developer/VSSDK/VisualStudioIntegration/Common/Source/CSharp/Shell90/OleMenuCommand.cs

   1 using System;
   2 using System.Runtime.InteropServices;
   3 using System.Security.Permissions;
   4 using Microsoft.VisualStudio.OLE.Interop;
   5
   6 namespace Microsoft.VisualStudio.Shell
   7 {
   8     using System.ComponentModel;
   9     using System.ComponentModel.Design;
  10
  11     /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCmdEventArgs"]/*' />
  12     /// <summary>
  13     /// This is the set of arguments passed to a OleMenuCommand object when the
  14     /// Invoke function is called
  15     /// </summary>
  16     [CLSCompliant(false)]
  17     public class OleMenuCmdEventArgs : System.EventArgs
  18     {
  19         private object inParam;
  20         private IntPtr outParam;
  21         private OLECMDEXECOPT execOptions;
  22
  23         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCmdEventArgs.OleMenuCmdEventArgs"]/*' />
  24         /// <summary>
  25         /// Builds the OleMenuCmdEventArgs
  26         /// </summary>
  27         /// <param name="inParam">The input parameter to the command function.</param>
  28         /// <param name="outParam">A pointer to the parameter returned by the function</param>
  29         public OleMenuCmdEventArgs(object inParam, IntPtr outParam) :
  30             this(inParam, outParam, OLECMDEXECOPT.OLECMDEXECOPT_DODEFAULT)
  31         {
  32         }
  33
  34         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCmdEventArgs.OleMenuCmdEventArgs"]/*' />
  35         /// <summary>
  36         /// Builds the OleMenuCmdEventArgs
  37         /// </summary>
  38         /// <param name="inParam">The input parameter to the command function.</param>
  39         /// <param name="outParam">A pointer to the parameter returned by the function</param>
  40         /// <param name="options">Execution options for the command.</param>
  41         public OleMenuCmdEventArgs(object inParam, IntPtr outParam, OLECMDEXECOPT options) : base()
  42         {
  43             this.execOptions = options;
  44             this.inParam = inParam;
  45             this.outParam = outParam;
  46         }
  47
  48         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCmdEventArgs.InValue"]/*' />
  49         /// <summary>
  50         /// Gets the parameter passed as input to the command function
  51         /// </summary>
  52         public object InValue
  53         {
  54             get { return inParam; }
  55         }
  56
  57         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCmdEventArgs.Options"]/*' />
  58         /// <summary>
  59         /// Gets the execution options for the command.
  60         /// </summary>
  61         public OLECMDEXECOPT Options
  62         {
  63             get { return execOptions; }
  64         }
  65
  66         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCmdEventArgs.OutValue"]/*' />
  67         /// <summary>
  68         /// Gets a pointer to the parameter used as output by the command function
  69         /// </summary>
  70         public IntPtr OutValue
  71         {
  72             get { return outParam; }
  73         }
  74     }
  75
  76     /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand"]/*' />
  77     /// <summary>
  78     /// This class is an expansion of MenuCommand.
  79     /// </summary>
  80     [System.Runtime.InteropServices.ComVisible(true)]
  81     public class OleMenuCommand : MenuCommand, IOleMenuCommand, IMenuCommandInvokeEx
  82     {
  83         /// <summary>The event handler called to execute the command.</summary>
  84         private EventHandler execHandler;
  85         /// <summary>
  86         /// The event handler caller before getting the command status; it can be used to
  87         /// implement a command with a dynamic status.
  88         /// </summary>
  89         private EventHandler beforeQueryStatusHandler;
  90         private string text;
  91         // Used in the case of dynamic menu (created with the DYNAMICITEMSTART option)
  92         private int matchedCommandId;
  93         // If the command supports parameters, then this string will contain the description
  94         // of the parameters
  95         private string parametersDescription;
  96
  97         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.OleMenuCommand"]/*' />
  98         /// <summary>
  99         /// Builds a new OleMenuCommand.
 100         /// </summary>
 101         /// <param name="invokeHandler">The event handler called to execute the command.</param>
 102         /// <param name="id">ID of the command.</param>
 103         public OleMenuCommand(EventHandler invokeHandler, CommandID id) :
 104             base(invokeHandler, id)
 105         {
 106             PrivateInit(invokeHandler, null, null, String.Empty);
 107         }
 108
 109         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.OleMenuCommand1"]/*' />
 110         /// <summary>
 111         /// Builds a new OleMenuCommand.
 112         /// </summary>
 113         /// <param name="invokeHandler">The event handler called to execute the command.</param>
 114         /// <param name="id">ID of the command.</param>
 115         /// <param name="Text">The text of the command.</param>
 116         public OleMenuCommand(EventHandler invokeHandler, CommandID id, string Text) :
 117             base(invokeHandler, id)
 118         {
 119             PrivateInit(invokeHandler, null, null, Text);
 120         }
 121
 122         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.OleMenuCommand2"]/*' />
 123         /// <devdoc>
 124         /// Builds a new OleMenuCommand.
 125         /// </devdoc>
 126         /// <param name="invokeHandler">The event handler called to execute the command.</param>
 127         /// <param name="changeHandler">The event handler called when the command's status changes.</param>
 128         /// <param name="id">ID of the command.</param>
 129         public OleMenuCommand(EventHandler invokeHandler, EventHandler changeHandler, CommandID id) :
 130             base(invokeHandler, id)
 131         {
 132             PrivateInit(invokeHandler, changeHandler, null, String.Empty);
 133         }
 134
 135         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.OleMenuCommand3"]/*' />
 136         /// <devdoc>
 137         /// Builds a new OleMenuCommand.
 138         /// </devdoc>
 139         /// <param name="invokeHandler">The event handler called to execute the command.</param>
 140         /// <param name="changeHandler">The event handler called when the command's status changes.</param>
 141         /// <param name="id">ID of the command.</param>
 142         /// <param name="Text">The text of the command.</param>
 143         public OleMenuCommand(EventHandler invokeHandler, EventHandler changeHandler, CommandID id, string Text) :
 144             base(invokeHandler, id)
 145         {
 146             PrivateInit(invokeHandler, changeHandler, null, Text);
 147         }
 148
 149         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.OleMenuCommand4"]/*' />
 150         /// <devdoc>
 151         /// Builds a new OleMenuCommand.
 152         /// </devdoc>
 153         /// <param name="invokeHandler">The event handler called to execute the command.</param>
 154         /// <param name="changeHandler">The event handler called when the command's status changes.</param>
 155         /// <param name="beforeQueryStatus">Event handler called when a lient asks for the command status.</param>
 156         /// <param name="id">ID of the command.</param>
 157         public OleMenuCommand(EventHandler invokeHandler, EventHandler changeHandler, EventHandler beforeQueryStatus, CommandID id) :
 158             base(invokeHandler, id)
 159         {
 160             PrivateInit(invokeHandler, changeHandler, beforeQueryStatus, String.Empty);
 161         }
 162
 163         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.OleMenuCommand5"]/*' />
 164         /// <devdoc>
 165         /// Builds a new OleMenuCommand.
 166         /// </devdoc>
 167         /// <param name="invokeHandler">The event handler called to execute the command.</param>
 168         /// <param name="changeHandler">The event handler called when the command's status changes.</param>
 169         /// <param name="beforeQueryStatus">Event handler called when a lient asks for the command status.</param>
 170         /// <param name="id">ID of the command.</param>
 171         /// <param name="Text">The text of the command.</param>
 172         public OleMenuCommand(EventHandler invokeHandler, EventHandler changeHandler, EventHandler beforeQueryStatus, CommandID id, string Text) :
 173             base(invokeHandler, id)
 174         {
 175             PrivateInit(invokeHandler, changeHandler, beforeQueryStatus, Text);
 176         }
 177
 178         private void PrivateInit(EventHandler handler, EventHandler changeHandler, EventHandler beforeQS, string Text)
 179         {
 180             execHandler = handler;
 181             if (changeHandler != null)
 182             {
 183                 this.CommandChanged += changeHandler;
 184             }
 185             beforeQueryStatusHandler = beforeQS;
 186             text = Text;
 187             parametersDescription = null;
 188         }
 189
 190         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.BeforeQueryStatus"]/*' />
 191         /// <devdoc>
 192         /// Event fired when a client asks for the status of the command.
 193         /// </devdoc>
 194         /// <value></value>
 195         public event EventHandler BeforeQueryStatus
 196         {
 197             add { beforeQueryStatusHandler += value; }
 198             remove { beforeQueryStatusHandler -= value; }
 199         }
 200
 201         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.OleStatus"]/*' />
 202         public override int OleStatus
 203                 {
 204                         [PermissionSet(SecurityAction.LinkDemand, Name = "FullTrust")]
 205             get
 206             {
 207                 if (null != beforeQueryStatusHandler)
 208                 {
 209                     beforeQueryStatusHandler(this, EventArgs.Empty);
 210                 }
 211                 return base.OleStatus;
 212             }
 213         }
 214
 215         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.ParametersDescription"]/*' />
 216         /// <devdoc>
 217         /// Get or set the string that describes the paraeters accepted by the command.
 218         /// </devdoc>
 219         public string ParametersDescription
 220         {
 221             get { return parametersDescription; }
 222             set { parametersDescription = value; }
 223         }
 224
 225         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.Invoke"]/*' />
 226         /// <devdoc>
 227         /// Executes the command.
 228         /// </devdoc>
 229         /// <param name="inArg">The parameter passed to the command.</param>
 230         [PermissionSet(SecurityAction.LinkDemand, Name = "FullTrust")]
 231         public override void Invoke(object inArg)
 232         {
 233             try
 234             {
 235                 OleMenuCmdEventArgs args = new OleMenuCmdEventArgs(inArg, NativeMethods.InvalidIntPtr);
 236                 execHandler(this, args);
 237             }
 238             catch (CheckoutException ex)
 239             {
 240                 if (CheckoutException.Canceled != ex)
 241                     throw;
 242             }
 243         }
 244
 245         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.Invoke1"]/*' />
 246         /// <devdoc>
 247         /// Executes the command.
 248         /// </devdoc>
 249         /// <param name="inArg">The parameter passed to the command.</param>
 250         /// <param name="outArg">The parameter returned by the command.</param>
 251         [EnvironmentPermission(SecurityAction.LinkDemand, Unrestricted = true)]
 252         public virtual void Invoke(object inArg, IntPtr outArg)
 253         {
 254             Invoke(inArg, outArg, OLECMDEXECOPT.OLECMDEXECOPT_DODEFAULT);
 255         }
 256
 257         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.Invoke2"]/*' />
 258         /// <summary>
 259         /// Executes the command with execution options.
 260         /// </summary>
 261         /// <param name="inArg">The parameter passed to the command.</param>
 262         /// <param name="outArg">The parameter returned by the command.</param>
 263         /// <param name="options">The execution options for the command.</param>
 264         [EnvironmentPermission(SecurityAction.LinkDemand, Unrestricted = true)]
 265         [CLSCompliant(false)]
 266         public virtual void Invoke(object inArg, IntPtr outArg, OLECMDEXECOPT options)
 267         {
 268             try
 269             {
 270                 OleMenuCmdEventArgs args = new OleMenuCmdEventArgs(inArg, outArg, options);
 271                 execHandler(this, args);
 272             }
 273             catch (CheckoutException ex)
 274             {
 275                 if (CheckoutException.Canceled != ex)
 276                     throw;
 277             }
 278         }
 279
 280         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.Text"]/*' />
 281         /// <devdoc>
 282         /// Gets or sets the text for the command.
 283         /// </devdoc>
 284         /// <value></value>
 285         public virtual string Text
 286         {
 287             get { return text; }
 288             set { if (text != value) { text = value; OnCommandChanged(EventArgs.Empty); } }
 289         }
 290
 291         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.DynamicItemMatch"]/*' />
 292         /// <devdoc>
 293         /// Allows a dynamic item command to match the subsequent items in its list.  This must be overriden
 294         /// when implementing a menu via DYNAMICITEMSTART.
 295         /// </devdoc>
 296         /// <param name="cmdId"></param>
 297         /// <returns></returns>
 298         public virtual bool DynamicItemMatch(int cmdId)
 299         {
 300             return false;
 301         }
 302
 303         /// <include file='doc\OleMenuCommand.uex' path='docs/doc[@for="OleMenuCommand.MatchedCommandId"]/*' />
 304         /// <devdoc>
 305         /// The command id that was most recently used to match this command.  This must be set by the sub-class
 306         /// when a match occurs and can be used to identify the actual command being invoked.
 307         /// </devdoc>
 308         /// <value></value>
 309         public int MatchedCommandId
 310         {
 311             get { return matchedCommandId; }
 312             set { matchedCommandId = value; }
 313         }
 314
 315     }
 316 }