Rhino C++ API  7.19
Public Types | Public Member Functions | Static Public Member Functions | Friends | List of all members
CRhinoCommand Class Referenceabstract

Every command is Rhino is defined by a class derived from CRhinoCommand. More...

#include <rhinoSdkCommand.h>

Inheritance diagram for CRhinoCommand:
CRhinoHiddenCommand CRhinoScriptCommand CRhinoSelCommand CRhinoTestCommand CRhinoTransformCommand CRhinoSelSubObjectCommand

Public Types

enum  result {
  success = 0, cancel = 1, nothing = 2, failure,
  unknown_command, cancel_modeless_dialog, exit_rhino = 0x0FFFFFFF
}
 

Public Member Functions

 CRhinoCommand (bool bTransparent=false, bool bDoNotRepeat=false, const class CRhinoPlugIn *pPlugIn=nullptr, bool bTestCommand=false)
 
virtual ~CRhinoCommand ()
 
const unsigned int & CommandFlags () const
 
UUID CommandId () const
 
virtual UUID CommandUUID ()=0
 !! See cmdExample.cpp for instructions on the use of this class. !! ///< More...
 
virtual bool ContextHelpURL (ON_wString &url) const
 
virtual void DoHelp ()
 Override this function to display help for this command. More...
 
virtual void DynamicDraw (class CRhinoView &)
 
virtual CRhinoObjectEditObjects (const class CRhinoHistoryRecord &history_record, ON_SimpleArray< CRhinoObjectPair > &results)
 
void EnableHistoryReplayOnObjectAttributeChange (bool bEnable=true)
 
void EnableRepeatable (BOOL bRepeatable=true)
 
void EnableUndo (bool bUndoable=true)
 
virtual const wchar_t * EnglishCommandName () const
 
virtual const wchar_t * EnglishCommandName ()=0
 
bool HistoryReplayOnObjectAttributeChange () const
 
bool IsAlphaCommand () const
 Returns true if a command is an "alpha" command. More...
 
bool IsRepeatable () const
 
bool IsScriptRunnerCommand () const
 
bool IsSystem () const
 
bool IsTestCommand () const
 
bool IsTransparent () const
 
bool IsUndoable () const
 
virtual void LoadProfile (LPCTSTR lpszSection, CRhinoProfileContext &pc)
 
virtual const wchar_t * LocalCommandName () const
 
const class CRhinoPlugInPlugIn () const
 
virtual CRhinoObjectReplayHistory (const class CRhinoHistoryRecord &history_record)
 
virtual bool ReplayHistory (const class CRhinoHistoryRecord &history_record, ON_SimpleArray< CRhinoObjectPair > &results)
 
virtual CRhinoCommand::result RunCommand (const CRhinoCommandContext &)=0
 
virtual void SaveProfile (LPCTSTR lpszSection, CRhinoProfileContext &pc)
 
CRhinoSettingsSettings ()
 

Static Public Member Functions

static bool IsValidCommandName (const wchar_t *)
 

Friends

class CRhCommand
 
class CRhCommandManager
 
class CRhinoHistoryManager
 
class CRhMiniDumpHelper
 
unsigned int RhCommandFlags_ (const CRhinoCommand *)
 
void RhSetCommandFlags_ (CRhinoCommand *, unsigned int)
 

Detailed Description

Every command is Rhino is defined by a class derived from CRhinoCommand.

Member Enumeration Documentation

◆ result

Enumerator
success 

command worked

cancel 

user canceled command

nothing 

command did nothing but cancel was not pressed

failure 

command failed (bad input, computational problem, etc.)

unknown_command 

command not found (user probably had a typo in command name)

cancel_modeless_dialog 
exit_rhino 

exit Rhino.

Constructor & Destructor Documentation

◆ CRhinoCommand()

CRhinoCommand::CRhinoCommand ( bool  bTransparent = false,
bool  bDoNotRepeat = false,
const class CRhinoPlugIn pPlugIn = nullptr,
bool  bTestCommand = false 
)

Description: For each class derived from CRhinoCommand, there is only a single static instance that exists in the .CPP file where the class is defined. No other instances of a class derived from CRhinoCommand should ever be created. Paremeters: bTransparent - [in] true if command is transparent and can be run inside of other commands. bDoNotRepeat - [in] true if command should not be repeated. pPlugIn - [in] if command is part of a plug-in, the plug-in pointer must be passed here. (This is automatically handled by the plug-in wizard.) bTestCommand - [in] true if command is a "test" or debugging tool that should not be part of the commercial release.

◆ ~CRhinoCommand()

virtual CRhinoCommand::~CRhinoCommand ( )
virtual

Member Function Documentation

◆ CommandFlags()

const unsigned int& CRhinoCommand::CommandFlags ( ) const

◆ CommandId()

UUID CRhinoCommand::CommandId ( ) const

◆ CommandUUID()

virtual UUID CRhinoCommand::CommandUUID ( )
pure virtual

!! See cmdExample.cpp for instructions on the use of this class. !! ///<

Rhino command UUID

this should have been a const function, but the mistake was made years ago and now there are thousands of instances of this class. The function CommandId() is const and calls CommandUUID().

◆ ContextHelpURL()

virtual bool CRhinoCommand::ContextHelpURL ( ON_wString url) const
virtual

Description: The Command Context window will call this function when it is attempting to show help for this command. Override this function if you have a help topic that you can display in the Command Context window. Parameters: url - [out] URL to your command's help topic. The Command Context window is an embedded web browser control, so any URL that you can display in a web browser would be valid. The base class function returns a URL that is formatted to show a page inside the Rhino CHM help file. For example, Rhino's line command returns a string like the following: mk:@MSITStore:C:\Program%20Files\Rhinoceros%204.0\English\Help\rhinov4.chm::/Commands/Lines.htm::Line_command Returns: true if the Command Context should update to display the url false if you don't want the Command Context window to change it's current url Remarks: The recommended approach is to create a URL that points to an HTML file that is on the user's computer. This speeds up the display of your help topic and doesn't make your command look like it is running slow when the Command Context auto-update is on.

◆ DoHelp()

virtual void CRhinoCommand::DoHelp ( )
virtual

Override this function to display help for this command.

◆ DynamicDraw()

virtual void CRhinoCommand::DynamicDraw ( class CRhinoView )
virtual

If you need to draw visual cues during your command, then override DynamicDraw().
Call EnableDynamicDraw(true/false) to enable/disable the use of your DynamicDraw() function.
Call RhinoApp().UpdateViews() when you need to force the view to be updated.

◆ EditObjects()

virtual CRhinoObject* CRhinoCommand::EditObjects ( const class CRhinoHistoryRecord history_record,
ON_SimpleArray< CRhinoObjectPair > &  results 
)
virtual

Description: The Rhino "Edit" command calls uses the virtual EditObjects functions to interactively edit objects. If a command supports editing, it must override the EditObjects function. Parameters: history - [in] History information the command record when it first created the existing objects.

results - [in/out] results[i].m_objects[0] - [in] existing object results[i].m_objects[1] - [out] updated object

The input array has the objects that were created by the command in results[i].m_objects[0].

EditObjects is responsible for creating replacements and putting them in results[i].m_objects[1]. The replacements must NOT be added to the document. An input results[i].m_objects[0] can be set to NULL if no replacement can be calculated.

If results[i].m_objects[0] and results[i].m_objects[1] are both not NULL, then m_objects[1] will replace m_objects[0]. If results[i].m_objects[1] is NULL, then nothing is done to results[i].m_objects[0]. If results[i].m_objects[0] is NULL and results[i].m_objects[1] is not NULL, then results[i].m_objects[1] is added. Returns: Return true if Rhino should process the information in results[] and false otherwise.

◆ EnableHistoryReplayOnObjectAttributeChange()

void CRhinoCommand::EnableHistoryReplayOnObjectAttributeChange ( bool  bEnable = true)

Description: By default, object attribute changes do not trigger history replay. If you want objects created with a command to trigger history replay when object attributes change, call EnableHistoryReplayOnObjectAttributeChange(true) in the constructor for the command's class. Parameters: bEnable - [in] See Also: CRhinoCommand::HistoryReplayOnObjectAttributeChange

◆ EnableRepeatable()

void CRhinoCommand::EnableRepeatable ( BOOL  bRepeatable = true)

◆ EnableUndo()

void CRhinoCommand::EnableUndo ( bool  bUndoable = true)

Description: By default, all commands are undoable. If you have a command that should not be undoable, then call EnableUndo(false) in the constructor for the command's class. Parameters: bUndoable - [in] Remarks: It is a rare command that should call EnableUndo. Enable undo should only be called in the constructor for the command. Under no circustances should enable undo be called while RunCommand is active. See Also: CRhinoCommand::IsUndoable

◆ EnglishCommandName() [1/2]

virtual const wchar_t* CRhinoCommand::EnglishCommandName ( ) const
virtual

◆ EnglishCommandName() [2/2]

virtual const wchar_t* CRhinoCommand::EnglishCommandName ( )
pure virtual

Rhino default english command name TODO - When all the code is checked in, remove the non-const version and make the const version pure virtual.

◆ HistoryReplayOnObjectAttributeChange()

bool CRhinoCommand::HistoryReplayOnObjectAttributeChange ( ) const

Description: Returns true if objects created with this command should trigger history replay when object attributes change. See Also: CRhinoCommand::EnableHistoryReplayOnObjectAttributeChange

◆ IsAlphaCommand()

bool CRhinoCommand::IsAlphaCommand ( ) const

Returns true if a command is an "alpha" command.

◆ IsRepeatable()

bool CRhinoCommand::IsRepeatable ( ) const

Returns true if a command is "repeatable"; i.e., the command can be repeated by pressing ENTER immediately after the command finishes.

◆ IsScriptRunnerCommand()

bool CRhinoCommand::IsScriptRunnerCommand ( ) const

Returns: True if the command is a script runner command like "ReadCommandFile" or the RhinoScript plug-in's "ReadScript". Remarks: In the depths of the Rhino core, "ordinary" commands and "script running" commands need to be treated a litte differently so that commands run in a script behave exactly as if they were being run from the command line.

◆ IsSystem()

bool CRhinoCommand::IsSystem ( ) const

Returns true if a command is a system command. (Most commands are not and SDK developers can ignore this field.)

◆ IsTestCommand()

bool CRhinoCommand::IsTestCommand ( ) const

Returns true if a command is a "test" command that is not available in the commercial release. All commands derived from CRhinoTestCommand are "test" commands.

◆ IsTransparent()

bool CRhinoCommand::IsTransparent ( ) const

Returns true if a command is "transparent"; i.e., the command does not modify the contents of the model's geometry in any way. Examples of transparent commands include commands that change views and toggle snap states. Any command that adds or deletes, a view cannot be transparent.

◆ IsUndoable()

bool CRhinoCommand::IsUndoable ( ) const

Description: Returns true if this command's actions can be undone by the Rhino "Undo" command. See Also: CRhinoCommand::EnableUndo

◆ IsValidCommandName()

static bool CRhinoCommand::IsValidCommandName ( const wchar_t *  )
static

◆ LoadProfile()

virtual void CRhinoCommand::LoadProfile ( LPCTSTR  lpszSection,
CRhinoProfileContext pc 
)
virtual

Description: Loads persistenct command settings from the Rhino profile. Parameters: lpszSection - [in] profile section to use for this command pc - [in] profile context to use to get at value saved in the Rhino profile. Remarks: Most commands do not override LoadProfile. Use LoadProfile to get command options that persist between Rhino sessions. The default does nothing.

◆ LocalCommandName()

virtual const wchar_t* CRhinoCommand::LocalCommandName ( ) const
virtual

Localized command name. The default implementation uses the command name string table to translate the string returned by EnglishCommandName().

◆ PlugIn()

const class CRhinoPlugIn* CRhinoCommand::PlugIn ( ) const

If command is in a plug-in, this returns the pointer to the plug-in.

◆ ReplayHistory() [1/2]

virtual CRhinoObject* CRhinoCommand::ReplayHistory ( const class CRhinoHistoryRecord history_record)
virtual

◆ ReplayHistory() [2/2]

virtual bool CRhinoCommand::ReplayHistory ( const class CRhinoHistoryRecord history_record,
ON_SimpleArray< CRhinoObjectPair > &  results 
)
virtual

Description: Rhino calls uses the virtual ReplayHistory functions to to remake an objects when inputs have changed.
If a command supports history, it must override exactly one of the ReplayHistory functions. Simple commands can use the simple version of replay history that just just generates a new object. Complex commands, like Project and Interesect need to override the complex version of replay history that uses a results[] array to return multiple objects. Parameters: history - [in] History information the command record when it first created the existing objects.

results - [in/out] (complex version) results[i].m_objects[0] - [in] existing object results[i].m_objects[1] - [out] updated object

The input array has the objects that were created by the command in results[i].m_objects[0].

ReplayHistory is responsible for creating replacements and putting them in results[i].m_objects[1]. The replacements must NOT be added to the document. The results[] array can be grown if there are new "updated" objects that do not replace an existing object. In this case set the m_objects[0] pointer to NULL. An input results[i].m_objects[0] can be set to NULL if no replacement can be calculated.

If results[i].m_objects[0] and results[i].m_objects[1] are both not NULL, then m_objects[1] will replace m_objects[0]. If results[i].m_objects[0] is not NULL and results[i].m_objects[1] is NULL, then results[i].m_objects[0] is deleted. If results[i].m_objects[0] is NULL and results[i].m_objects[1] is not NULL, then results[i].m_objects[1] is added. Returns: The simple version returns either NULL or an updated object. The complex version returns true if Rhino should process the information in results[] and false otherwise.

◆ RunCommand()

virtual CRhinoCommand::result CRhinoCommand::RunCommand ( const CRhinoCommandContext )
pure virtual

Description: Rhino calls this function to run the command. Returns: success command worked cancel user canceled command nothing command did nothing but cancel was not pressed. failure command failed (bad input, computational problem, etc.

Implemented in CRhinoSelSubObjectCommand, and CRhinoSelCommand.

◆ SaveProfile()

virtual void CRhinoCommand::SaveProfile ( LPCTSTR  lpszSection,
CRhinoProfileContext pc 
)
virtual

Description: Save persistent command settings to the Rhino profile. Parameters: lpszSection - [in] profile section to use for this command pc - [in] profile context to use to get at value saved in the Rhino profile. Remarks: Most commands do not override SaveProfile. Use SaveProfile to save command options that persist between Rhino sessions. The default does nothing.

◆ Settings()

CRhinoSettings& CRhinoCommand::Settings ( )

Description: Get persistent command settings

Friends And Related Function Documentation

◆ CRhCommand

friend class CRhCommand
friend

◆ CRhCommandManager

friend class CRhCommandManager
friend

◆ CRhinoHistoryManager

friend class CRhinoHistoryManager
friend

◆ CRhMiniDumpHelper

friend class CRhMiniDumpHelper
friend

◆ RhCommandFlags_

unsigned int RhCommandFlags_ ( const CRhinoCommand )
friend

◆ RhSetCommandFlags_

void RhSetCommandFlags_ ( CRhinoCommand ,
unsigned int   
)
friend