dom/commandhandler/nsICommandManager.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7 #include "nsIObserver.idl"
   8 #include "nsICommandParams.idl"
   9
  10 interface mozIDOMWindowProxy;
  11
  12 %{C++
  13 class nsCommandManager;
  14 %}
  15
  16 /*
  17  * nsICommandManager is an interface used to executing user-level commands,
  18  * and getting the state of available commands.
  19  *
  20  * Commands are identified by strings, which are documented elsewhere.
  21  * In addition, the list of required and optional parameters for
  22  * each command, that are passed in via the nsICommandParams, are
  23  * also documented elsewhere. (Where? Need a good location for this).
  24  */
  25
  26
  27 [scriptable, builtinclass, uuid(bb5a1730-d83b-4fa2-831b-35b9d5842e84)]
  28 interface nsICommandManager : nsISupports
  29 {
  30   /*
  31    * Register an observer on the specified command. The observer's Observe
  32    * method will get called when the state (enabled/disabled, or toggled etc)
  33    * of the command changes.
  34    *
  35    * You can register the same observer on multiple commmands by calling this
  36    * multiple times.
  37    */
  38   void        addCommandObserver(in nsIObserver aCommandObserver,
  39                                  in string aCommandToObserve);
  40
  41   /*
  42    * Stop an observer from observering the specified command. If the observer
  43    * was also registered on ther commands, they will continue to be observed.
  44    *
  45    * Passing an empty string in 'aCommandObserved' will remove the observer
  46    * from all commands.
  47    */
  48   void        removeCommandObserver(in nsIObserver aCommandObserver,
  49                                     in string aCommandObserved);
  50
  51   /*
  52    * Ask the command manager if the specified command is supported.
  53    * If aTargetWindow is null, the focused window is used.
  54    *
  55    */
  56   boolean     isCommandSupported(in string aCommandName,
  57                                  in mozIDOMWindowProxy aTargetWindow);
  58
  59   /*
  60    * Ask the command manager if the specified command is currently.
  61    * enabled.
  62    * If aTargetWindow is null, the focused window is used.
  63    */
  64   boolean     isCommandEnabled(in string aCommandName,
  65                                in mozIDOMWindowProxy aTargetWindow);
  66
  67   /*
  68    * Get the state of the specified commands.
  69    *
  70    * On input: aCommandParams filled in with values that the caller cares
  71    * about, most of which are command-specific (see the command documentation
  72    * for details). One boolean value, "enabled", applies to all commands,
  73    * and, in return will be set to indicate whether the command is enabled
  74    * (equivalent to calling isCommandEnabled).
  75    *
  76    * aCommandName is the name of the command that needs the state
  77    * aTargetWindow is the source of command controller
  78    *      (null means use focus controller)
  79    * On output: aCommandParams: values set by the caller filled in with
  80    * state from the command.
  81    */
  82   void        getCommandState(in string aCommandName,
  83                               in mozIDOMWindowProxy aTargetWindow,
  84                   /* inout */ in nsICommandParams aCommandParams);
  85
  86   /*
  87    * Execute the specified command.
  88    * The command will be executed in aTargetWindow if it is specified.
  89    * If aTargetWindow is null, it will go to the focused window.
  90    *
  91    * param: aCommandParams, a list of name-value pairs of command parameters,
  92    * may be null for parameter-less commands.
  93    *
  94    */
  95   [can_run_script]
  96   void        doCommand(in string aCommandName,
  97                         in nsICommandParams aCommandParams,
  98                         in mozIDOMWindowProxy aTargetWindow);
  99
 100 %{C++
 101   /**
 102    * In order to avoid circular dependency issues, these methods are defined
 103    * in nsCommandManager.h.  Consumers need to #include that header.
 104    */
 105   inline nsCommandManager* AsCommandManager();
 106   inline const nsCommandManager* AsCommandManager() const;
 107 %}
 108 };
 109
 110
 111 /*
 112
 113 Arguments to observers "Observe" method are as follows:
 114
 115   void Observe(   in nsISupports aSubject,          // The nsICommandManager calling this Observer
 116                   in string      aTopic,            // Name of the command
 117                   in wstring     aDummy );          // unused
 118
 119 */