Rhino C++ API  7.24
Public Member Functions | Friends | List of all members
CRhinoInstanceDefinitionTable Class Reference

#include <rhinoSdkInstance.h>

Inheritance diagram for CRhinoInstanceDefinitionTable:
ON_SimpleArray< CRhinoInstanceDefinition * >

Public Member Functions

 CRhinoInstanceDefinitionTable (CRhinoDoc &)
 
int AddInstanceDefinition (const ON_InstanceDefinition &idef, bool bReference=false, bool bQuiet=false)
 
int AddInstanceDefinition (const ON_InstanceDefinition &idef, const CRhinoObject *object, bool bReference=false, bool bQuiet=false)
 
int AddInstanceDefinition (const ON_InstanceDefinition &idef, const ON_SimpleArray< const CRhinoObject * > &objects, bool bReference=false, bool bQuiet=false)
 
int AddInstanceDefinition (const ON_InstanceDefinition &idef, const ON_SimpleArray< const CRhinoObject * > &objects, unsigned int worksession_ref_model_sn, unsigned int linked_idef_sn, bool bQuiet)
 
CRhinoInstanceObjectAddInstanceObject (int instance_definition_index, ON_Xform instance_xform, const ON_3dmObjectAttributes *instance_attributes=NULL, CRhinoHistory *pHistory=NULL, bool bReference=false)
 
void Compact (bool bIgnoreUndoReferences)
 
int CopyLinkedReferenceStyleBlockDefinition (int source_idef_index, const wchar_t *idef_name, bool bUpdateNewLinkedBlock)
 
int Count () const
 OBSOLETE - USE InstanceDefinitionCount. More...
 
CRhinoInstanceObjectCreateInstanceObject (int instance_definition_index, ON_Xform instance_xform, const ON_3dmObjectAttributes *instance_attributes=NULL, CRhinoHistory *pHistory=NULL, bool bReference=false, bool bInstanceDefinitionObject=false, bool bAddToDoc=true)
 
bool DeleteInstanceDefinition (int idef_index, bool bDeleteReferences, bool bQuiet=false)
 
CRhinoDocDocument () const
 
int FindInstanceDefinition (const wchar_t *idef_name) const
 
int FindInstanceDefinition (ON_UUID idef_uuid, bool bIgnoreDeletedInstanceDefs=true) const
 
int FindInstanceDefinition (unsigned int idef_runtime_sn, bool bIgnoreDeletedInstanceDefs=true) const
 
int FindLinkedInstanceDefinition (int index0, const wchar_t *file_name, bool bRelativePath, bool bIgnoreDeletedInstanceDefs) const
 
void GetSortedList (ON_SimpleArray< const CRhinoInstanceDefinition * > &sorted_list, bool bIgnoreDeleted=false) const
 
void GetUnusedInstanceDefinitionName (const wchar_t *root_name, ON_wString &def_name) const
 
void GetUnusedInstanceDefinitionName (ON_wString &result) const
 
const CRhinoInstanceDefinitionInstanceDefinition (unsigned int sn) const
 
int InstanceDefinitionCount () const
 
void ListTable (ON_TextLog &text_log, unsigned int level_of_detail) const
 
bool ModifyInstanceDefinition (const ON_InstanceDefinition &idef_settings, int idef_index, unsigned int modify_field_mask, bool bQuiet)
 
bool ModifyInstanceDefinitionGeometry (int idef_index, const ON_SimpleArray< const CRhinoObject * > &new_objects, bool bQuiet=false)
 
const CRhinoInstanceDefinitionoperator[] (int idef_index) const
 
bool PromoteTenuousInstanceDefinition (int idef_index, const wchar_t *name)
 
bool PurgeInstanceDefinition (int idef_index)
 
bool SetDescription (int index, const wchar_t *description)
 
bool SetName (int index, const wchar_t *name)
 
void SetRemapIndex (int idef_index, int remap_index)
 
bool SetURL (int index, const wchar_t *url)
 OBSOLETE - USE ModifyInstanceDefinition. More...
 
void Sort (int(*compare)(const CRhinoInstanceDefinition *, const CRhinoInstanceDefinition *, void *), int(*cull)(const CRhinoInstanceDefinition *, void *), void *p=0)
 
const class CRhinoDocTableReferenceTableReference () const
 
bool UndeleteInstanceDefinition (int idef_index)
 
bool UndoModifyInstanceDefinition (int idef_index, unsigned int ur_sn=0)
 
bool UpdateLinkedInstanceDefinition (int idef_index, const wchar_t *filename, bool bUpdateNestedLinks)
 
bool UpdateLinkedInstanceDefinition (int idef_index, const wchar_t *filename, bool bUpdateNestedLinks, bool bQuiet)
 
bool UpdateLinkedInstanceDefinition (int idef_index, const wchar_t *filename, bool bUpdateNestedLinks, CRhFileReadOptions &fro)
 

Friends

class CRhinoDoc
 
class CRhinoRead3dmHelper
 

Constructor & Destructor Documentation

◆ CRhinoInstanceDefinitionTable()

CRhinoInstanceDefinitionTable::CRhinoInstanceDefinitionTable ( CRhinoDoc )

Member Function Documentation

◆ AddInstanceDefinition() [1/4]

int CRhinoInstanceDefinitionTable::AddInstanceDefinition ( const ON_InstanceDefinition idef,
bool  bReference = false,
bool  bQuiet = false 
)

Description: Add an instance definition to the instance definition table.

Parameters: idef - [in] the UUID in idef is used to find the objects bReference - [in] true if this is from a reference file bQuiet - [in] true if errors should be silent

Returns: -1 failure >=0 index of instance definition in the instance definition table.

◆ AddInstanceDefinition() [2/4]

int CRhinoInstanceDefinitionTable::AddInstanceDefinition ( const ON_InstanceDefinition idef,
const CRhinoObject object,
bool  bReference = false,
bool  bQuiet = false 
)

Description: Add an instance definition to the instance definition table.

Parameters: idef - [in] the UUID in idef is ignored. object - [in] will be moved to instance geometry list bReference - [in] true if this is from a reference file bQuiet - [in] true if errors should be silent

Returns: -1 failure >=0 index of instance definition in the instance definition table.

◆ AddInstanceDefinition() [3/4]

int CRhinoInstanceDefinitionTable::AddInstanceDefinition ( const ON_InstanceDefinition idef,
const ON_SimpleArray< const CRhinoObject * > &  objects,
bool  bReference = false,
bool  bQuiet = false 
)

Description: Add an instance definition to the instance definition table.

Parameters: idef - [in] The UUID in idef is ignored. objects - [in] will be moved to instance geometry list bReference - [in] true if this is from a reference file bQuiet - [in] true if errors should be silent

Returns: -1 failure >=0 index of instance definition in the instance definition table.

◆ AddInstanceDefinition() [4/4]

int CRhinoInstanceDefinitionTable::AddInstanceDefinition ( const ON_InstanceDefinition idef,
const ON_SimpleArray< const CRhinoObject * > &  objects,
unsigned int  worksession_ref_model_sn,
unsigned int  linked_idef_sn,
bool  bQuiet 
)

◆ AddInstanceObject()

CRhinoInstanceObject* CRhinoInstanceDefinitionTable::AddInstanceObject ( int  instance_definition_index,
ON_Xform  instance_xform,
const ON_3dmObjectAttributes instance_attributes = NULL,
CRhinoHistory pHistory = NULL,
bool  bReference = false 
)
Parameters
instance_definition_indexOBSOLETE - USE Create...

◆ Compact()

void CRhinoInstanceDefinitionTable::Compact ( bool  bIgnoreUndoReferences)

Description: Purge deleted instance definition information that is not in use. This function is time consuming and should be used in a thoughtful manner.
Parameters: bIgnoreUndoReferences: If false, then deleted instance definition information that could possibly be undeleted by the Undo command will not be deleted. If true, then all deleted instance definition information is deleted.

◆ CopyLinkedReferenceStyleBlockDefinition()

int CRhinoInstanceDefinitionTable::CopyLinkedReferenceStyleBlockDefinition ( int  source_idef_index,
const wchar_t *  idef_name,
bool  bUpdateNewLinkedBlock 
)

Parameters: source_idef_index - [in] index of a block definition with ON_InstanceDefinition::IDEF_UPDATE_TYPE::Linked == ON_InstanceDefinition.InstanceDefinitionType() ON_InstanceDefinition::eLinkedComponentAppearance::Reference == ON_InstanceDefinition.LinkedComponentAppearance() idef_name - [in] If idef_name is not empty, it must be a valid unused name, and the new instance definition will be given this name. If idef_name is nullptr or empty, a new name will be automatically assigned. bUpdateNewLinkedBlock - [in] true if the new linked block should be updated by reading the reference file. false if the caller will take responsibility for updating the new linked block. Returns: -1: copy failed because source_idef_index or idef_name was invalid.

◆ Count()

int CRhinoInstanceDefinitionTable::Count ( ) const

OBSOLETE - USE InstanceDefinitionCount.

◆ CreateInstanceObject()

CRhinoInstanceObject* CRhinoInstanceDefinitionTable::CreateInstanceObject ( int  instance_definition_index,
ON_Xform  instance_xform,
const ON_3dmObjectAttributes instance_attributes = NULL,
CRhinoHistory pHistory = NULL,
bool  bReference = false,
bool  bInstanceDefinitionObject = false,
bool  bAddToDoc = true 
)

◆ DeleteInstanceDefinition()

bool CRhinoInstanceDefinitionTable::DeleteInstanceDefinition ( int  idef_index,
bool  bDeleteReferences,
bool  bQuiet = false 
)

Description: Deletes instance definition. Parameters: idef_index - [in] zero based index of instance definition to delete. This must be in the range 0 <= idef_index < InstanceDefinitionCount(). bDeleteReferences - [in] true to delete all references to this definition. False to delete definition only if there are no references. bQuiet - [in] If TRUE, no warning message box appears if an instance definition cannot be deleted because it is the current layer or it contains active geometry. Returns: TRUE if successful. false if the instance definition has active references and bDeleteReferences is false.

◆ Document()

CRhinoDoc& CRhinoInstanceDefinitionTable::Document ( ) const

◆ FindInstanceDefinition() [1/3]

int CRhinoInstanceDefinitionTable::FindInstanceDefinition ( const wchar_t *  idef_name) const

Description: Finds the instance definition with a given name.

Parameters: idef_name - [in] name of instance definition to search for. The search ignores case.

Returns: >=0 index of the instance definition with the given name -1 no instance definition has the given name

◆ FindInstanceDefinition() [2/3]

int CRhinoInstanceDefinitionTable::FindInstanceDefinition ( ON_UUID  idef_uuid,
bool  bIgnoreDeletedInstanceDefs = true 
) const

Description: Finds the instance definition with a given name.

Parameters: idef_uuid - [in] Unique id of the instance definition to search for. The search ignores case.

bIgnoreDeletedInstanceDefs - [in] true means don't search deleted instance definitions.

Returns: >=0 index of the instance definition with the given name -1 no instance definition has the given name

◆ FindInstanceDefinition() [3/3]

int CRhinoInstanceDefinitionTable::FindInstanceDefinition ( unsigned int  idef_runtime_sn,
bool  bIgnoreDeletedInstanceDefs = true 
) const

Description: Finds the instance definition with a given name.

Parameters: idef_runtime_sn - [in] value of CRhinoInstanceDefinition::m_idef_runtime_sn

bIgnoreDeletedInstanceDefs - [in] true means don't search deleted instance definitions.

Returns: >=0 index of the instance definition with the given name -1 no instance definition has the given name

◆ FindLinkedInstanceDefinition()

int CRhinoInstanceDefinitionTable::FindLinkedInstanceDefinition ( int  index0,
const wchar_t *  file_name,
bool  bRelativePath,
bool  bIgnoreDeletedInstanceDefs 
) const

Description: Searches for an instance definition the is in some way linked to a file.

Parameters: index0 - [in] Searching the idef table begins at this index. Pass 0 to search the entire table. This is used to continue searching after finding the first idef to be linked to a file. file_name - [in] name of a file. The search ignores case. bRelativePath - [in] true if file_name is relative to the current document's location bIgnoreDeletedInstanceDefs - [in] true means don't search deleted instance definitions. Returns: >=0 index of the instance definition linked to a file. -1 no instance definition has the given name

◆ GetSortedList()

void CRhinoInstanceDefinitionTable::GetSortedList ( ON_SimpleArray< const CRhinoInstanceDefinition * > &  sorted_list,
bool  bIgnoreDeleted = false 
) const

Description: Gets an array of pointers to layers that is sorted by the values of CRhinoInstanceDefinition::m_sort_index.

Parameters: sorted_list - [out] this array is filled in with CRhinoInstanceDefinition pointers sorted by the values of CRhinoInstanceDefinition::m_sort_index. bIgnoreDeleted - [in] if TRUE then deleted layers are filtered out.

Remarks: Use Sort() to set the values of m_sort_index.

◆ GetUnusedInstanceDefinitionName() [1/2]

void CRhinoInstanceDefinitionTable::GetUnusedInstanceDefinitionName ( const wchar_t *  root_name,
ON_wString def_name 
) const

◆ GetUnusedInstanceDefinitionName() [2/2]

void CRhinoInstanceDefinitionTable::GetUnusedInstanceDefinitionName ( ON_wString result) const

Description: Gets unused instance definition name. Used as default when creating new instance definitions. Parameters: root_name - [in] The returned name is "root_name nn" If root_name is empty, then "Block" (localized) is used. def_suffix - [in/out] Unique names are created by appending a decimal number to the localized term for "Block" as in "Block 01", "Block 02", and so on. When def_suffix is not null, the search for an unused name begins at "Block suffix". When suffix is null the search begins at "Block 01". The output value of def_suffix is the value of the appended number used to create the unused instance definition name. def_name - [out] A valid instance definition name that is not in use.

◆ InstanceDefinition()

const CRhinoInstanceDefinition* CRhinoInstanceDefinitionTable::InstanceDefinition ( unsigned int  sn) const

Description: Find the instance defintion that has the specified serial number. Parameters: sn - [in] runtime serial number Returns: Pointer to the instance definition. This pointer may be null.

◆ InstanceDefinitionCount()

int CRhinoInstanceDefinitionTable::InstanceDefinitionCount ( ) const

Returns: Number of items in the instance definitions table, including deleted layers.

◆ ListTable()

void CRhinoInstanceDefinitionTable::ListTable ( ON_TextLog text_log,
unsigned int  level_of_detail 
) const

◆ ModifyInstanceDefinition()

bool CRhinoInstanceDefinitionTable::ModifyInstanceDefinition ( const ON_InstanceDefinition idef_settings,
int  idef_index,
unsigned int  modify_field_mask,
bool  bQuiet 
)

Description: Modify instance definition settings (name, url, description). Does not change instance defintion uuid or geometry.

Parameters: idef_settings - [in] new settings. (The uuid list is ignored.) idef_index - [in] zero based index of layer to set. This must be in the range 0 <= layer_index < LayerCount(). idef_settings_mask - [in] Bitfield with values from ON_InstanceDefinition::idef_*_settings enum. If a bit is set, then the corresponding values in idef_settings are used to modify the instance definition. bQuiet - [in] if TRUE, information message boxes pop up when illegal changes are attempted.

Returns: TRUE if successful. FALSE if layer_index is out of range or the settings attempt to lock or hide the current layer.

Example:
/ Modify instance definition name and url

      CRhinoInstanceDefinitionTable& idef_table = doc.m_instance_definition_table;

      int idef_index = ...;

      ON_InstanceDefinition idef_settings;
      idef_settings.m_name    = L"Barcelona Map";
      idef_settings.m_url     = L"http://en.wikipedia.org/wiki/Barcelona";
      idef_settings.m_url_tag = L"Barcelona";

      idef_mask = ON_InstanceDefinition::idef_name_setting
               | ON_InstanceDefinition::idef_url_setting;

      idef_table.ModifyInstanceDefiition(idef_settings,idef_index,idef_mask);

/ Modify all settings CRhinoInstanceDefinition* idef = idef_table[idef_index]; ON_InstanceDefinition idef_settings = *idef; ///< copy existing settings idef_settings.m_... = ...; ///< make necessary changes idef_table.ModifyInstanceDefiition( idef_settings, idef_index, ON_InstanceDefinition::all_idef_settings);

See Also: CRhinoInstanceDefinitionTable::ModifyInstanceDefinitionGeometry

◆ ModifyInstanceDefinitionGeometry()

bool CRhinoInstanceDefinitionTable::ModifyInstanceDefinitionGeometry ( int  idef_index,
const ON_SimpleArray< const CRhinoObject * > &  new_objects,
bool  bQuiet = false 
)

Description: Modify instance definition geometry and replace all references to the current definition with references to the new definition.

Parameters: idef_index - [in] zero based index of the instance definition to change. new_objects - [in] new geometry for the instance definition. bQuiet - [in] if TRUE, information message boxes pop up when illegal changes are attempted.

Returns: index of the new definition or -1 if it fails

See Also: CRhinoInstanceDefinitionTable::ModifyInstanceDefinitionGeometry

◆ operator[]()

const CRhinoInstanceDefinition* CRhinoInstanceDefinitionTable::operator[] ( int  idef_index) const

Description: Conceptually, the instance definition table is an array of InstanceDefinitionCount() elements. The operator[] can be used to get individual instance definitions. Parameters: idef_index - [in] zero based array index Returns: Pointer to the instance definition. This pointer may be null.

◆ PromoteTenuousInstanceDefinition()

bool CRhinoInstanceDefinitionTable::PromoteTenuousInstanceDefinition ( int  idef_index,
const wchar_t *  name 
)

Description: If an instance definition is present because it was created while reading a linked idef, it is not saved in the file. Call PromoteTenuousInstanceDefinition will modify the idef so it is a "real" idef in the file.

◆ PurgeInstanceDefinition()

bool CRhinoInstanceDefinitionTable::PurgeInstanceDefinition ( int  idef_index)

Description: Purges an instance definition and its definition geometry. Parameters: idef_index - [in] zero based index of instance definition to delete. This must be in the range 0 <= idef_index < InstanceDefinitionCount(). Returns: True if successful. False if the instance definition cannot be purged because it is in use by reference objects or undo information.

◆ SetDescription()

bool CRhinoInstanceDefinitionTable::SetDescription ( int  index,
const wchar_t *  description 
)

◆ SetName()

bool CRhinoInstanceDefinitionTable::SetName ( int  index,
const wchar_t *  name 
)

◆ SetRemapIndex()

void CRhinoInstanceDefinitionTable::SetRemapIndex ( int  idef_index,
int  remap_index 
)

◆ SetURL()

bool CRhinoInstanceDefinitionTable::SetURL ( int  index,
const wchar_t *  url 
)

OBSOLETE - USE ModifyInstanceDefinition.

◆ Sort()

void CRhinoInstanceDefinitionTable::Sort ( int(*)(const CRhinoInstanceDefinition *, const CRhinoInstanceDefinition *, void *)  compare,
int(*)(const CRhinoInstanceDefinition *, void *)  cull,
void *  p = 0 
)

Description: Use this to set CRhinoInstanceDefinition::m_sort_index so that the values of m_sort_index run from 0 to InstanceDefinitionCount()-1 and compare( idef_table[i], idef_table[j]) < 0 ) implies idef_table[i].m_sort_index < idef_table[j].m_sort_index.

Parameters: compare - [in] compare function with prototype that returns <0 if arg1<arg2, 0 if arg1=arg2, and >0 if arg1>arg2. cull - [in] optional filter function that returns TRUE if the instance definition should be ignored when sorting. Instance definitions that are ignored are not included in the list returned by GetSortedList(). Pass 0 if you do not need to cull instance definitions. p - [in] pointer passed as last argument to compare() and cull().

Remarks: After calling Sort(), you can repeatedly call GetSortedList() to get a sorted list of CRhinoInstanceDefinition pointers.
Sort() and GetSortedList() do not modify the order or persistent information in the layer table. They are intended to be used to get sorted lists of instance definitions for dialogs, etc.

◆ TableReference()

const class CRhinoDocTableReference& CRhinoInstanceDefinitionTable::TableReference ( ) const

◆ UndeleteInstanceDefinition()

bool CRhinoInstanceDefinitionTable::UndeleteInstanceDefinition ( int  idef_index)

Description: Undeletes an instance definition that has been deleted by DeleteLayer(). Parameters: idef_index - [in] zero based index of an instance definition to undelete. This must be in the range 0 <= idef_index < InstanceDefinitionCount(). Returns: TRUE if successful.

◆ UndoModifyInstanceDefinition()

bool CRhinoInstanceDefinitionTable::UndoModifyInstanceDefinition ( int  idef_index,
unsigned int  ur_sn = 0 
)

Description: If the instance definition has been modified and the modifcation can be undone, then UndoModifyInstanceDefinition() will restore the instance definition to its previous state. Returns: TRUE if this layer had been modified and the modifications were undone.

◆ UpdateLinkedInstanceDefinition() [1/3]

bool CRhinoInstanceDefinitionTable::UpdateLinkedInstanceDefinition ( int  idef_index,
const wchar_t *  filename,
bool  bUpdateNestedLinks 
)

Description: Read the objects from a file and use them as the instance's definition geometry. Parameters: idef_index - [in] instance definition index filename - [in] name of file (can be any type of file that Rhino or a plug-in can read). bUpdateNestedLinks - [in] If true and the instance definition referes to a linked instance definition, that needs to be updated, then the nested defition is also updated. If false, nested updates are skipped. Returns: True if successful.

◆ UpdateLinkedInstanceDefinition() [2/3]

bool CRhinoInstanceDefinitionTable::UpdateLinkedInstanceDefinition ( int  idef_index,
const wchar_t *  filename,
bool  bUpdateNestedLinks,
bool  bQuiet 
)

◆ UpdateLinkedInstanceDefinition() [3/3]

bool CRhinoInstanceDefinitionTable::UpdateLinkedInstanceDefinition ( int  idef_index,
const wchar_t *  filename,
bool  bUpdateNestedLinks,
CRhFileReadOptions &  fro 
)

24 Oct 2014 - Lowell - Added a function to pass through the file read options to updates of nested linked blocks rh-28779

Friends And Related Function Documentation

◆ CRhinoDoc

friend class CRhinoDoc
friend

◆ CRhinoRead3dmHelper

friend class CRhinoRead3dmHelper
friend