import FIREFOX_52_6_0esr_RELEASE from mozilla-esr52 hg repo

embedding/components/commandhandler/nsICommandManager.idl

@@ -0,0 +1,118 @@
+/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "nsISupports.idl"
+#include "nsIObserver.idl"
+#include "nsICommandParams.idl"
+
+interface mozIDOMWindowProxy;
+
+/*
+ * nsICommandManager is an interface used to executing user-level commands,
+ * and getting the state of available commands.
+ *
+ * Commands are identified by strings, which are documented elsewhere.
+ * In addition, the list of required and optional parameters for
+ * each command, that are passed in via the nsICommandParams, are
+ * also documented elsewhere. (Where? Need a good location for this).
+ */
+ 
+ 
+[scriptable, uuid(bb5a1730-d83b-4fa2-831b-35b9d5842e84)]
+interface nsICommandManager : nsISupports
+{
+  /*
+   * Register an observer on the specified command. The observer's Observe
+   * method will get called when the state (enabled/disbaled, or toggled etc)
+   * of the command changes.
+   *
+   * You can register the same observer on multiple commmands by calling this
+   * multiple times.
+   */
+  void        addCommandObserver(in nsIObserver aCommandObserver,
+                                 in string aCommandToObserve);
+
+  /*
+   * Stop an observer from observering the specified command. If the observer
+   * was also registered on ther commands, they will continue to be observed.
+   *
+   * Passing an empty string in 'aCommandObserved' will remove the observer
+   * from all commands.
+   */
+  void        removeCommandObserver(in nsIObserver aCommandObserver,
+                                    in string aCommandObserved);
+
+  /*
+   * Ask the command manager if the specified command is supported.
+   * If aTargetWindow is null, the focused window is used.
+   *
+   */
+  boolean     isCommandSupported(in string aCommandName,
+                                 in mozIDOMWindowProxy aTargetWindow);
+
+  /*
+   * Ask the command manager if the specified command is currently.
+   * enabled.
+   * If aTargetWindow is null, the focused window is used.
+   */
+  boolean     isCommandEnabled(in string aCommandName,
+                               in mozIDOMWindowProxy aTargetWindow);
+
+  /*
+   * Get the state of the specified commands.
+   *
+   * On input: aCommandParams filled in with values that the caller cares
+   * about, most of which are command-specific (see the command documentation
+   * for details). One boolean value, "enabled", applies to all commands,
+   * and, in return will be set to indicate whether the command is enabled
+   * (equivalent to calling isCommandEnabled).
+   *
+   * aCommandName is the name of the command that needs the state
+   * aTargetWindow is the source of command controller 
+   *      (null means use focus controller)
+   * On output: aCommandParams: values set by the caller filled in with
+   * state from the command.
+   */
+  void        getCommandState(in string aCommandName,
+                              in mozIDOMWindowProxy aTargetWindow,
+                  /* inout */ in nsICommandParams aCommandParams);
+    
+  /*
+   * Execute the specified command.
+   * The command will be executed in aTargetWindow if it is specified.
+   * If aTargetWindow is null, it will go to the focused window.
+   *
+   * param: aCommandParams, a list of name-value pairs of command parameters,
+   * may be null for parameter-less commands.
+   *
+   */
+  void        doCommand(in string aCommandName,
+                        in nsICommandParams aCommandParams,
+                        in mozIDOMWindowProxy aTargetWindow);
+
+};
+
+
+/*
+
+Arguments to observers "Observe" method are as follows:
+
+  void Observe(   in nsISupports aSubject,          // The nsICommandManager calling this Observer
+                  in string      aTopic,            // Name of the command
+                  in wstring     aDummy );          // unused
+
+*/
+
+// {64edb481-0c04-11d5-a73c-e964b968b0bc}
+%{C++
+#define NS_COMMAND_MANAGER_CID \
+{ 0x64edb481, 0x0c04, 0x11d5, { 0xa7, 0x3c, 0xe9, 0x64, 0xb9, 0x68, 0xb0, 0xbc } }
+
+#define NS_COMMAND_MANAGER_CONTRACTID \
+ "@mozilla.org/embedcomp/command-manager;1"
+%}
+
+
+