Back to index

lightning-sunbird  0.9+nobinonly
nsICommandManager.idl
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is mozilla.org code.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *   Simon Fraser <sfraser@netscape.com>
00024  *   Kathleen Brade <brade@netscape.com>
00025  *
00026  * Alternatively, the contents of this file may be used under the terms of
00027  * either the GNU General Public License Version 2 or later (the "GPL"), or
00028  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00029  * in which case the provisions of the GPL or the LGPL are applicable instead
00030  * of those above. If you wish to allow use of your version of this file only
00031  * under the terms of either the GPL or the LGPL, and not to allow others to
00032  * use your version of this file under the terms of the MPL, indicate your
00033  * decision by deleting the provisions above and replace them with the notice
00034  * and other provisions required by the GPL or the LGPL. If you do not delete
00035  * the provisions above, a recipient may use your version of this file under
00036  * the terms of any one of the MPL, the GPL or the LGPL.
00037  *
00038  * ***** END LICENSE BLOCK ***** */
00039 
00040 #include "nsISupports.idl"
00041 #include "nsIObserver.idl"
00042 #include "nsICommandParams.idl"
00043 
00044 interface nsIDOMWindow;
00045 
00046 /*
00047  * nsICommandManager is an interface used to executing user-level commands,
00048  * and getting the state of available commands.
00049  *
00050  * Commands are identified by strings, which are documented elsewhere.
00051  * In addition, the list of required and optional parameters for
00052  * each command, that are passed in via the nsICommandParams, are
00053  * also documented elsewhere. (Where? Need a good location for this).
00054  */
00055  
00056  
00057 [scriptable, uuid(080D2001-F91E-11D4-A73C-F9242928207C)]
00058 interface nsICommandManager : nsISupports
00059 {
00060   /*
00061    * Register an observer on the specified command. The observer's Observe
00062    * method will get called when the state (enabled/disbaled, or toggled etc)
00063    * of the command changes.
00064    *
00065    * You can register the same observer on multiple commmands by calling this
00066    * multiple times.
00067    */
00068   void        addCommandObserver(in nsIObserver aCommandObserver,
00069                                  in string aCommandToObserve);
00070 
00071   /*
00072    * Stop an observer from observering the specified command. If the observer
00073    * was also registered on ther commands, they will continue to be observed.
00074    *
00075    * Passing an empty string in 'aCommandObserved' will remove the observer
00076    * from all commands.
00077    */
00078   void        removeCommandObserver(in nsIObserver aCommandObserver,
00079                                     in string aCommandObserved);
00080 
00081   /*
00082    * Ask the command manager if the specified command is supported.
00083    * If aTargetWindow is null, the focused window is used.
00084    *
00085    */
00086   boolean     isCommandSupported(in string aCommandName,
00087                                  in nsIDOMWindow aTargetWindow);
00088 
00089   /*
00090    * Ask the command manager if the specified command is currently.
00091    * enabled.
00092    * If aTargetWindow is null, the focused window is used.
00093    */
00094   boolean     isCommandEnabled(in string aCommandName,
00095                                in nsIDOMWindow aTargetWindow);
00096 
00097   /*
00098    * Get the state of the specified commands.
00099    *
00100    * On input: aCommandParams filled in with values that the caller cares
00101    * about, most of which are command-specific (see the command documentation
00102    * for details). One boolean value, "enabled", applies to all commands,
00103    * and, in return will be set to indicate whether the command is enabled
00104    * (equivalent to calling isCommandEnabled).
00105    *
00106    * aCommandName is the name of the command that needs the state
00107    * aTargetWindow is the source of command controller 
00108    *      (null means use focus controller)
00109    * On output: aCommandParams: values set by the caller filled in with
00110    * state from the command.
00111    */
00112   void        getCommandState(in string aCommandName,
00113                               in nsIDOMWindow aTargetWindow,
00114                   /* inout */ in nsICommandParams aCommandParams);
00115     
00116   /*
00117    * Execute the specified command.
00118    * The command will be executed in aTargetWindow if it is specified.
00119    * If aTargetWindow is null, it will go to the focused window.
00120    *
00121    * param: aCommandParams, a list of name-value pairs of command parameters,
00122    * may be null for parameter-less commands.
00123    *
00124    */
00125   void        doCommand(in string aCommandName,
00126                         in nsICommandParams aCommandParams,
00127                         in nsIDOMWindow aTargetWindow);
00128 
00129 };
00130 
00131 
00132 /*
00133 
00134 Arguments to observers "Observe" method are as follows:
00135 
00136   void Observe(   in nsISupports aSubject,          // The nsICommandManager calling this Observer
00137                   in string      aTopic,            // Name of the command
00138                   in wstring     aDummy );          // unused
00139 
00140 */
00141 
00142 // {64edb481-0c04-11d5-a73c-e964b968b0bc}
00143 %{C++
00144 #define NS_COMMAND_MANAGER_CID \
00145 { 0x64edb481, 0x0c04, 0x11d5, { 0xa7, 0x3c, 0xe9, 0x64, 0xb9, 0x68, 0xb0, 0xbc } }
00146 
00147 #define NS_COMMAND_MANAGER_CONTRACTID \
00148  "@mozilla.org/embedcomp/command-manager;1"
00149 %}
00150 
00151 
00152