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