Package org.sm.smtools.application

Class JStandardGUIApplication

java.lang.Object
java.awt.Component
java.awt.Container
java.awt.Window
java.awt.Frame
javax.swing.JFrame
org.sm.smtools.application.JStandardGUIApplication
All Implemented Interfaces:
java.awt.event.ActionListener, java.awt.event.ComponentListener, java.awt.event.WindowListener, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible, javax.swing.RootPaneContainer, javax.swing.WindowConstants
Direct Known Subclasses:
JDerivedGUIApplication
public class JStandardGUIApplication
extends javax.swing.JFrame
implements java.awt.event.ActionListener, java.awt.event.ComponentListener, java.awt.event.WindowListener
The JStandardGUIApplication class provides a standard Swing based GUI framework.

By default, the JStandardGUIApplication class will result in the following GUI:

Typically, this JStandardGUIApplication is subclassed, with several methods overridden. These methods control the application's settings, the visual layout of its GUI, and the actions that need to be taken upon user input.

The overridable methods that setup the GUI's form and behaviour are:

Note that by default, a "General" menu is present, which looks as follows:

Note that if the underlying operating system allows for minimisation to the system tray, then this options becomes available in the menu.

As the application is ran, the global system Registry is read from the file registry.ser (and stored back to file at the end).

When the user wants to quit the application, a confirmation dialog is shown:

Note that this confirmation can be skipped if DevelopMode.isActivated() is true.

Version:
20/03/2020
Author:
Sven Maerivoet
See Also:
Serialized Form

  • Nested Class Summary

    Nested classes/interfaces inherited from class javax.swing.JFrame

    javax.swing.JFrame.AccessibleJFrame

    Nested classes/interfaces inherited from class java.awt.Frame

    java.awt.Frame.AccessibleAWTFrame

    Nested classes/interfaces inherited from class java.awt.Window

    java.awt.Window.AccessibleAWTWindow, java.awt.Window.Type

    Nested classes/interfaces inherited from class java.awt.Container

    java.awt.Container.AccessibleAWTContainer

    Nested classes/interfaces inherited from class java.awt.Component

    java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

  • Field Summary

    Fields
    Modifier and Type Field Description
    protected JARResources fResources
    Access point to the application's own resources.
    protected static int kAutoSizeGUI
    Useful constant to specify that the GUI should fit exactly around its components.
    protected static int kFullScreenGUI
    Useful constant to specify that the GUI should have full screen size.
    protected static java.lang.String klafGTK
    Useful constant for specifying the GTK look-and-feel.
    protected static java.lang.String klafMac
    Useful constant for specifying the Mac OS X look-and-feel.
    protected static java.lang.String klafMetal
    Useful constant for specifying Java's Metal look-and-feel.
    protected static java.lang.String klafMotif
    Useful constant for specifying the Motif look-and-feel.
    protected static java.lang.String klafNimbus
    Useful constant for specifying Java's Nimbus look-and-feel.
    protected static java.lang.String klafQuaqua
    Useful constant for specifying the Quaqua (Mac OS X emulation) look-and-feel.
    protected static java.lang.String klafSystem
    Useful constant for specifying the current platform's look-and-feel.
    protected static java.lang.String klafWindows
    Useful constant for specifying the Microsoft Windows look-and-feel.
    protected static java.lang.String klafWindowsClassic
    Useful constant for specifying the Microsoft Windows Classic look-and-feel.

    Fields inherited from class javax.swing.JFrame

    accessibleContext, rootPane, rootPaneCheckingEnabled

    Fields inherited from class java.awt.Frame

    ICONIFIED, MAXIMIZED_BOTH, MAXIMIZED_HORIZ, MAXIMIZED_VERT, NORMAL

    Fields inherited from class java.awt.Component

    BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

    Fields inherited from interface java.awt.image.ImageObserver

    ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

    Fields inherited from interface javax.swing.WindowConstants

    DISPOSE_ON_CLOSE, DO_NOTHING_ON_CLOSE, EXIT_ON_CLOSE, HIDE_ON_CLOSE

  • Constructor Summary

    Constructors
    Constructor Description
    JStandardGUIApplication​(java.lang.String[] argv, java.lang.Object[] parameters)
    Constructs a JStandardGUIApplication object.

  • Method Summary

    Modifier and Type Method Description
    protected void abortApplication​(java.lang.String abortMessage, boolean... appendLocale)
    Immediately aborts the running application.
    void actionPerformed​(java.awt.event.ActionEvent e)
    The GUI's action listener.
    protected void addGUIToolBarButton​(javax.swing.AbstractButton button, java.lang.String toolTipText, java.lang.String actionCommand, java.awt.event.ActionListener actionListener)
    Helper method to add a button to the GUI's tool bar.
    protected void addGUIToolBarComponent​(javax.swing.JComponent component, java.lang.String toolTipText)
    Helper method to add an arbitrary component to the GUI's tool bar.
    protected void addGUIToolBarSeparator()
    Helper method to add a separator to the GUI's tool bar.
    void beep()
    Emits an audible beep.
    void componentHidden​(java.awt.event.ComponentEvent e)
    This method does nothing.
    void componentMoved​(java.awt.event.ComponentEvent e)
    This method does nothing.
    void componentResized​(java.awt.event.ComponentEvent e)
    This method calls the callback function guiWindowResized().
    void componentShown​(java.awt.event.ComponentEvent e)
    This method does nothing.
    protected javax.swing.JCheckBoxMenuItem constructGUICheckBoxMenuItem​(java.lang.String checkBoxMenuItemKey)
    Helper method for constructing a check box menu item object; a mnemonic is used if it is found.
    Note that the I18NL10N database is automatically used.
    protected javax.swing.JCheckBoxMenuItem constructGUICheckBoxMenuItem​(java.lang.String checkBoxMenuItemKey, boolean useMnemonic)
    Helper method for constructing a check box menu item object; an optional mnemonic can be used if it is found.
    Note that the I18NL10N database is automatically used.
    protected javax.swing.JMenuItem constructGUIMenuItem​(java.lang.String menuItemKey)
    Helper method constructing a menu item object; a mnemonic is used if it is found.
    Note that the I18NL10N database is automatically used.
    protected javax.swing.JMenuItem constructGUIMenuItem​(java.lang.String menuItemKey, boolean useMnemonic)
    Helper method for constructing a menu item object; an optional mnemonic can be used if it is found.
    Note that the I18NL10N database is automatically used.
    protected javax.swing.JRadioButtonMenuItem constructGUIRadioButtonMenuItem​(java.lang.String radioButtonMenuItemKey)
    Helper method for constructing a radio button menu item object; a mnemonic is used if it is found.
    Note that the I18NL10N database is automatically used.
    protected javax.swing.JRadioButtonMenuItem constructGUIRadioButtonMenuItem​(java.lang.String radioButtonMenuItemKey, boolean useMnemonic)
    Helper method for constructing a radio button menu item object; an optional mnemonic can be used if it is found.
    Note that the I18NL10N database is automatically used.
    protected void createGUIToolBar()
    Sets up the GUI's tool bar.
    protected java.lang.String getApplicationLocalePrefix()
    Sets up the path and prefix names to the application's locale databases, for example:
    protected int getApplicationRequiredMajorJavaVersion()
    Sets up the required major version of the Java runtime engine that wants to run this application.
    protected int getApplicationRequiredMinorJavaVersion()
    Sets up the required minor version of the Java runtime engine that wants to run this application.
    protected java.lang.String getApplicationResourceArchiveFilename()
    Sets up the filename of the JAR or ZIP file containing the application's resources.
    protected void getGUIContentPane​(javax.swing.JPanel contentPane)
    Sets up the GUI's content pane.
    protected javax.swing.JPanel getGUIGlassPane()
    Sets up a constructed glass pane.
    protected java.awt.Image getGUIIcon()
    Sets up the Image containing the GUI's icon.
    protected java.lang.String getGUIInitialLookAndFeel()
    Sets up the application's initial look-and-feel.
    protected java.awt.Dimension getGUIInitialSize()
    Sets up the GUI's initial size on the screen.
    protected JGUISounds.EGUISoundSet getGUIInitialSoundSet()
    Sets up the application's initial GUI sound set.
    protected java.util.ArrayList<javax.swing.JMenu> getGUIMenus()
    Sets up custom menus.
    protected javax.swing.JMenu getGUIRightHandMenu()
    Sets up a custom right hand menu (e.g., a "Help" menu).
    java.awt.Insets getGUIScreenInsets()
    Returns the screen insets.
    java.awt.Dimension getGUIScreenSize()
    Returns the screen size.
    protected JSplashScreen getGUISplashScreen()
    Returns a handle to the GUI's splash screen.
    protected javax.swing.JLabel getGUISplashScreenContent()
    Sets up a JLabel containing the splash screen's custom content.
    protected java.io.InputStream getGUISplashScreenSound()
    Sets up the MP3 sound to play during the splash screen.
    protected JStatusBar getGUIStatusBar()
    Getter method for the status bar.
    protected java.util.ArrayList<javax.swing.JLabel> getGUIStatusBarCustomLabels()
    Sets up custom labels that are shown to the right hand side of the status bar.
    protected boolean getGUISystemSoundsEnabledOnStartup()
    Specifies whether or not the GUI's system sounds should be enabled at startup.
    protected java.lang.String getGUITitle()
    Sets up the GUI's window title.
    protected javax.swing.ActionMap getGUIToolBarActionMap()
    Helper method to retrieve the GUI's tool bar's action map.
    protected javax.swing.InputMap getGUIToolBarInputMap()
    Helper method to retrieve the GUI's tool bar's input map.
    protected java.lang.String getGUIToolBarTitle()
    Returns the GUI's tool bar's title.
    protected void guiLookAndFeelChanged()
    A callback method for when the look-and-feel has changed.
    protected void guiWindowResized()
    A callback function for when the GUI's window is resized.
    protected boolean hasGUIAboutBox()
    Returns a boolean indicating whether or not a custom about box is available.
    void hideGUIMouseCursor()
    Emulates hiding the mouse cursor.
    protected void hideGUIToolBar()
    Helper method to hide the GUI's tool bar.
    protected void initialiseApplication​(java.lang.Object[] parameters)
    Allows custom initialisation of the subclass's member fields.
    protected boolean isGUIClockEnabled()
    Sets up whether or not a clock (HH:MM:SS) should be shown at the right of the menubar.
    protected boolean isGUIMinimiseToSystemTrayAllowed()
    Sets up whether or not the application is allowed to minimise to the system tray (if supported by the host platform).
    protected boolean isGUIRepaintedWhenResizing()
    Sets up whether or not the GUI should always be repainted when the window is resized.
    protected boolean isGUIResizable()
    Sets up whether or not the GUI's window should be resizable.
    protected boolean isGUIStatusBarEnabled()
    Sets up whether or not the status bar should be shown at the bottom of the application's window.
    protected boolean isGUIToolBarFloatable()
    Returns if the GUI's tool bar's can float freely.
    protected void loadApplicationRegistry()
    Allows loading of custom registry values.
    static void main​(java.lang.String[] argv)
    The application's main method.
    protected boolean parseApplicationParameter​(int paramNr, java.lang.String parameter)
    Allows parsing of custom command-line parameters.
    void setGUIDynamicLayout​(boolean dynamicLayout)
    Sets the use of dynamic layout (i.e., real-time repainting of the JFrame's components when resizing).
    protected void showApplicationParameterWarning​(int paramNr, java.lang.String parameter, java.lang.String message)
    Logs a textual warning message.
    protected void showGUIAboutBox()
    Shows a custom about box.
    protected void showGUIDefaultMouseCursor()
    Shows the default mouse cursor.
    protected void showGUIToolBar()
    Helper method to show the GUI's tool bar.
    protected void showGUIWaitMouseCursor()
    Shows the wait mouse cursor.
    protected void shutdownApplication()
    Allows custom clean-up when the application is shutting down.
    void windowActivated​(java.awt.event.WindowEvent e)
    This method does nothing.
    void windowClosed​(java.awt.event.WindowEvent e)
    This method does nothing.
    void windowClosing​(java.awt.event.WindowEvent e)
    Gracefully ends the application by running the shutdown sequence and saving the registry.
    void windowDeactivated​(java.awt.event.WindowEvent e)
    This method does nothing.
    void windowDeiconified​(java.awt.event.WindowEvent e)
    Plays a sound.
    void windowIconified​(java.awt.event.WindowEvent e)
    Plays a sound and if necessary creates an icon in the system tray.
    void windowOpened​(java.awt.event.WindowEvent e)
    This method does nothing.

    Methods inherited from class javax.swing.JFrame

    addImpl, createRootPane, frameInit, getAccessibleContext, getContentPane, getDefaultCloseOperation, getGlassPane, getGraphics, getJMenuBar, getLayeredPane, getRootPane, getTransferHandler, isDefaultLookAndFeelDecorated, isRootPaneCheckingEnabled, paramString, processWindowEvent, remove, repaint, setContentPane, setDefaultCloseOperation, setDefaultLookAndFeelDecorated, setGlassPane, setIconImage, setJMenuBar, setLayeredPane, setLayout, setRootPane, setRootPaneCheckingEnabled, setTransferHandler, update

    Methods inherited from class java.awt.Frame

    addNotify, getExtendedState, getFrames, getIconImage, getMaximizedBounds, getMenuBar, getState, getTitle, isResizable, isUndecorated, remove, removeNotify, setBackground, setExtendedState, setMaximizedBounds, setMenuBar, setOpacity, setResizable, setShape, setState, setTitle, setUndecorated

    Methods inherited from class java.awt.Window

    addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, createBufferStrategy, createBufferStrategy, dispose, getBackground, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getIconImages, getInputContext, getListeners, getLocale, getModalExclusionType, getMostRecentFocusOwner, getOpacity, getOwnedWindows, getOwner, getOwnerlessWindows, getShape, getToolkit, getType, getWarningString, getWindowFocusListeners, getWindowListeners, getWindows, getWindowStateListeners, isActive, isAlwaysOnTop, isAlwaysOnTopSupported, isAutoRequestFocus, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isOpaque, isShowing, isValidateRoot, pack, paint, processEvent, processWindowFocusEvent, processWindowStateEvent, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, setAlwaysOnTop, setAutoRequestFocus, setBounds, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setIconImages, setLocation, setLocation, setLocationByPlatform, setLocationRelativeTo, setMinimumSize, setModalExclusionType, setSize, setSize, setType, setVisible, toBack, toFront

    Methods inherited from class java.awt.Container

    add, add, add, add, add, addContainerListener, applyComponentOrientation, areFocusTraversalKeysSet, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, list, list, paintComponents, print, printComponents, processContainerEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, transferFocusDownCycle, validate, validateTree

    Methods inherited from class java.awt.Component

    add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getTreeLock, getWidth, getX, getY, hasFocus, imageUpdate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isValid, isVisible, list, list, list, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, requestFocusInWindow, revalidate, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setMaximumSize, setMixingCutoutShape, setName, setPreferredSize, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.awt.MenuContainer

    getFont

  • Field Details

    • kAutoSizeGUI

      protected static final int kAutoSizeGUI
      Useful constant to specify that the GUI should fit exactly around its components.
      See Also:
      Constant Field Values

    • kFullScreenGUI

      protected static final int kFullScreenGUI
      Useful constant to specify that the GUI should have full screen size.

      Note that the maximised state of a window is currently not yet supported due to Java lack thereof.

      See Also:
      Constant Field Values

    • klafGTK

      protected static final java.lang.String klafGTK
      Useful constant for specifying the GTK look-and-feel.
      See Also:
      Constant Field Values

    • klafMac

      protected static final java.lang.String klafMac
      Useful constant for specifying the Mac OS X look-and-feel.
      See Also:
      Constant Field Values

    • klafMetal

      protected static final java.lang.String klafMetal
      Useful constant for specifying Java's Metal look-and-feel.
      See Also:
      Constant Field Values

    • klafMotif

      protected static final java.lang.String klafMotif
      Useful constant for specifying the Motif look-and-feel.
      See Also:
      Constant Field Values

    • klafNimbus

      protected static final java.lang.String klafNimbus
      Useful constant for specifying Java's Nimbus look-and-feel.
      See Also:
      Constant Field Values

    • klafQuaqua

      protected static final java.lang.String klafQuaqua
      Useful constant for specifying the Quaqua (Mac OS X emulation) look-and-feel.
      See Also:
      Constant Field Values

    • klafWindows

      protected static final java.lang.String klafWindows
      Useful constant for specifying the Microsoft Windows look-and-feel.
      See Also:
      Constant Field Values

    • klafWindowsClassic

      protected static final java.lang.String klafWindowsClassic
      Useful constant for specifying the Microsoft Windows Classic look-and-feel.
      See Also:
      Constant Field Values

    • klafSystem

      protected static final java.lang.String klafSystem
      Useful constant for specifying the current platform's look-and-feel.
      See Also:
      Constant Field Values

    • fResources

      protected JARResources fResources
      Access point to the application's own resources.

  • Constructor Details

  • Method Details

    • actionPerformed

      public void actionPerformed​(java.awt.event.ActionEvent e)
      The GUI's action listener.

      Note that when overriding this method in a subclass, its parent should explicitly be called in order to guarantee the correct default processing of the user's input: 

         super.actionPerformed(e);
   // rest of method's code
      Specified by:
      actionPerformed in interface java.awt.event.ActionListener
      Parameters:
      e - the ActionEvent that is received

    • componentMoved

      public final void componentMoved​(java.awt.event.ComponentEvent e)
      This method does nothing.

      Note that this method cannot be overridden!

      Specified by:
      componentMoved in interface java.awt.event.ComponentListener
      Parameters:
      e - the WindowEvent that is received

    • componentShown

      public final void componentShown​(java.awt.event.ComponentEvent e)
      This method does nothing.

      Note that this method cannot be overridden!

      Specified by:
      componentShown in interface java.awt.event.ComponentListener
      Parameters:
      e - the WindowEvent that is received

    • componentHidden

      public final void componentHidden​(java.awt.event.ComponentEvent e)
      This method does nothing.

      Note that this method cannot be overridden!

      Specified by:
      componentHidden in interface java.awt.event.ComponentListener
      Parameters:
      e - the WindowEvent that is received

    • componentResized

      public final void componentResized​(java.awt.event.ComponentEvent e)
      This method calls the callback function guiWindowResized().

      Note that this method cannot be overridden!

      Specified by:
      componentResized in interface java.awt.event.ComponentListener
      Parameters:
      e - the WindowEvent that is received

    • windowActivated

      public void windowActivated​(java.awt.event.WindowEvent e)
      This method does nothing.
      Specified by:
      windowActivated in interface java.awt.event.WindowListener
      Parameters:
      e - the WindowEvent that is received

    • windowClosed

      public void windowClosed​(java.awt.event.WindowEvent e)
      This method does nothing.
      Specified by:
      windowClosed in interface java.awt.event.WindowListener
      Parameters:
      e - the WindowEvent that is received

    • windowClosing

      public final void windowClosing​(java.awt.event.WindowEvent e)
      Gracefully ends the application by running the shutdown sequence and saving the registry.

      Note that this method cannot be overridden!

      Specified by:
      windowClosing in interface java.awt.event.WindowListener
      Parameters:
      e - the WindowEvent that is received

    • windowDeactivated

      public void windowDeactivated​(java.awt.event.WindowEvent e)
      This method does nothing.
      Specified by:
      windowDeactivated in interface java.awt.event.WindowListener
      Parameters:
      e - the WindowEvent that is received

    • windowDeiconified

      public final void windowDeiconified​(java.awt.event.WindowEvent e)
      Plays a sound.

      Note that this method cannot be overridden!

      Specified by:
      windowDeiconified in interface java.awt.event.WindowListener
      Parameters:
      e - the WindowEvent that is received

    • windowIconified

      public final void windowIconified​(java.awt.event.WindowEvent e)
      Plays a sound and if necessary creates an icon in the system tray.

      Note that this method cannot be overridden!

      Specified by:
      windowIconified in interface java.awt.event.WindowListener
      Parameters:
      e - the WindowEvent that is received

    • windowOpened

      public void windowOpened​(java.awt.event.WindowEvent e)
      This method does nothing.
      Specified by:
      windowOpened in interface java.awt.event.WindowListener
      Parameters:
      e - the WindowEvent that is received

    • main

      public static void main​(java.lang.String[] argv)
      The application's main method.

      Note that this method should be overridden by a derived subclass: 

         public static void main(String[] argv)
   {
     DerivedGUIApplication derivedGUIApplication = new DerivedGUIApplication(argv);
   }
      Parameters:
      argv - an array of strings containing the command-line parameters

    • beep

      public final void beep()
      Emits an audible beep.

    • showGUIDefaultMouseCursor

      protected final void showGUIDefaultMouseCursor()
      Shows the default mouse cursor.

    • showGUIWaitMouseCursor

      protected final void showGUIWaitMouseCursor()
      Shows the wait mouse cursor.

    • hideGUIMouseCursor

      public final void hideGUIMouseCursor()
      Emulates hiding the mouse cursor.

    • setGUIDynamicLayout

      public final void setGUIDynamicLayout​(boolean dynamicLayout)
      Sets the use of dynamic layout (i.e., real-time repainting of the JFrame's components when resizing).
      Parameters:
      dynamicLayout - a boolean indicating whether or not dynamic layout should be activated

    • getGUIScreenSize

      public final java.awt.Dimension getGUIScreenSize()
      Returns the screen size.
      Returns:
      the screen size

    • getGUIScreenInsets

      public final java.awt.Insets getGUIScreenInsets()
      Returns the screen insets.
      Returns:
      the screen insets

    • getApplicationRequiredMajorJavaVersion

      protected int getApplicationRequiredMajorJavaVersion()
      Sets up the required major version of the Java runtime engine that wants to run this application.

      The default is 1 (for JRE 1.8.0).

      Returns:
      the required major version of the Java runtime engine

    • getApplicationRequiredMinorJavaVersion

      protected int getApplicationRequiredMinorJavaVersion()
      Sets up the required minor version of the Java runtime engine that wants to run this application.

      The default is 8 (for JRE 1.8.0).

      Returns:
      the required minor version of the Java runtime engine

    • getApplicationResourceArchiveFilename

      protected java.lang.String getApplicationResourceArchiveFilename()
      Sets up the filename of the JAR or ZIP file containing the application's resources.

      If null is specified, then the system ignores loading the application's resources.

      Returns:
      the filename of the archive (JAR or ZIP) containing the application's resources
      See Also:
      JARResources

    • getApplicationLocalePrefix

      protected java.lang.String getApplicationLocalePrefix()
      Sets up the path and prefix names to the application's locale databases, for example:
      "application-resources/locales/locale-"

      If null is specified, then the system ignores loading the application's locale databases.

      Returns:
      the path to the location of the application's locale databases
      See Also:
      I18NL10N

    • loadApplicationRegistry

      protected void loadApplicationRegistry()
      Allows loading of custom registry values. A typical code example looks like: 
         (at)SuppressWarnings("unchecked")
   
   // obtain a local reference to the system registry
   Registry systemRegistry = Registry.kINSTANCE;
   
   // load last opened folder
   Object lastOpenedFolderEntry = systemRegistry.getObject("fLastOpenedFolder");
   if (lastOpenedFolderEntry != null) {
     fLastOpenedFolder = (String) lastOpenedFolderEntry;
   }
   else {
     // setup and store default as the current folder
     fLastOpenedFolder = ".";
     systemRegistry.addObject("fLastOpenedFolder",fLastOpenedFolder);
   }

    • initialiseApplication

      protected void initialiseApplication​(java.lang.Object[] parameters)
      Allows custom initialisation of the subclass's member fields.

      The parameters in the Object[] array are passed through the class's constructor (see JStandardGUIApplication(String[],Object[])). They are typically specified as new Object[] {object1,object2}.

      Parameters:
      parameters - an array of Objects

    • shutdownApplication

      protected void shutdownApplication()
      Allows custom clean-up when the application is shutting down. A typical code example could include: 
         // obtain a local reference to the system registry
   Registry systemRegistry = Registry.kINSTANCE;
   
   // update registry
   systemRegistry.addObject("fLastOpenedFolder",fLastOpenedFolder);
      Note that the shutdown() sequence is not ran in case of a fatal error resulting in early abort.
      See Also:
      abortApplication(String,boolean...)

    • parseApplicationParameter

      protected boolean parseApplicationParameter​(int paramNr, java.lang.String parameter)
      Allows parsing of custom command-line parameters.

      A derived subclass typically overrides this method to parse all its custom command-line parameters.

      Note that if an error occurs during parsing, the showApplicationParameterWarning(int,String,String) method should be called with the appropriate parameters.

      The following example shows the parsing of one custom parameter (with a custom option): 

         final String kCustomParameter = "PARAMETER";
   final String kCustomOption    = "OPTION";
   
   String upperCaseParameter = parameter.toUpperCase();
   
   // parse parameter
   if (upperCaseParameter.startsWith(kCustomParameter + "=")) {
   
     String upperCaseOption = upperCaseParameter.substring(kCustomParameter.length() + 1);
     // parse option
     if (upperCaseOption.equalsIgnoreCase(kCustomOption)) {
       // take action as parameter is parsed
     }
     else {
       showParameterWarning(paramNr,parameter,"not a valid option");
     }
     
     // indicate that parameter was valid
     return true;
   }
   else {
     // indicate that parameter is unknown
     return false;
   }
      Parameters:
      paramNr - the number of the parameter that is being parsed
      parameter - the unmodified parameter as specified on the command-line
      Returns:
      true if the parameter was parsed successfully, false otherwise
      See Also:
      showApplicationParameterWarning(int,String,String)

    • showApplicationParameterWarning

      protected final void showApplicationParameterWarning​(int paramNr, java.lang.String parameter, java.lang.String message)
      Logs a textual warning message.
      Parameters:
      paramNr - the number of the parameter that failed to get parsed
      parameter - the unmodified parameter as specified on the command-line
      message - the warning message to log
      See Also:
      parseApplicationParameter(int,String)

    • getGUISplashScreenContent

      protected javax.swing.JLabel getGUISplashScreenContent()
      Sets up a JLabel containing the splash screen's custom content.

      See JSplashScreen for more information regarding the splash screen.

      Returns:
      a JLabel containing the splash screen's custom content
      See Also:
      JSplashScreen

    • getGUISplashScreenSound

      protected java.io.InputStream getGUISplashScreenSound()
      Sets up the MP3 sound to play during the splash screen.

      See JSplashScreen for more information regarding the splash screen and MP3Player for playing MP3 sounds.

      Returns:
      the MP3 sound to play during the splash screen
      See Also:
      JSplashScreen, MP3Player

    • getGUISplashScreen

      protected final JSplashScreen getGUISplashScreen()
      Returns a handle to the GUI's splash screen.
      Returns:
      a handle to the GUI's splash screen
      See Also:
      JSplashScreen

    • getGUIInitialLookAndFeel

      protected java.lang.String getGUIInitialLookAndFeel()
      Sets up the application's initial look-and-feel.

      The possible values that can be returned are:

      Note that this method returns the current platform's look-and-feel by default.

      Returns:
      the application's initial look-and-feel

    • getGUIInitialSoundSet

      protected JGUISounds.EGUISoundSet getGUIInitialSoundSet()
      Sets up the application's initial GUI sound set.

      The possible values that can be returned are (see also JGUISounds):

      • the LCARS sound set
      • the Apple sound set
      • the space sound set

      Note that this method returns the LCARS GUI sound set by default.

      Returns:
      the application's initial GUI sound set

    • getGUISystemSoundsEnabledOnStartup

      protected boolean getGUISystemSoundsEnabledOnStartup()
      Specifies whether or not the GUI's system sounds should be enabled at startup.

      This method returns true by default.

      Returns:
      a boolean indicating whether or not the GUI's system sounds should be enabled at startup

    • guiLookAndFeelChanged

      protected void guiLookAndFeelChanged()
      A callback method for when the look-and-feel has changed.

    • getGUIInitialSize

      protected java.awt.Dimension getGUIInitialSize()
      Sets up the GUI's initial size on the screen.

      A derived subclass should return a Dimension object containing the initial width and height of the GUI's window. Their values are expressed in pixels, but the following two special values are also accepted:

      An example: 

         return (new Dimension(JStandardGUIApplication.kFullScreenGUI,250));
      which specifies a GUI with full screen width and 250 pixels height.
      Returns:
      the GUI's initial size on the screen as a Dimension object

    • isGUIResizable

      protected boolean isGUIResizable()
      Sets up whether or not the GUI's window should be resizable.

      This method returns true by default.

      Returns:
      true if the GUI's window should be resizable, false if it should be fixed size

    • isGUIRepaintedWhenResizing

      protected boolean isGUIRepaintedWhenResizing()
      Sets up whether or not the GUI should always be repainted when the window is resized. This only works if the host platform supports it.

      This method returns true by default.

      Returns:
      true if the GUI should be repainted when the window is resized

    • guiWindowResized

      protected void guiWindowResized()
      A callback function for when the GUI's window is resized.

    • getGUIIcon

      protected java.awt.Image getGUIIcon()
      Sets up the Image containing the GUI's icon.

      The Image should be a JPG-file, 32x32 pixels with 24-bit colourdepth (i.e., true colour).

      Returns:
      the Image containing the GUI's icon

    • getGUITitle

      protected java.lang.String getGUITitle()
      Sets up the GUI's window title.
      Returns:
      the GUI's window title

    • getGUIContentPane

      protected void getGUIContentPane​(javax.swing.JPanel contentPane)
      Sets up the GUI's content pane.

      A derived subclass typically overrides this method. The subclass can operate on the given contentPane parameter (which is initialised, i.e., not null, by default).

      A subclass thus sets the content pane's layout managers, adds components to it, ...

      Parameters:
      contentPane - the GUI's main content pane to modify

    • getGUIToolBarTitle

      protected java.lang.String getGUIToolBarTitle()
      Returns the GUI's tool bar's title.
      Returns:
      the GUI's tool bar's title

    • isGUIToolBarFloatable

      protected boolean isGUIToolBarFloatable()
      Returns if the GUI's tool bar's can float freely.

      By default, this method returns true.

      Returns:
      a boolean indicating whether or not the GUI's tool bar can float freely

    • createGUIToolBar

      protected void createGUIToolBar()
      Sets up the GUI's tool bar.

      A derived subclass typically overrides this method. The subclass can add buttons to the tool bar via the addGUIToolBarButton(AbstractButton,String,String,ActionListener) and addGUIToolBarSeparator() methods.

      This would typically look like the following: 

         String kActionCommandMenuItemXXX = "xxx";
   String kActionCommandMenuItemYYY = "yyy";
   JButton button1 = new JButton(new ImageIcon(fResources.getImage("application-resources/icons/load-parameters-icon.png")));
   JButton button2 = new JButton("Button #2");
   
   addToolBarButton(
     button1,
     I18NL10N.kINSTANCE.translate(kActionCommandMenuItemXXX),
     kActionCommandMenuItemXXX,this);
     
   addToolBarSeparator();
     
   addToolBarButton(
     button2,
     I18NL10N.kINSTANCE.translate(kActionCommandMenuItemYYY),
     kActionCommandMenuItemYYY,this);

    • addGUIToolBarButton

      protected final void addGUIToolBarButton​(javax.swing.AbstractButton button, java.lang.String toolTipText, java.lang.String actionCommand, java.awt.event.ActionListener actionListener)
      Helper method to add a button to the GUI's tool bar.
      Parameters:
      button - the button to add
      toolTipText - the tool tip text associated with the button
      actionCommand - the action command of the button
      actionListener - the action listener for the button (usually this)

    • addGUIToolBarComponent

      protected final void addGUIToolBarComponent​(javax.swing.JComponent component, java.lang.String toolTipText)
      Helper method to add an arbitrary component to the GUI's tool bar.
      Parameters:
      component - the component to add
      toolTipText - the tool tip text associated with the component

    • addGUIToolBarSeparator

      protected final void addGUIToolBarSeparator()
      Helper method to add a separator to the GUI's tool bar.

    • showGUIToolBar

      protected final void showGUIToolBar()
      Helper method to show the GUI's tool bar.

      Note that the GUI's tool bar is only shown if it contains any content.

    • hideGUIToolBar

      protected final void hideGUIToolBar()
      Helper method to hide the GUI's tool bar.

    • getGUIToolBarInputMap

      protected final javax.swing.InputMap getGUIToolBarInputMap()
      Helper method to retrieve the GUI's tool bar's input map.
      Returns:
      the GUI's tool bar's input map

    • getGUIToolBarActionMap

      protected final javax.swing.ActionMap getGUIToolBarActionMap()
      Helper method to retrieve the GUI's tool bar's action map.
      Returns:
      the GUI's tool bar's action map

    • getGUIMenus

      protected java.util.ArrayList<javax.swing.JMenu> getGUIMenus()
      Sets up custom menus.

      By default, the application already contains a "General" menu containing access to the optional about box, setting the GUI's look and feel and getting confirmation when the user wants to quit the application.

      Note that this method returns null by default.

      Returns:
      an ArrayList of menus
      See Also:
      getGUIRightHandMenu()

    • getGUIRightHandMenu

      protected javax.swing.JMenu getGUIRightHandMenu()
      Sets up a custom right hand menu (e.g., a "Help" menu).

      Note that this method returns null by default.

      Returns:
      a menu used in the right part of the menubar
      See Also:
      getGUIMenus()

    • constructGUIMenuItem

      protected final javax.swing.JMenuItem constructGUIMenuItem​(java.lang.String menuItemKey, boolean useMnemonic)
      Helper method for constructing a menu item object; an optional mnemonic can be used if it is found.
      Note that the I18NL10N database is automatically used.

      Note that this method cannot be overridden!

      Parameters:
      menuItemKey - the key of the menu item
      useMnemonic - a flag indicating whether to use a mnemonic or not
      Returns:
      a menu item object

    • constructGUIMenuItem

      protected final javax.swing.JMenuItem constructGUIMenuItem​(java.lang.String menuItemKey)
      Helper method constructing a menu item object; a mnemonic is used if it is found.
      Note that the I18NL10N database is automatically used.

      Note that this method cannot be overridden!

      Parameters:
      menuItemKey - the key of the menu item
      Returns:
      a menu item object

    • constructGUIRadioButtonMenuItem

      protected final javax.swing.JRadioButtonMenuItem constructGUIRadioButtonMenuItem​(java.lang.String radioButtonMenuItemKey, boolean useMnemonic)
      Helper method for constructing a radio button menu item object; an optional mnemonic can be used if it is found.
      Note that the I18NL10N database is automatically used.

      Note that this method cannot be overridden!

      Parameters:
      radioButtonMenuItemKey - the key of the menu item
      useMnemonic - a flag indicating whether to use a mnemonic or not
      Returns:
      a radio button menu item object

    • constructGUIRadioButtonMenuItem

      protected final javax.swing.JRadioButtonMenuItem constructGUIRadioButtonMenuItem​(java.lang.String radioButtonMenuItemKey)
      Helper method for constructing a radio button menu item object; a mnemonic is used if it is found.
      Note that the I18NL10N database is automatically used.

      Note that this method cannot be overridden!

      Parameters:
      radioButtonMenuItemKey - the key of the menu item
      Returns:
      a radio button menu item object

    • constructGUICheckBoxMenuItem

      protected final javax.swing.JCheckBoxMenuItem constructGUICheckBoxMenuItem​(java.lang.String checkBoxMenuItemKey, boolean useMnemonic)
      Helper method for constructing a check box menu item object; an optional mnemonic can be used if it is found.
      Note that the I18NL10N database is automatically used.

      Note that this method cannot be overridden!

      Parameters:
      checkBoxMenuItemKey - the key of the menu item
      useMnemonic - a flag indicating whether to use a mnemonic or not
      Returns:
      a check box menu item object

    • constructGUICheckBoxMenuItem

      protected final javax.swing.JCheckBoxMenuItem constructGUICheckBoxMenuItem​(java.lang.String checkBoxMenuItemKey)
      Helper method for constructing a check box menu item object; a mnemonic is used if it is found.
      Note that the I18NL10N database is automatically used.

      Note that this method cannot be overridden!

      Parameters:
      checkBoxMenuItemKey - the key of the menu item
      Returns:
      a check box menu item object

    • getGUIStatusBarCustomLabels

      protected java.util.ArrayList<javax.swing.JLabel> getGUIStatusBarCustomLabels()
      Sets up custom labels that are shown to the right hand side of the status bar.
      Returns:
      an ArrayList of custom labels, or null if none are provided

    • isGUIStatusBarEnabled

      protected boolean isGUIStatusBarEnabled()
      Sets up whether or not the status bar should be shown at the bottom of the application's window.

      Note that this method returns true by default.

      Returns:
      whether or not the status bar should be shown at the bottom of the application's window

    • getGUIStatusBar

      protected final JStatusBar getGUIStatusBar()
      Getter method for the status bar.
      Returns:
      the status bar

    • getGUIGlassPane

      protected javax.swing.JPanel getGUIGlassPane()
      Sets up a constructed glass pane.

      An application will typically override this method and create its own glass pane object inside it after returning it.

      Returns:
      a constructed glass pane

    • isGUIClockEnabled

      protected boolean isGUIClockEnabled()
      Sets up whether or not a clock (HH:MM:SS) should be shown at the right of the menubar.

      Note that this method returns true by default.

      Returns:
      whether or not a clock (HH:MM:SS) should be shown at the right of the menubar

    • hasGUIAboutBox

      protected boolean hasGUIAboutBox()
      Returns a boolean indicating whether or not a custom about box is available.

      Note that this method returns false by default, indicating that no custom about box is available.

      Returns:
      a boolean indicating whether or not a custom about box is available
      See Also:
      JAboutBox

    • showGUIAboutBox

      protected void showGUIAboutBox()
      Shows a custom about box.
      See Also:
      JAboutBox

    • isGUIMinimiseToSystemTrayAllowed

      protected boolean isGUIMinimiseToSystemTrayAllowed()
      Sets up whether or not the application is allowed to minimise to the system tray (if supported by the host platform).

      Note that this method returns true by default.

      Returns:
      whether or not the application is allowed to minimise to the system tray

    • abortApplication

      protected final void abortApplication​(java.lang.String abortMessage, boolean... appendLocale)
      Immediately aborts the running application.
      Parameters:
      abortMessage - the message to display when aborting
      appendLocale - optional argument that, when set to true, appends a localised message that the application is aborted