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

#include <rhinoSdkFileOptions.h>

Public Types

enum  WriteFailedReasons : unsigned int {
  kUnsetReason = 0, kUserCanceled, kEvaluationPeriodExpired, kAnotherWriteInProgress,
  kEmptyFileName, kInvalidFileName, kFileIsReadOnly, kFileIsLocked,
  kUnableToOpenFile, kUnableToOpenTemporaryFile, kUnableToRenameTemporaryFile, kUnableToReplaceFile,
  kUnableToLoadPlugIn, kFileTypeIdDoesNotIdentifyAFileWritingPlugIn, kFileWritingPlugInFailed, kDeviceFull,
  kDeviceWriteFailed, kDeviceSeekFailed, kInputValidationFailed, kWriteFailedStartSection,
  kWriteFailedPropertiesTable, kWriteFailedSettingsTable, kWriteFailedBitmapTable, kWriteFailedTextureMappingTable,
  kWriteFailedMaterialTable, kWriteFailedLinetypeTable, kWriteFailedLayerTable, kWriteFailedGroupTable,
  kWriteFailedDimensionStyleTable, kWriteFailedLightTable, kWriteFailedHatchPatternTable, kWriteFailedInstanceDefinitionTable,
  kWriteFailedObjectTable, kWriteFailedHistoryRecordTable, kWriteFailedUserTable, kWriteFailedEndMark
enum  WriteStates : unsigned int { kNotWriting = 0, kWriteInProgress = 1, kWriteSucceeded = 2, kWriteFailed = 3 }

Public Member Functions

 CRhinoFileWriteOptions ()
 CRhinoFileWriteOptions (const CRhinoFileWriteOptions &)
 ~CRhinoFileWriteOptions ()
bool ClipboardIsDestination () const
bool CreateBackupFile () const
unsigned int DocumentSerialNumber () const
bool FileNameIsEmpty () const
bool FileNameIsNotEmpty () const
ON_UUID FileTypeId () const
unsigned int FileTypeIndex () const
bool FileTypeIs3dm () const
bool FileTypeIsComplete3dm () const
bool GeometryObjectFilter () const
bool GetFileName (ON_String &sUTF8FileName) const
bool GetFileName (ON_wString &sFileName) const
bool GetTemporaryFileName (ON_String &sUTF8FileName) const
bool GetTemporaryFileName (ON_wString &sFileName) const
bool IncludeBitmaps () const
bool IncludeNotes () const
bool IncludeObjectHistory () const
bool IncludePlugInInformation () const
bool IncludePreviewImage () const
bool IncludeReferenceModelInformation () const
bool IncludeRenderMeshes () const
bool IncludeTextures () const
bool IsAutosave () const
CRhinoFileWriteOptionsoperator= (const CRhinoFileWriteOptions &)
unsigned int Rhino3dmVersion () const
bool SelectedObjectFilter () const
bool SetCreateBackupFile (bool bCreateBackupFile)
bool SetDocumentSerialNumber (unsigned int)
bool SetFileName (const char *sUTF8FileName)
bool SetFileName (const wchar_t *sFileName)
bool SetFileTypeIdAndIndex (ON_UUID file_type_id, unsigned int file_type_index)
bool SetGeometryObjectFilter (bool bGeometryObjectFilter)
bool SetIncludeBitmaps (bool bIncludeBitmaps)
bool SetIncludeNotes (bool bIncludeNotes)
bool SetIncludeObjectHistory (bool bIncludeObjectHistory)
bool SetIncludePlugInInformation (bool bIncludePlugInInformation)
bool SetIncludePreviewImage (bool bIncludePreviewImage)
bool SetIncludeReferenceModelInformation (bool bIncludeReferenceModelInformation)
bool SetIncludeRenderMeshes (bool bIncludeRenderMeshes)
bool SetIncludeTextures (bool bIncludeTextures)
bool SetIsAutosave (bool bIsAutosave)
bool SetRhino3dmVersion (unsigned int rhino_3dm_version)
bool SetSelectedObjectFilter (bool bSelectedObjectFilter)
bool SetTemporaryFileName (const char *sUTF8FileName)
bool SetTemporaryFileName (const wchar_t *sFileName)
bool SetTransformation (ON_Xform xform)
bool SetUpdateDocumentPath (bool bUpdateDocumentPath)
bool SetUseBatchMode (bool bUseBatchMode)
bool SetUseTemporaryFileAndRename (bool bUseTemporaryFileAndRename)
bool TemplateFileIsDestination () const
bool TemporaryFileNameIsEmpty () const
bool TemporaryFileNameIsNotEmpty () const
ON_Xform Transformation () const
bool TransformationIsIdentity () const
bool UpdateDocumentPath () const
bool UseBatchMode () const
bool UseTemporaryFileAndRename () const
unsigned int WriteFailedReason () const
const wchar_t * WriteFailedReasonDescription () const
CRhinoFileWriteOptions::WriteStates WriteState () const

Static Public Member Functions

static bool GetFileTypeIdAndIndexFromFileExtension (const wchar_t *sFileExtension, ON_UUID &file_type_id, unsigned int &file_type_index)
static bool GetFileTypeIdAndIndexFromFileName (const wchar_t *sFileName, ON_UUID &file_type_id, unsigned int &file_type_index)
static const wchar_t * WriteFailedReasonDescription (unsigned int write_failed_reason)

Static Public Attributes

static const CRhinoFileWriteOptions ClipboardFileDefaults
static const CRhinoFileWriteOptions Defaults
static const CRhinoFileWriteOptions TemplateFileDefaults


class CRhinoDoc
CRhinoFileWriteOptions CRhinoFileWriteOptions_DefaultsCtor (unsigned int)
const class CRhFileWriteOptionsData * RhFileWriteOptionsConstData (const class CRhinoFileWriteOptions *)
class CRhFileWriteOptionsData * RhFileWriteOptionsData (class CRhinoFileWriteOptions *)
void RhSetWriteFailed (class CRhinoFileWriteOptions *, CRhinoFileWriteOptions::WriteFailedReasons)

Detailed Description

Copyright (c) 1993-2017 Robert McNeel & Associates. All rights reserved. Rhinoceros is a registered trademark of Robert McNeel & Associates.


For complete Rhino SDK copyright information see http://www.rhino3d.com/developer.

Member Enumeration Documentation

◆ WriteFailedReasons


Another Rhino session is using this file and it is locked.


FileTypeId() does not identify any plug-in that can be loaded.


FileTypeId() does not identify a file writing plug-in.


there is a bug in the code and a validation check found it


writing to a section or table failed


◆ WriteStates


Constructor & Destructor Documentation

◆ CRhinoFileWriteOptions() [1/2]

CRhinoFileWriteOptions::CRhinoFileWriteOptions ( )

◆ ~CRhinoFileWriteOptions()

CRhinoFileWriteOptions::~CRhinoFileWriteOptions ( )

◆ CRhinoFileWriteOptions() [2/2]

CRhinoFileWriteOptions::CRhinoFileWriteOptions ( const CRhinoFileWriteOptions )

Member Function Documentation

◆ ClipboardIsDestination()

bool CRhinoFileWriteOptions::ClipboardIsDestination ( ) const

Returns: True if a the selected object are being copied to the clipboard.

◆ CreateBackupFile()

bool CRhinoFileWriteOptions::CreateBackupFile ( ) const

Returns: True: If a file with the same name exists, it will be renamed by appending "bak" to its name. False If a file with the same name exists, it will be deleted and replaced.

◆ DocumentSerialNumber()

unsigned int CRhinoFileWriteOptions::DocumentSerialNumber ( ) const

Returns: The runtime serial number of the document being written. Remarks: The default is 0. Use CRhinoDoc::FromRuntimeSerialNumber() to get a pointer to the document.

◆ FileNameIsEmpty()

bool CRhinoFileWriteOptions::FileNameIsEmpty ( ) const

◆ FileNameIsNotEmpty()

bool CRhinoFileWriteOptions::FileNameIsNotEmpty ( ) const

◆ FileTypeId()

ON_UUID CRhinoFileWriteOptions::FileTypeId ( ) const

Returns: nil: File will be a Rhino .3dm file. not-nil: ID of the file export plug-in that will write the file

◆ FileTypeIndex()

unsigned int CRhinoFileWriteOptions::FileTypeIndex ( ) const

Returns: FileTypeIndex that identifies the extension the file writing plugin will create.

◆ FileTypeIs3dm()

bool CRhinoFileWriteOptions::FileTypeIs3dm ( ) const

Returns: True if the file time is some version of a Rhino 3dm file.

◆ FileTypeIsComplete3dm()

bool CRhinoFileWriteOptions::FileTypeIsComplete3dm ( ) const

Returns: True if the the file type is the current 3dm file version and everything in the document will be saved.

◆ GeometryObjectFilter()

bool CRhinoFileWriteOptions::GeometryObjectFilter ( ) const

Returns: True: The geometry only filter will be applied. Only geometric objects (curves, surface, breps, meshes, ...) will be saved. Annotation, layers, materials, ... will not be saved. False: The geometry only filter will not be applied. Remarks: The default is false.

◆ GetFileName() [1/2]

bool CRhinoFileWriteOptions::GetFileName ( ON_String sUTF8FileName) const

◆ GetFileName() [2/2]

bool CRhinoFileWriteOptions::GetFileName ( ON_wString sFileName) const

◆ GetFileTypeIdAndIndexFromFileExtension()

static bool CRhinoFileWriteOptions::GetFileTypeIdAndIndexFromFileExtension ( const wchar_t *  sFileExtension,
ON_UUID file_type_id,
unsigned int &  file_type_index 

◆ GetFileTypeIdAndIndexFromFileName()

static bool CRhinoFileWriteOptions::GetFileTypeIdAndIndexFromFileName ( const wchar_t *  sFileName,
ON_UUID file_type_id,
unsigned int &  file_type_index 

◆ GetTemporaryFileName() [1/2]

bool CRhinoFileWriteOptions::GetTemporaryFileName ( ON_String sUTF8FileName) const

◆ GetTemporaryFileName() [2/2]

bool CRhinoFileWriteOptions::GetTemporaryFileName ( ON_wString sFileName) const

◆ IncludeBitmaps()

bool CRhinoFileWriteOptions::IncludeBitmaps ( ) const

Returns: True if bitmap images used for textures and other purposes should be saved in the file. Remarks: The default is true.

◆ IncludeNotes()

bool CRhinoFileWriteOptions::IncludeNotes ( ) const

Returns: True if notes will be saved in the file. Remarks: The default is true.

◆ IncludeObjectHistory()

bool CRhinoFileWriteOptions::IncludeObjectHistory ( ) const

Returns: True if object history information should be saved in the file. Remarks: The default is true.

◆ IncludePlugInInformation()

bool CRhinoFileWriteOptions::IncludePlugInInformation ( ) const

Returns: True if plug-in information will be saved in the file. Remarks: The default is true.

◆ IncludePreviewImage()

bool CRhinoFileWriteOptions::IncludePreviewImage ( ) const

Returns: True if a preview image of the model will be saved in the file. Remarks: The default is true.

◆ IncludeReferenceModelInformation()

bool CRhinoFileWriteOptions::IncludeReferenceModelInformation ( ) const

Returns: True if information from reference models will be saved in the file. Remarks: The default is false.

◆ IncludeRenderMeshes()

bool CRhinoFileWriteOptions::IncludeRenderMeshes ( ) const

Returns: True if cached render meshes will be saved in the file. Remarks: The default is true.

◆ IncludeTextures()

bool CRhinoFileWriteOptions::IncludeTextures ( ) const

Returns: True if testure information should be saved in the file. Remarks: The default is false.

◆ IsAutosave()

bool CRhinoFileWriteOptions::IsAutosave ( ) const

Returns: True if the save operation is an autosave. Remarks: The default is false.

◆ operator=()

CRhinoFileWriteOptions& CRhinoFileWriteOptions::operator= ( const CRhinoFileWriteOptions )

◆ Rhino3dmVersion()

unsigned int CRhinoFileWriteOptions::Rhino3dmVersion ( ) const

Returns: 0: The file type is non-3dm file identified by FileTypeId() and FileTypeIndex(). >= 2: The file type is a 3dm file and the number specifies the earliest version of Rhino that will be able to read the 3dm file. Remarks: The default is RhinoVersion::App3dmVersionNumber().

◆ SelectedObjectFilter()

bool CRhinoFileWriteOptions::SelectedObjectFilter ( ) const

Returns RhinoVersion::App3dmVersionNumber(); static int Default3dmFileVersion(); Returns: True: The selected object filter will be applied. Only selected objects and the additional information in the model they rely on, like layers, materials and instance definitions, will be saved. False: The selected object filter will not be applied. Remarks: The default is false.

◆ SetCreateBackupFile()

bool CRhinoFileWriteOptions::SetCreateBackupFile ( bool  bCreateBackupFile)

◆ SetDocumentSerialNumber()

bool CRhinoFileWriteOptions::SetDocumentSerialNumber ( unsigned int  )

◆ SetFileName() [1/2]

bool CRhinoFileWriteOptions::SetFileName ( const char *  sUTF8FileName)

Parameters: sUTF8FileName - [in] Returns: True if the value was set.

◆ SetFileName() [2/2]

bool CRhinoFileWriteOptions::SetFileName ( const wchar_t *  sFileName)

Parameters: sFileName - [in] Returns: True if the value was set.

◆ SetFileTypeIdAndIndex()

bool CRhinoFileWriteOptions::SetFileTypeIdAndIndex ( ON_UUID  file_type_id,
unsigned int  file_type_index 

Parameters: file_type_id - [in] nil, a Rhino application id, or the id of a file writing plug-in. file_type_index - [in] If file_type_id identifies a file writing plug-in, then file_type_index selects the type of file the plug-in will write. If file_type_id is nil or a Rhino application id, this parameter is ignored and the file type is set to the current 3dm version. Returns: True if the value was set to application_id. Remarks: CRhinoFileWriteOptions::GetFileTypeIdAndIndexFromFileName() and CRhinoFileWriteOptions::GetFileTypeIdAndIndexFromFileExtension() may be used to get the file_type_id and file_type_index from a file name or file extension.

◆ SetGeometryObjectFilter()

bool CRhinoFileWriteOptions::SetGeometryObjectFilter ( bool  bGeometryObjectFilter)

Returns: True if the value was set.

◆ SetIncludeBitmaps()

bool CRhinoFileWriteOptions::SetIncludeBitmaps ( bool  bIncludeBitmaps)

Returns: True if the value was set.

◆ SetIncludeNotes()

bool CRhinoFileWriteOptions::SetIncludeNotes ( bool  bIncludeNotes)

Returns: True if the value was set.

◆ SetIncludeObjectHistory()

bool CRhinoFileWriteOptions::SetIncludeObjectHistory ( bool  bIncludeObjectHistory)

◆ SetIncludePlugInInformation()

bool CRhinoFileWriteOptions::SetIncludePlugInInformation ( bool  bIncludePlugInInformation)

Returns: True if the value was set.

◆ SetIncludePreviewImage()

bool CRhinoFileWriteOptions::SetIncludePreviewImage ( bool  bIncludePreviewImage)

Returns: True if the value was set.

◆ SetIncludeReferenceModelInformation()

bool CRhinoFileWriteOptions::SetIncludeReferenceModelInformation ( bool  bIncludeReferenceModelInformation)

Returns: True if the value was set.

◆ SetIncludeRenderMeshes()

bool CRhinoFileWriteOptions::SetIncludeRenderMeshes ( bool  bIncludeRenderMeshes)

Returns: True if the value was set.

◆ SetIncludeTextures()

bool CRhinoFileWriteOptions::SetIncludeTextures ( bool  bIncludeTextures)

Returns: True if the value was set.

◆ SetIsAutosave()

bool CRhinoFileWriteOptions::SetIsAutosave ( bool  bIsAutosave)

Returns: True if the value was set.

◆ SetRhino3dmVersion()

bool CRhinoFileWriteOptions::SetRhino3dmVersion ( unsigned int  rhino_3dm_version)

Description: Specify what version of .3dm file should be written. Parameters: rhino_3dm_version - [in] 2 <= rhino_3dm_version <= RhinoVersion::App3dmVersionNumber() This number specifies the earliest version of Rhino that will be able to read the file. Returns: True if the value was set to rhino_3dm_version. False if setting is prohibited or the input is not valid, in which case you can call Rhino3dmVersion() to determine what happened.

◆ SetSelectedObjectFilter()

bool CRhinoFileWriteOptions::SetSelectedObjectFilter ( bool  bSelectedObjectFilter)

Returns: True if the value was set.

◆ SetTemporaryFileName() [1/2]

bool CRhinoFileWriteOptions::SetTemporaryFileName ( const char *  sUTF8FileName)

◆ SetTemporaryFileName() [2/2]

bool CRhinoFileWriteOptions::SetTemporaryFileName ( const wchar_t *  sFileName)

◆ SetTransformation()

bool CRhinoFileWriteOptions::SetTransformation ( ON_Xform  xform)

Parameters: xform - [in] Transformation to apply to saved geometry. Returns: True if the value was set.

◆ SetUpdateDocumentPath()

bool CRhinoFileWriteOptions::SetUpdateDocumentPath ( bool  bUpdateDocumentPath)

◆ SetUseBatchMode()

bool CRhinoFileWriteOptions::SetUseBatchMode ( bool  bUseBatchMode)

Returns: True if the value was set.

◆ SetUseTemporaryFileAndRename()

bool CRhinoFileWriteOptions::SetUseTemporaryFileAndRename ( bool  bUseTemporaryFileAndRename)

◆ TemplateFileIsDestination()

bool CRhinoFileWriteOptions::TemplateFileIsDestination ( ) const

Returns: True if a template file is being saved.

◆ TemporaryFileNameIsEmpty()

bool CRhinoFileWriteOptions::TemporaryFileNameIsEmpty ( ) const

◆ TemporaryFileNameIsNotEmpty()

bool CRhinoFileWriteOptions::TemporaryFileNameIsNotEmpty ( ) const

◆ Transformation()

ON_Xform CRhinoFileWriteOptions::Transformation ( ) const

Returns: Transformation that will be applied to the saved geometry.

◆ TransformationIsIdentity()

bool CRhinoFileWriteOptions::TransformationIsIdentity ( ) const

Returns: True if no transformation will be applied to the saved geometry.

◆ UpdateDocumentPath()

bool CRhinoFileWriteOptions::UpdateDocumentPath ( ) const

Returns: True: (default) If a complete, current version, 3dm file is successfully saved, then then name of the file will be used to update the document's default file path and title and document will be marked as not modified. False: The document's default file path, title and modified state will not be changed under any circumstances. Remarks: This setting is ignored when selected information is exported, earlier 3dm versions or non-3dm formats are written.

◆ UseBatchMode()

bool CRhinoFileWriteOptions::UseBatchMode ( ) const

Returns: True if the writing operation cannot pause for user input. Remarks: The default is false.

◆ UseTemporaryFileAndRename()

bool CRhinoFileWriteOptions::UseTemporaryFileAndRename ( ) const

Returns: True: When writing occurs, a temporary file will be written to. If the writing succeeds, the temporary file will be renamed to the specified file name.
Remarks: It is not necessary to specify the name of the temporary file. If you want to specify the name of the temporary file, you may use SetTemporaryFileName().

◆ WriteFailedReason()

unsigned int CRhinoFileWriteOptions::WriteFailedReason ( ) const

◆ WriteFailedReasonDescription() [1/2]

const wchar_t* CRhinoFileWriteOptions::WriteFailedReasonDescription ( ) const

Returns: If WriteState() and WriteFailedReason() identify a reason for failure, the a description is returned. Otherwise null is returned.

◆ WriteFailedReasonDescription() [2/2]

static const wchar_t* CRhinoFileWriteOptions::WriteFailedReasonDescription ( unsigned int  write_failed_reason)

◆ WriteState()

CRhinoFileWriteOptions::WriteStates CRhinoFileWriteOptions::WriteState ( ) const

Friends And Related Function Documentation

◆ CRhinoDoc

friend class CRhinoDoc

◆ CRhinoFileWriteOptions_DefaultsCtor

CRhinoFileWriteOptions CRhinoFileWriteOptions_DefaultsCtor ( unsigned int  )

Additional settings that control the type and content of the file. These settings are managed as a non-SDK class so they can be modified without breaking the SDK.

◆ RhFileWriteOptionsConstData

const class CRhFileWriteOptionsData* RhFileWriteOptionsConstData ( const class CRhinoFileWriteOptions )

◆ RhFileWriteOptionsData

class CRhFileWriteOptionsData* RhFileWriteOptionsData ( class CRhinoFileWriteOptions )

◆ RhSetWriteFailed

void RhSetWriteFailed ( class CRhinoFileWriteOptions ,

Member Data Documentation

◆ ClipboardFileDefaults

const CRhinoFileWriteOptions CRhinoFileWriteOptions::ClipboardFileDefaults

Description: If a model is being saved to the clipboard, then the CRhinoFileWriteOptions parameter must be constructed as a copy of ClipboardFileDefaults.

◆ Defaults

const CRhinoFileWriteOptions CRhinoFileWriteOptions::Defaults

◆ TemplateFileDefaults

const CRhinoFileWriteOptions CRhinoFileWriteOptions::TemplateFileDefaults

Description: If a model is being saved as a template, then the CRhinoFileWriteOptions parameter must be constructed as a copy of TemplateFileDefaults.