Rhino C++ API  7.24
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
 
- 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
strong

Result codes for Execute()

Enumerator
Success 
Failure 
Cancel 

◆ Separator

enum CRhRdkTask::Separator : unsigned int
strong

This enum is for MenuSeparators()

Enumerator
None 
Before 
After 
Both 

◆ SubMenus

enum CRhRdkTask::SubMenus
strong

This enum is for SubMenu()

Enumerator
None 
CreateNew 
Thumbnails 
PlugIn 

Constructor & Destructor Documentation

◆ CRhRdkTask()

CRhRdkTask::CRhRdkTask ( )

◆ ~CRhRdkTask()

virtual CRhRdkTask::~CRhRdkTask ( )
virtual

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
protected

◆ GetSureMessage()

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

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

Parameters
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.
Returns
true if such a message is required by this task, else false.

◆ GetUndoString()

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

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
virtual
Returns
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
virtual
Returns
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
Returns
The task's unique id.

◆ InterfaceId()

virtual UUID CRhRdkTask::InterfaceId ( void  ) const
finaloverridevirtual

Returns the unique interface id of this extension.

Implements CRhRdkExtension.

◆ IsEnabled()

virtual bool CRhRdkTask::IsEnabled ( const IRhRdkTaskOrigin origin) const
pure virtual
Returns
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
virtual
Returns
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
Returns
the sort order of the task on any menus it appears on.

◆ MenuSeparators()

virtual Separator CRhRdkTask::MenuSeparators ( void  ) const
virtual
Returns
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
Returns
The menu string for this task.
Parameters
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
virtual

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

Parameters
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.
Returns
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
virtual

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)
static
Returns
The ids of the data sources needed to make tasks work.

◆ SetError()

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

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
protectedvirtual

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

Parameters
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
virtual
Returns
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
virtual
Returns
true if the task can be used when editing a sandbox document, else false.

◆ Update()

virtual void CRhRdkTask::Update ( IRhRdkTaskUpdate tu) const
virtual

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
virtual

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
virtual

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().