Rhino C++ API  8.7
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
CRhRdkTask Class Referenceabstract

#include <RhRdkTask.h>

Inheritance diagram for CRhRdkTask:
CRhRdkExtension CRhRdkObject CRhRdkContentTask CRhRdkCustomTask CRhRdkSimpleTask CRhRdkMultipleContentTask CRhRdkSingleContentTask CRhRdkRequestTask CRhRdkMultipleTopLevelContentTask CRhRdkSingleTopLevelContentTask

Public Types

enum  Result : unsigned int { Result::Success, Result::Failure, Result::Cancel }
enum  Separator : unsigned int { Separator::None, Separator::Before, Separator::After, Separator::Both }
enum  SubMenus { SubMenus::None, SubMenus::CreateNew, SubMenus::Thumbnails, SubMenus::PlugIn }

Public Member Functions

 CRhRdkTask ()
virtual ~CRhRdkTask ()
Result Error (const wchar_t *wszMessage) const
virtual Result Execute (const IRhRdkTaskOrigin &origin) const =0
virtual bool IconIn (CRhRdkContent::Kinds kind, int width, int height, CRhinoDib &dibOut) const
virtual bool IconOut (CRhRdkContent::Kinds kind, int width, int height, CRhinoDib &dibOut) const
virtual UUID Id (void) const =0
virtual UUID InterfaceId (void) const final override
virtual bool IsEnabled (const IRhRdkTaskOrigin &origin) const =0
virtual bool IsForTopLevelContent (void) const
virtual int MenuOrder (const IRhRdkTaskOrigin &origin) const =0
virtual Separator MenuSeparators (void) const
virtual const wchar_t * MenuString (const IRhRdkTaskOrigin &origin, CRhRdkContent::Kinds kind) const =0
virtual bool Query (const IRhRdkTaskOrigin &origin, bool bOnItem) const
virtual UUID RenderEngineId (void) const
virtual void SetError (const wchar_t *wszMessage, RhRdkMbSeverity severity) const
virtual SubMenus SubMenu (void) const
virtual bool SupportsSandbox (void) const
virtual void Update (IRhRdkTaskUpdate &tu) const
virtual Result UserExecute (const IRhRdkTaskOrigin &origin) const
virtual void UserUpdate (IRhRdkTaskUpdate &tu) const
- Public Member Functions inherited from CRhRdkExtension
 CRhRdkExtension ()
virtual ~CRhRdkExtension ()
virtual UUID PlugInId (void) const =0
bool Unregister (void)
- Public Member Functions inherited from CRhRdkObject
 CRhRdkObject ()
virtual ~CRhRdkObject ()
virtual void * EVF (const wchar_t *wszFunc, void *pvData)
void operator delete (void *buf)
void operator delete[] (void *buf)
void * operator new (size_t size)
void * operator new[] (size_t size)

Static Public Member Functions

static void RequiredDataSources (OUT ON_SimpleArray< ON_UUID > &aId)
- Static Public Member Functions inherited from CRhRdkObject
static void CheckMemory (void)
static void PopulateDebuggingInfo (void)

Protected Member Functions

void FullUndoString (const IRhRdkTaskOrigin &origin, ON_wString &sOut) const
virtual bool GetSureMessage (const IRhRdkTaskOrigin &origin, ON_wString &sMessageOut, ON_wString &sYesVerbOut, ON_wString &sNoVerbOut, ON_wString &sDontShowAgainIdOut) const
virtual void GetUndoString (const IRhRdkTaskOrigin &origin, ON_wString &sOut) const
virtual void SetSelection (const IRhRdkTaskOrigin &origin, const CRhRdkContentArray &aContent) const

Detailed Description

This class is the base class for all tasks. A task encapsulates the functionality of any operation the user can perform by clicking a menu item or pressing a key in a content editor.

Member Enumeration Documentation

◆ Result

enum CRhRdkTask::Result : unsigned int

Result codes for Execute()


◆ Separator

enum CRhRdkTask::Separator : unsigned int

This enum is for MenuSeparators()


◆ SubMenus

enum CRhRdkTask::SubMenus

This enum is for SubMenu()


Constructor & Destructor Documentation

◆ CRhRdkTask()

CRhRdkTask::CRhRdkTask ( )

◆ ~CRhRdkTask()

virtual CRhRdkTask::~CRhRdkTask ( )

Member Function Documentation

◆ Error()

Result CRhRdkTask::Error ( const wchar_t *  wszMessage) const

Helper function to set error message with severity 'error' and return failure.

◆ Execute()

virtual Result CRhRdkTask::Execute ( const IRhRdkTaskOrigin origin) const
pure virtual

Implement this method to execute the task.

Implemented in CRhRdkRequestTask.

◆ FullUndoString()

void CRhRdkTask::FullUndoString ( const IRhRdkTaskOrigin origin,
ON_wString sOut 
) const

◆ GetSureMessage()

virtual bool CRhRdkTask::GetSureMessage ( const IRhRdkTaskOrigin origin,
ON_wString sMessageOut,
ON_wString sYesVerbOut,
ON_wString sNoVerbOut,
ON_wString sDontShowAgainIdOut 
) const

Implement this method to provide an 'Are you sure?' message. Only override and implement this if you want such a message.

originis the task origin.
sMessageOutaccepts the message that will be displayed to the user. The message box will have 'Yes' and 'No' buttons and a 'Don't show me this again' check box.
sYesVerbOutprovides alternative text for the 'Yes' button (only used on the Mac).
sNoVerbOutprovides alternative text for the 'No' button (only used on the Mac).
sDontShowAgainIdOutaccepts an identifier which is used to remember if the user chose to not be asked this question again.
true if such a message is required by this task, else false.

◆ GetUndoString()

virtual void CRhRdkTask::GetUndoString ( const IRhRdkTaskOrigin origin,
ON_wString sOut 
) const

Implement this method to provide a custom undo string. The default is automatically created from the menu string.

◆ IconIn()

virtual bool CRhRdkTask::IconIn ( CRhRdkContent::Kinds  kind,
int  width,
int  height,
CRhinoDib dibOut 
) const
An icon for the 'in' or 'checked' state of the menu item or button that initiates this task. Since many operations do not have a 'checked' state, the default implementation returns IconOut().

◆ IconOut()

virtual bool CRhRdkTask::IconOut ( CRhRdkContent::Kinds  kind,
int  width,
int  height,
CRhinoDib dibOut 
) const
An icon for the 'out' or 'unchecked' state of the menu item or button that initiates this task.

◆ Id()

virtual UUID CRhRdkTask::Id ( void  ) const
pure virtual
The task's unique id.

◆ InterfaceId()

virtual UUID CRhRdkTask::InterfaceId ( void  ) const

Returns the unique interface id of this extension.

Implements CRhRdkExtension.

◆ IsEnabled()

virtual bool CRhRdkTask::IsEnabled ( const IRhRdkTaskOrigin origin) const
pure virtual
true if the task is enabled, else false. This is used by content-dependent tasks to disable the task's UI if the wrong number of contents are selected.

Implemented in CRhRdkMultipleContentTask, CRhRdkSingleContentTask, and CRhRdkSimpleTask.

◆ IsForTopLevelContent()

virtual bool CRhRdkTask::IsForTopLevelContent ( void  ) const
true if the task can only operate on top-level content, else false.

Reimplemented in CRhRdkMultipleTopLevelContentTask, and CRhRdkSingleTopLevelContentTask.

◆ MenuOrder()

virtual int CRhRdkTask::MenuOrder ( const IRhRdkTaskOrigin origin) const
pure virtual
the sort order of the task on any menus it appears on.

◆ MenuSeparators()

virtual Separator CRhRdkTask::MenuSeparators ( void  ) const
the menu separators that surround the menu item of this task.

◆ MenuString()

virtual const wchar_t* CRhRdkTask::MenuString ( const IRhRdkTaskOrigin origin,
CRhRdkContent::Kinds  kind 
) const
pure virtual
The menu string for this task.
kindis the kind of top-level content being displayed in the UI that is showing the menu.

◆ Query()

virtual bool CRhRdkTask::Query ( const IRhRdkTaskOrigin origin,
bool  bOnItem 
) const

Query if the task should be displayed to the user in a menu etc. The default implementation returns the result of calling origin.SupportsTask().

originrepresents the UI that the menu was invoked in.
bOnItemis true if the user right-clicked on one or more items (thumbnail, tree node etc). It will be false if the menu was not a context menu, nothing was selected or the user right-clicked on a blank area of the UI. For content/sub-node controls, this is always true.
true if a UI element (e.g., a menu item) should be created for the task, else false.

Reimplemented in CRhRdkCustomTask, CRhRdkMultipleContentTask, and CRhRdkSingleContentTask.

◆ RenderEngineId()

virtual UUID CRhRdkTask::RenderEngineId ( void  ) const

Get the render engine id associated with the task. Only tasks associated with the current renderer will be shown on menus. If this method returns uuidUniversalRenderEngine then the task will always be shown. This is the default.

◆ RequiredDataSources()

static void CRhRdkTask::RequiredDataSources ( OUT ON_SimpleArray< ON_UUID > &  aId)

Returns the ids of the data sources needed to make tasks work.

◆ SetError()

virtual void CRhRdkTask::SetError ( const wchar_t *  wszMessage,
RhRdkMbSeverity  severity 
) const

Set an error message and severity. This is typically called when a task is about to return failure.

◆ SetSelection()

virtual void CRhRdkTask::SetSelection ( const IRhRdkTaskOrigin origin,
const CRhRdkContentArray aContent 
) const

Set the selection so that the user can view and edit a collection of one or more contents.

originis the task origin which represents where the selection should be set.
aContentis the contents to set as the current selection.

◆ SubMenu()

virtual SubMenus CRhRdkTask::SubMenu ( void  ) const
a value from the SubMenus enum which determines if the task can appear on a sub-menu, and which sub-menu it will appear on. The default is 'None'.

Reimplemented in CRhRdkCustomTask.

◆ SupportsSandbox()

virtual bool CRhRdkTask::SupportsSandbox ( void  ) const
true if the task can be used when editing a sandbox document, else false.

◆ Update()

virtual void CRhRdkTask::Update ( IRhRdkTaskUpdate tu) const

Implement this method to update the UI element associated with the task (e.g., a menu). If you do not implement this, the task's UI elements will always appear in an active and unchecked state.

Reimplemented in CRhRdkRequestTask.

◆ UserExecute()

virtual Result CRhRdkTask::UserExecute ( const IRhRdkTaskOrigin origin) const

Execute the task. This method should rarely, if ever, be overridden. As well as executing the task by calling Execute(), it does common operations such as asking if the user is sure, and displaying an error message on failure. The actual task operation is performed by an override of Execute().

◆ UserUpdate()

virtual void CRhRdkTask::UserUpdate ( IRhRdkTaskUpdate tu) const

Update the UI element (e.g., a menu) associated with a task. This method should rarely if ever, be overridden. It first checks if the task is enabled generally by calling IsEnabled(). If the task is enabled, it updates the task's UI by calling Update(). The actual update is performed by an override of Update().