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

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