source: josm/trunk/src/org/openstreetmap/josm/tools/PlatformHook.java@ 1058

// License: GPL. Copyright 2007 by Immanuel Scholz and others
package org.openstreetmap.josm.tools;

import static org.openstreetmap.josm.tools.I18n.tr;
import org.openstreetmap.josm.tools.ShortCut;

import java.io.IOException;

/**
 * This interface allows platfrom (operating system) dependent code
 * to be bundled into self-contained classes.
 *
 * For plugin authors:
 * To implement your own PlatformHook class, implement this interface,
 * then create the class when your plugin is loaded and store it in
 * Main.platform. Please not that the two "startup" hooks will be
 * called _before_ your plugin is loaded. If you need to hook there,
 * split your class into two (one containing only the startup hooks,
 * and one with the remainder) and send the startup class, together
 * with propper OS detection code (see Main) for inclusion with
 * JOSM to the JOSM team.
 *
 * Also, it might be a good idea to extend PlatformHookUnixoid.
 * That class has a more or less neutral behaviour, that should
 * work on all platforms supported by J2SE.
 *
 * Attention: At this time this interface is not to be considered
 * complete.
 */
public interface PlatformHook {
        /**
          * The preStartupHook will be called extremly early. It is
          * guaranteed to be called before the GUI setup has started.
          *
          * Reason: On OSX we need to inform the Swing libraries
          * that we want to be integrated with the OS before we setup
          * our GUI.
          */
        public void preStartupHook();

        /**
          * The startupHook will be called early, but after the GUI
          * setup has started.
          *
          * Reason: On OSX we need to register some callbacks with the
          * OS, so we'll receive events from the system menu.
          */
        public void startupHook();

        /**
          * The openURL hook will be used to open an URL in the
          * default webbrowser.
          */
        public void openUrl(String url) throws IOException;

        /**
          * The initShortCutGroups hook will be called by the
          * ShortCut class if it detects that there are no
          * groups in teh config file. So that will happen
          * once on each JOSM installation only.
          *
          * Please note that ShorCut will load its config on demand,
          * that is, at the moment the first shortcut is registered.
          *
          * In this hook, you have to fill the preferences with
          * data, not the internal structures! Also, do not try
          * to register any shortcuts from within.
          */
        public void initShortCutGroups();

        /**
          * The initSystemShortCuts hook will be called by the
          * ShortCut class after the modifier groups have been read
          * from the config, but before any shortcuts are read from
          * it or registered from within the application.
          *
          * Plese note that you are not allowed to register any
          * shortuts from this hook, but only "systemCuts"!
          *
          * BTW: SystemCuts should be named "system:<whatever>",
          * and it'd be best if sou'd recycle the names already used
          * by the Windows and OSX hooks. Especially the later has
          * really many of them.
          *
          * You should also register any and all shortcuts that the
          * operation system handles itself to block JOSM from trying
          * to use them---as that would just not work. Call setAutomatic
          * on them to prevent the keyboard preferences from allowing the
          * user to change them.
          */
        public void initSystemShortCuts();

        /**
          * The makeTooltip hook will be called whenever a tooltip for
          * a menu or button is created.
          *
          * Tooltips are usually not system dependent, unless the
          * JVM is to dumb to provide correct names for all the keys.
          *
          * Another reason not to use the implementation in the *nix
          * hook are LAFs that don't understand HTML, such as the OSX
          * LAFs.
          */
        public String makeTooltip(String name, ShortCut sc);
}