001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.tools;
003
004import java.io.File;
005import java.io.IOException;
006
007/**
008 * This interface allows platform (operating system) dependent code
009 * to be bundled into self-contained classes.
010 * @since 1023
011 */
012public interface PlatformHook {
013    
014    /**
015      * The preStartupHook will be called extremly early. It is
016      * guaranteed to be called before the GUI setup has started.
017      *
018      * Reason: On OSX we need to inform the Swing libraries
019      * that we want to be integrated with the OS before we setup our GUI.
020      */
021    public void preStartupHook();
022
023    /**
024      * The startupHook will be called early, but after the GUI
025      * setup has started.
026      *
027      * Reason: On OSX we need to register some callbacks with the
028      * OS, so we'll receive events from the system menu.
029      */
030    public void startupHook();
031
032    /**
033      * The openURL hook will be used to open an URL in the
034      * default web browser.
035     * @param url The URL to open
036     * @throws IOException if any I/O error occurs
037      */
038    public void openUrl(String url) throws IOException;
039
040    /**
041      * The initSystemShortcuts hook will be called by the
042      * Shortcut class after the modifier groups have been read
043      * from the config, but before any shortcuts are read from
044      * it or registered from within the application.
045      *
046      * Plese note that you are not allowed to register any
047      * shortuts from this hook, but only "systemCuts"!
048      *
049      * BTW: SystemCuts should be named "system:<whatever>",
050      * and it'd be best if sou'd recycle the names already used
051      * by the Windows and OSX hooks. Especially the later has
052      * really many of them.
053      *
054      * You should also register any and all shortcuts that the
055      * operation system handles itself to block JOSM from trying
056      * to use them---as that would just not work. Call setAutomatic
057      * on them to prevent the keyboard preferences from allowing the
058      * user to change them.
059      */
060    public void initSystemShortcuts();
061
062    /**
063      * The makeTooltip hook will be called whenever a tooltip for
064      * a menu or button is created.
065      *
066      * Tooltips are usually not system dependent, unless the
067      * JVM is too dumb to provide correct names for all the keys.
068      *
069      * Another reason not to use the implementation in the *nix
070      * hook are LAFs that don't understand HTML, such as the OSX LAFs.
071      * 
072     * @param name Tooltip text to display 
073     * @param sc Shortcut associated (to display accelerator between parenthesis)
074     * @return Full tooltip text (name + accelerator)
075      */
076    public String makeTooltip(String name, Shortcut sc);
077
078    /**
079     * Returns the default LAF to be used on this platform to look almost as a native application.
080     * @return The default native LAF for this platform
081     */
082    public String getDefaultStyle();
083
084    /**
085     * Determines if the platform allows full-screen.
086     * @return {@code true} if full screen is allowed, {@code false} otherwise
087     */
088    public boolean canFullscreen();
089
090    /**
091     * Renames a file.
092     * @param from Source file
093     * @param to Target file
094     * @return {@code true} if the file has been renamed, {@code false} otherwise
095     */
096    public boolean rename(File from, File to);
097
098    /**
099     * Returns a detailed OS description (at least family + version).
100     * @return A detailed OS description.
101     * @since 5850
102     */
103    public String getOSDescription();
104}