001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.tools;
003
004import java.io.File;
005import java.io.IOException;
006import java.security.KeyStore;
007import java.security.KeyStoreException;
008import java.security.NoSuchAlgorithmException;
009import java.security.cert.CertificateException;
010
011/**
012 * This interface allows platform (operating system) dependent code
013 * to be bundled into self-contained classes.
014 * @since 1023
015 */
016public interface PlatformHook {
017
018    /**
019      * The preStartupHook will be called extremly early. It is
020      * guaranteed to be called before the GUI setup has started.
021      *
022      * Reason: On OSX we need to inform the Swing libraries
023      * that we want to be integrated with the OS before we setup our GUI.
024      */
025    public void preStartupHook();
026    
027    /**
028      * The afterPrefStartupHook will be called early, but after
029      * the preferences have been loaded and basic processing of
030      * command line arguments is finished. 
031      * It is guaranteed to be called before the GUI setup has started.
032      */
033    public void afterPrefStartupHook();
034
035    /**
036      * The startupHook will be called early, but after the GUI
037      * setup has started.
038      *
039      * Reason: On OSX we need to register some callbacks with the
040      * OS, so we'll receive events from the system menu.
041      */
042    public void startupHook();
043
044    /**
045      * The openURL hook will be used to open an URL in the
046      * default web browser.
047     * @param url The URL to open
048     * @throws IOException if any I/O error occurs
049      */
050    public void openUrl(String url) throws IOException;
051
052    /**
053      * The initSystemShortcuts hook will be called by the
054      * Shortcut class after the modifier groups have been read
055      * from the config, but before any shortcuts are read from
056      * it or registered from within the application.
057      *
058      * Plese note that you are not allowed to register any
059      * shortuts from this hook, but only "systemCuts"!
060      *
061      * BTW: SystemCuts should be named "system:<whatever>",
062      * and it'd be best if sou'd recycle the names already used
063      * by the Windows and OSX hooks. Especially the later has
064      * really many of them.
065      *
066      * You should also register any and all shortcuts that the
067      * operation system handles itself to block JOSM from trying
068      * to use them---as that would just not work. Call setAutomatic
069      * on them to prevent the keyboard preferences from allowing the
070      * user to change them.
071      */
072    public void initSystemShortcuts();
073
074    /**
075      * The makeTooltip hook will be called whenever a tooltip for
076      * a menu or button is created.
077      *
078      * Tooltips are usually not system dependent, unless the
079      * JVM is too dumb to provide correct names for all the keys.
080      *
081      * Another reason not to use the implementation in the *nix
082      * hook are LAFs that don't understand HTML, such as the OSX LAFs.
083      *
084     * @param name Tooltip text to display
085     * @param sc Shortcut associated (to display accelerator between parenthesis)
086     * @return Full tooltip text (name + accelerator)
087      */
088    public String makeTooltip(String name, Shortcut sc);
089
090    /**
091     * Returns the default LAF to be used on this platform to look almost as a native application.
092     * @return The default native LAF for this platform
093     */
094    public String getDefaultStyle();
095
096    /**
097     * Determines if the platform allows full-screen.
098     * @return {@code true} if full screen is allowed, {@code false} otherwise
099     */
100    public boolean canFullscreen();
101
102    /**
103     * Renames a file.
104     * @param from Source file
105     * @param to Target file
106     * @return {@code true} if the file has been renamed, {@code false} otherwise
107     */
108    public boolean rename(File from, File to);
109
110    /**
111     * Returns a detailed OS description (at least family + version).
112     * @return A detailed OS description.
113     * @since 5850
114     */
115    public String getOSDescription();
116
117    /**
118     * Setup system keystore to add JOSM HTTPS certificate (for remote control).
119     * @param entryAlias The entry alias to use
120     * @param trustedCert the JOSM certificate for localhost
121     * @return {@code true} if something has changed as a result of the call (certificate installation, etc.)
122     * @throws KeyStoreException in case of error
123     * @throws IOException in case of error
124     * @throws CertificateException in case of error
125     * @throws NoSuchAlgorithmException in case of error
126     * @since 7343
127     */
128    public boolean setupHttpsCertificate(String entryAlias, KeyStore.TrustedCertificateEntry trustedCert)
129            throws KeyStoreException, NoSuchAlgorithmException, CertificateException, IOException;
130
131    /**
132     * Returns the platform-dependent default cache directory.
133     * @return the platform-dependent default cache directory
134     * @since 7829
135     */
136    public File getDefaultCacheDirectory();
137
138    /**
139     * Returns the platform-dependent default preferences directory.
140     * @return the platform-dependent default preferences directory
141     * @since 7831
142     */
143    public File getDefaultPrefDirectory();
144
145    /**
146     * Returns the platform-dependent default user data directory.
147     * @return the platform-dependent default user data directory
148     * @since 7834
149     */
150    public File getDefaultUserDataDirectory();
151}