Rhino C++ API  7.24
Public Types | Public Member Functions | Static Public Attributes | Friends | List of all members
CRhinoFileReadOptions Class Reference

#include <rhinoSdkFileOptions.h>

Public Types

enum  ModeFlag : unsigned int {
  ModeFlag::ImportMode = 0, ModeFlag::OpenMode, ModeFlag::NewMode, ModeFlag::InsertMode,
  ModeFlag::ImportReferenceMode, ModeFlag::BatchMode, ModeFlag::UseScaleGeometry, ModeFlag::ScaleGeometry,
  ModeFlag::ScriptUpdateEmbededInstanceDefinitions, ModeFlag::UpdatingExistingInstanceDefinitions, ModeFlag::ModeCount
}
 

Public Member Functions

 CRhinoFileReadOptions ()
 
 CRhinoFileReadOptions (bool bImport)
 
 CRhinoFileReadOptions (const CRhinoFileReadOptions &)
 
 ~CRhinoFileReadOptions ()
 
const class ON_ManifestMapArchiveToModelIdentificationMap () const
 
CRhinoDocDestinationDocument () const
 
unsigned int DestinationDocumentSerialNumber () const
 
int ExistingLayerNameMatchingStyle () const
 
bool GetFileAlias (ON_wString &file_alias) const
 
bool GetFileName (ON_wString &file_name) const
 
bool GetFullPath (ON_wString &full_path) const
 
*int GetMissingLinkedFileQueryAction () const
 
  • / 22 Oct 2014 - Lowell - Added the answer about browsing for missing
More...
 
void GetModelItemId (ON_UUID file_item_id, ON_UUID *model_item_id) const
 
bool GetReferenceModelComponentName (const wchar_t *original_name, ON_wString &reference_component_name) const
 
unsigned int InstanceDefinitionSerialNumber () const
 
ON_InstanceDefinition::eLinkedComponentAppearance LinkedInstanceDefinitionLayerStyle () const
 
unsigned int LinkedInstanceDefinitionSerialNumber () const
 
RhinoYesNoResponse LookForMissingFile () const
 
bool Merge () const
 
bool Mode (ModeFlag mode_to_check) const
 
ON_UnitSystem ModelUnitSystem () const
 
double ModelUnitSystemScale (ON::LengthUnitSystem file_unit_system) const
 
double ModelUnitSystemScale (ON_UnitSystem file_unit_system) const
 
bool NoUserInterfaceQuestions () const
 
CRhinoFileReadOptionsoperator= (const CRhinoFileReadOptions &)
 
ON_UUID ReaderId () const
 
bool ReadingPrimaryFile () const
 
bool ReadingReferenceModel () const
 
bool ReadingRhinoModel () const
 
bool ReadingSecondaryFile () const
 
int ReadingStatus () const
 
bool ReadingTemplateFile () const
 
const ON_wString ReferanceModelComponentNamePrefix (bool bAppendReferenceNameSeparator) const
 
ON_UUID ReferenceModelGrandParentLayerId () const
 
unsigned int RhinoArchiveOpenNURBSVersion () const
 
unsigned int RhinoArchiveVersion () const
 
bool SetDestinationDocument (const CRhinoDoc *destination_document)
 
void SetLookForMissingFile (RhinoYesNoResponse look_for_missing_file)
 
*void SetMissingLinkedFileQueryAction (int action)
 
void SetMode (ModeFlag mode_to_set, bool bEnabled)
 
ON_UnitSystem SourceModelUnitSystem () const
 
unsigned int WorkSessionReferenceModelSerialNumber () const
 

Static Public Attributes

static const CRhinoFileReadOptions ImportModelDefaults
 
static const CRhinoFileReadOptions ImportReferenceModelDefaults
 
static const CRhinoFileReadOptions OpenModelDefaults
 
static const CRhinoFileReadOptions OpenTemplateDefaults
 
static const CRhinoFileReadOptions Unset
 

Friends

class CRhFileReadOptions
 

Member Enumeration Documentation

◆ ModeFlag

enum CRhinoFileReadOptions::ModeFlag : unsigned int
strong
Enumerator
ImportMode 

If you need to make any additions or changes to these enum values, then please read comment in
CRhinoFileReadOptions::CRhinoFileReadOptions(). These mode names are confusing and misleading, but they cannot be changed or the SDK will break. Read the comments carefully. When in doubt, read everything and put it in the model. ImportMode: true means we are merging whatever is being read into an existing document. This means you need to consider things like:

  • If the information being read is in a different unit system, it should be scaled if UseScaleGeometry is true.
  • There can be existing layers, fonts, materials, dimension styles, hatch patterns, and so on with the same name as items being read from the file.
OpenMode 

OpenMode: true means we are reading the information into an empty document. This means you need to consider things like:

  • Setting the unit system (if the file has a unit system)
  • Creating a default layer if one is not there.
  • Setting up appropriate views when you're finished reading.
NewMode 

NewMode: (default = false) true means we are reading template information in something like a OnFileNew event.

InsertMode 

InsertMode: true means we are reading information that will be used to create an instance definition or some other type of "inserting" that is supported by Rhino's "Insert" command.

ImportReferenceMode 

ImportReferenceMode: (default = false) true means we are reading information for a work session reference model or a linked instance definition.

BatchMode 

BatchMode: (default = false) true means you cannot ask questions during reading. (no dialogs, no "getters", etc.)

UseScaleGeometry 

UseScaleGeometry: (default = true) If this parameter is true, then no questions are asked when unit conversion scaling is optional and the setting specified by ScaleGeometry is used.

ScaleGeometry 

ScaleGeometry: (default = true) true: If ImportMode is true and the geometry in the file being read has a unit system different from the model's unit system, then apply the unit conversion scale to the file's geometry before adding it to the model.

false: Do not scale. Once case where this happens is when an instance definition is read from a file and the model space instance references have been scaled. In case the instance definition geometry cannot be scaled or the net result is that the size of the instance reference object is scaled by the square of the scale factor.

ScriptUpdateEmbededInstanceDefinitions 

ScriptUpdateEmbededInstanceDefinitions: (default = true) When an embedded instance definition is out of date, settings in document properties and on the instance definition control if the idef is not updated, automatically updated, or the user is asked if they want to update. In the case where the settings indicate the user should be asked, but BatchMode is true (and we can't ask), we need to have an automatic way to decide what to do. In this case (BatchMode = true and doc/idef settings indicate user should be asked, the value of ScriptUpdateEmbededInstanceDefinitions mode is used to decide if the out-of-date instance definitions should be updated. If this is confusing, then use the default (=true) setting.

UpdatingExistingInstanceDefinitions 

UpdatingExistingInstanceDefinitions: (default = false) Set to true when an existing instance definition is being updated and when instance defintion name collisions occur, the existing instance definition should be silently updated.

ModeCount 

Constructor & Destructor Documentation

◆ CRhinoFileReadOptions() [1/3]

CRhinoFileReadOptions::CRhinoFileReadOptions ( )

plug-in developers: Avoid creating local CRhinoFileReadOptions classes Instead use const CRhinoFileReadOptions& RhinoApp().FileReadOptions() when you need the current file reading options.

◆ CRhinoFileReadOptions() [2/3]

CRhinoFileReadOptions::CRhinoFileReadOptions ( bool  bImport)

◆ CRhinoFileReadOptions() [3/3]

CRhinoFileReadOptions::CRhinoFileReadOptions ( const CRhinoFileReadOptions )

◆ ~CRhinoFileReadOptions()

CRhinoFileReadOptions::~CRhinoFileReadOptions ( )

Member Function Documentation

◆ ArchiveToModelIdentificationMap()

const class ON_ManifestMap& CRhinoFileReadOptions::ArchiveToModelIdentificationMap ( ) const

Description: ArchiveToModelIdentificationMap() returns a mapping from archive (file) identification (component type, index, id) to model component identification.

◆ DestinationDocument()

CRhinoDoc* CRhinoFileReadOptions::DestinationDocument ( ) const

Returns: CRhinoDoc::FromRuntimeSerialNumber(DestinationDocumentSerialNumber()); Remarks: You must check for a nullptr before dereferencing the returned pointer.

◆ DestinationDocumentSerialNumber()

unsigned int CRhinoFileReadOptions::DestinationDocumentSerialNumber ( ) const

Returns: The runtime serial number of the CRhinoDoc that is the destination of the information read from the file.

Example:

CRhinoDoc* doc = CRhinoDoc::FromRuntimeSerialNumber(fro.DestinationDocumentSerialNumber());
if (nullptr == doc)
  ... no destination document ...
else
  ...

◆ ExistingLayerNameMatchingStyle()

int CRhinoFileReadOptions::ExistingLayerNameMatchingStyle ( ) const

Description: When some sort if import is happening (import, paste, insert, ...) this setting controls how Rhino looks for maching existing layers. The Returns: 0: Use full path layer name from file. 1: If there is already an active layer with the same short name, then use it. For example, if the current model has a layer tree that looks like X Y Z

and the file being read has a layer tree that looks like P Q X Y Z

then the file object on file layer P::X ends up on model layer X, the file objects on file layer Y end up on on model layer X::Y and the file objects on file layer Y::Z end up on model layer X::Z. Remarks: When a worksession reference model is being read, 0 is always returned. When a linked instance definition reference model is being read, the value of ON_InstanceDefinition::m_idef_layer_style determines what value this function returns. Otherwise, the value returned by RhinoApp().AppSettings().ImportFileLayerMatchingOption() determines what value this function returns.

◆ GetFileAlias()

bool CRhinoFileReadOptions::GetFileAlias ( ON_wString file_alias) const

Description: The file alias is generally the same as the file name with extension, but sometimes includes some portion of the directory path to avoid confusion when ther are several files in play with the same name. This string is used in user interface to identify the file when the absolute path name is too long to be useful and can be found someplace else in the user interface. Parameters: file_alias - [out] Returns: True if an alias existed.

◆ GetFileName()

bool CRhinoFileReadOptions::GetFileName ( ON_wString file_name) const

Parameters: file_name - [out] The file name, including the extension. Does not include drive or directory information. Returns: True if the value was returned.

◆ GetFullPath()

bool CRhinoFileReadOptions::GetFullPath ( ON_wString full_path) const

Parameters: full_path - [out] Absolute path to the file, including the drive, directory and file name with extension. Returns: True if the full path is available. False if not.

◆ GetMissingLinkedFileQueryAction()

* int CRhinoFileReadOptions::GetMissingLinkedFileQueryAction ( ) const

  • / 22 Oct 2014 - Lowell - Added the answer about browsing for missing

linked blocks to FileReadOptions rh-28779 Description: Sets or returns the current answer to the question of Ignoring missing linked block files asked while reading a 3dm file. In particular, if a user has already answered yes to all (rc_yes_to_all) no to all (rc_no_to_all), don't ask again.

◆ GetModelItemId()

void CRhinoFileReadOptions::GetModelItemId ( ON_UUID  file_item_id,
ON_UUID model_item_id 
) const

Description: This function is provided for plug-ins to use when their CRhinoPlugIn::ReadDocument() function is called and they need to convert Rhino document item ids used in a .3dm file that was just read into the Rhino document item ids used in the runtime model.

When a file is read, sometimes is is necessary to change the id of an item in a file to a new id in the runtime model. This often happens when one file is being imported into an existing document and an id found in the file is already in use in the existing document. An "item" can be anything in a table, like a layer, material, dimension style, geometry object, instance definition, and so on. Parameters: file_item_id - [in] id used for the item in the .3dm file being read. model_item_id - [out] id used to for the item in the runtime model See Also: CRhinoFileReadOptions::ArchiveToModelIdentificationMap()

◆ GetReferenceModelComponentName()

bool CRhinoFileReadOptions::GetReferenceModelComponentName ( const wchar_t *  original_name,
ON_wString reference_component_name 
) const

Description: When reference information is imported, name of model components like annotation styles, hatch patterns, block definitions, ..., have a reference prefix prepended to the original name. Parameters: original_name - [in] reference_component_name - [out] both paramters can be the same string. Example: If a block definition named "X" is in a reference file named C.3dm, then the reference_component_name will be "C.3dm : X". If the component is being read from a nested linked instance definition, the reference_component_name will be something like "A.3dm>B.3dm>C.3dm : X"

Returns: True if reference_component_name name was modified by prepending a prefix. False if reference_component_name is identical to original_name.

◆ InstanceDefinitionSerialNumber()

unsigned int CRhinoFileReadOptions::InstanceDefinitionSerialNumber ( ) const

Returns: 0: Reading the active model. >0: Serial number of an instance definition based on the contents of the file being read. When an instance defintion is being created, the instance definition may be of any type (static_def, linked_and_embedded_def, or linked_def). When an instance definition is being updated, the instance definition can be linked_and_embedded_def, or linked_def.

◆ LinkedInstanceDefinitionLayerStyle()

ON_InstanceDefinition::eLinkedComponentAppearance CRhinoFileReadOptions::LinkedInstanceDefinitionLayerStyle ( ) const

Returns: 0: unset 1: active Use short name to find a matching active layer. If none is found, then create the layer using the full path as an active layer (no grandparent layer). 2: reference Put the idef Remarks: When a linked instance defintion is being read in an active model, then this returns the value of ON_InstanceDefinition.m_idef_layer_style for the idef. Note that simple layer names

◆ LinkedInstanceDefinitionSerialNumber()

unsigned int CRhinoFileReadOptions::LinkedInstanceDefinitionSerialNumber ( ) const

Returns: 0: Not reading a linked instance definition. >0: Serial number of a linked instance definition being read or one that is being updated. For example, if a linked and embedded idef is being updated and it is nested inside of a linked idef, then this function will return the serial number of the linked idef.

◆ LookForMissingFile()

RhinoYesNoResponse CRhinoFileReadOptions::LookForMissingFile ( ) const

◆ Merge()

bool CRhinoFileReadOptions::Merge ( ) const

Returns: true: The inforation being read is being merged into the existing document. This happens in a number of cases including but not limited to reading work session reference files, reading instance defitions, anything done by the Insert command, harvesting various things like materials, page layouts, annotation styles and hatch patterns from files. false: The inforation being read is being used to create a new document. Remarks: This is identical to the Mode(CRhinoFileReadOptions::ModeFlag::ImportMode) setting.

◆ Mode()

bool CRhinoFileReadOptions::Mode ( ModeFlag  mode_to_check) const

Description: Check which modes are enabled for file reading.
More than one mode can be enabled for a file read. Parameters: mode_to_check - [in] Example: bool bImportMode = file_options.Mode(CRhinoFileReadOptions::ModeFlag::ImportMode ); bool bOpenMode = file_options.Mode(CRhinoFileReadOptions::ModeFlag::OpenMode ); bool bNewMode = file_options.Mode(CRhinoFileReadOptions::ModeFlag::NewMode ); bool bBatchMode = file_options.Mode(CRhinoFileReadOptions::ModeFlag::BatchMode ); Returns: TRUE if mode_to_check is active. See Also: ReadingTemplateFile(), ReadingPrimaryFile(), ReadingTemplateFile()

◆ ModelUnitSystem()

ON_UnitSystem CRhinoFileReadOptions::ModelUnitSystem ( ) const

Returns: The model space unit system used by the model the file is being read into. Remarks: When the ScaleGeometry mode setting is false, do not apply unit system scaling.

◆ ModelUnitSystemScale() [1/2]

double CRhinoFileReadOptions::ModelUnitSystemScale ( ON::LengthUnitSystem  file_unit_system) const

Parameters: file_unit_system - [in] unit system for an object read from the file Returns: The unit system conversion scale factor to apply to model space objects from the file. Remarks: When the ScaleGeometry mode setting is false, do not apply unit system scaling.

◆ ModelUnitSystemScale() [2/2]

double CRhinoFileReadOptions::ModelUnitSystemScale ( ON_UnitSystem  file_unit_system) const

Parameters: file_unit_system - [in] unit system for an object read from the file Returns: The unit system conversion scale factor to apply to model space objects from the file. Remarks: When the ScaleGeometry mode setting is false, do not apply unit system scaling.

◆ NoUserInterfaceQuestions()

bool CRhinoFileReadOptions::NoUserInterfaceQuestions ( ) const

Returns: true: You may not ask any questions while the the file is being read. Specifically, no dialogs and no "getter" prompts are permitted. This happens in a number of cases including situations where files are being "batch mode" processed and users will be grumpy if they start a long job, go home, and return the next morning to discover their job didn't finish because you interrupted the reading to ask a question. false: You may ask the user questions. Remarks: This is identical to the Mode(CRhinoFileReadOptions::ModeFlag::BatchMode) setting.

◆ operator=()

CRhinoFileReadOptions& CRhinoFileReadOptions::operator= ( const CRhinoFileReadOptions )

◆ ReaderId()

ON_UUID CRhinoFileReadOptions::ReaderId ( ) const

Returns: id that identifies what is doing the reading. If RhinoApp().IsRhinoUUID(id) is true, then Rhino is reading a Rhino model (typically .3dm file).
If id is not nill and RhinoApp().IsRhinoUUID(id) is false, then the id identifies the CRhinoPlugIn that is reading the file.

◆ ReadingPrimaryFile()

bool CRhinoFileReadOptions::ReadingPrimaryFile ( ) const

Returns: True means an empty document is being filled with the contents of the file during something like an "Open" Remarks: Exactly one of ReadingTemplateFile(), ReadingPrimaryFile(), or ReadingSecondaryFile() is true.

◆ ReadingReferenceModel()

bool CRhinoFileReadOptions::ReadingReferenceModel ( ) const

Returns: True if a reference model is being read. This is always the case for worksession reference models and linked instance definitions. It may happen in other less common situations.

◆ ReadingRhinoModel()

bool CRhinoFileReadOptions::ReadingRhinoModel ( ) const

Returns: True if a Rhino model (typically a .3dm file) is being read. False otherwise.

◆ ReadingSecondaryFile()

bool CRhinoFileReadOptions::ReadingSecondaryFile ( ) const

Returns: True means something like an import or insert or worksession reference file is being read into an existing docuemnt. Remarks: Exactly one of ReadingTemplateFile(), ReadingPrimaryFile(), or ReadingSecondaryFile() is true.

◆ ReadingStatus()

int CRhinoFileReadOptions::ReadingStatus ( ) const

Returns: 0: no stuatus 1: reading in progress 2: reading initial file successful 3: updating linked idefs found in this file 99: reading finished successfully 100: reading failed.

◆ ReadingTemplateFile()

bool CRhinoFileReadOptions::ReadingTemplateFile ( ) const

Returns: True if a template file is being read during something like a "New" Remarks: Exactly one of ReadingTemplateFile(), ReadingPrimaryFile(), or ReadingSecondaryFile() is true.

◆ ReferanceModelComponentNamePrefix()

const ON_wString CRhinoFileReadOptions::ReferanceModelComponentNamePrefix ( bool  bAppendReferenceNameSeparator) const

Parameters: bAppendReferenceNameSeparator - [in] If true and the reference prefix is not empty, then ON_ModelComponent::NameReferenceDelimiter (" : ") is append to the returned string. Returns: If a reference model is being read, the prefix for reference model components. Otherwise, empty string.

◆ ReferenceModelGrandParentLayerId()

ON_UUID CRhinoFileReadOptions::ReferenceModelGrandParentLayerId ( ) const

Description: Information that ultimately is part of a work session reference model or linked instance definition model is being read, all layers are added as sub-layers of a grand-parent layer. When the information being read is destined for the active model, no grand parent layer is used. Returns: nil: no grand parent layer is in use. non-nil: id of grand parent layer.

◆ RhinoArchiveOpenNURBSVersion()

unsigned int CRhinoFileReadOptions::RhinoArchiveOpenNURBSVersion ( ) const

Returns: 0: Not reading a Rhino file. >0: opernnurbs version Remarks: The hight bit of the version number is typically set. Do not cast this value as an int.

◆ RhinoArchiveVersion()

unsigned int CRhinoFileReadOptions::RhinoArchiveVersion ( ) const

Returns: 0: Not reading a Rhino file. 1: Reading a Rhino 1 file. 2: Reading a Rhino 2 file. 3: Reading a Rhino 3 file. 4: Reading a Rhino 4 file. 5: Reading a 32-bit Rhino 5 file (file size limited to 4GB) 50: Reading a 64-bit Rhino 5 file 60: Reading a Rhino 6 file ...

◆ SetDestinationDocument()

bool CRhinoFileReadOptions::SetDestinationDocument ( const CRhinoDoc destination_document)

Parameters: destination_document - [in] The CRhinoDoc that is the destination of the information read from the file. Returns: True if the destination document was set. False if the caller attempted to change the destination from one document to another.

◆ SetLookForMissingFile()

void CRhinoFileReadOptions::SetLookForMissingFile ( RhinoYesNoResponse  look_for_missing_file)

◆ SetMissingLinkedFileQueryAction()

* void CRhinoFileReadOptions::SetMissingLinkedFileQueryAction ( int  action)

◆ SetMode()

void CRhinoFileReadOptions::SetMode ( ModeFlag  mode_to_set,
bool  bEnabled 
)

Description: Set modes for file reading.
More than one mode can be enabled for a file read. Parameters: mode_to_set - [in] bEnabled - [in] Example: / set batch import mode file_options.SetMode(CRhinoFileReadOptions::ModeFlag::ImportMode, TRUE ); file_options.SetMode(CRhinoFileReadOptions::ModeFlag::BatchMode, TRUE );

◆ SourceModelUnitSystem()

ON_UnitSystem CRhinoFileReadOptions::SourceModelUnitSystem ( ) const

Returns: The model space unit system used by the model the file is being read out of (in the case of import, insert etc). Remarks: When the ScaleGeometry mode setting is false, do not apply unit system scaling.

◆ WorkSessionReferenceModelSerialNumber()

unsigned int CRhinoFileReadOptions::WorkSessionReferenceModelSerialNumber ( ) const

Returns: 0: Information being read will be added to the active model. >0: Serial number of a work session reference model based on the contents of the file being read.

Friends And Related Function Documentation

◆ CRhFileReadOptions

friend class CRhFileReadOptions
friend

Member Data Documentation

◆ ImportModelDefaults

const CRhinoFileReadOptions CRhinoFileReadOptions::ImportModelDefaults
static

◆ ImportReferenceModelDefaults

const CRhinoFileReadOptions CRhinoFileReadOptions::ImportReferenceModelDefaults
static

◆ OpenModelDefaults

const CRhinoFileReadOptions CRhinoFileReadOptions::OpenModelDefaults
static

◆ OpenTemplateDefaults

const CRhinoFileReadOptions CRhinoFileReadOptions::OpenTemplateDefaults
static

◆ Unset

const CRhinoFileReadOptions CRhinoFileReadOptions::Unset
static