Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All


The framework calls this function to execute a specified command or display help for the command.

virtual HRESULT OnExecOleCmd( 
   const GUID* pguidCmdGroup, 
   DWORD nCmdID, 
   DWORD nCmdExecOpt, 
   VARIANTARG* pvarargIn, 
   VARIANTARG* pvarargOut 


A pointer to a GUID that identifies a set of commands. Can be NULL to indicate the default command group.


The command to execute. Must be in the group identified by pguidCmdGroup.


The way the object should execute the command, one or more of the following values from the OLECMDEXECOPT enumeration:






Pointer to a VARIANTARG containing input arguments for the command. Can be NULL.


Pointer to a VARIANTARG to receive the output return values from the command. Can be NULL.

Returns S_OK if successful; otherwise, one of the following error codes:




Unexpected error occurred


Error occurred


Indicates MFC itself should attempt to translate and dispatch the command


pguidCmdGroup is non-NULL but does not specify a recognized command group


nCmdID is not recognized as a valid command in the group pguidCmdGroup


The command identified by nCmdID is disabled and cannot be executed


Caller asked for help on the command identified by nCmdID but no help is available


User canceled the execution

COleCmdUI can be used to enable, update, and set other properties of DocObject user interface commands. After the commands are initialized, you can execute them with OnExecOleCmd.

The framework calls the function before attempting to translate and dispatch an OLE document command. You don't need to override this function to handle standard OLE document commands, but you must supply an override to this function if you want to handle your own custom commands or handle commands that accept parameters or return results.

Most of the commands do not take arguments or return values. For a majority of commands the caller can pass NULLs for pvarargIn and pvarargOut. For commands that expect input values, the caller can declare and initialize a VARIANTARG variable and pass a pointer to the variable in pvarargIn. For commands that require a single value, the argument can be stored directly in the VARIANTARG and passed to the function. Multiple arguments must be packaged within the VARIANTARG using one of the supported types (such as IDispatch and SAFEARRAY ).

Similarly, if a command returns arguments the caller is expected to declare a VARIANTARG, initialize it to VT_EMPTY, and pass its address in pvarargOut. If a command returns a single value, the object can store that value directly in pvarargOut. Multiple output values must be packaged in some way appropriate for the VARIANTARG.

The base-class implementation of this function will walk the OLE_COMMAND_MAP structures associated with the command target and try to dispatch the command to an appropriate handler. The base-class implementation works only with commands that do not accept arguments or return values. If you need to handle commands that do accept arguments or return values, you must override this function and work with the pvarargIn and pvarargOut parameters yourself.

Header: afxole.h

© 2015 Microsoft