GH_Archive

This is the base archive class which takes care of all (de)serialization and messaging.

Properties

FileName

public string FileName { get; }

Gets the filename (without extension) of the currently loaded data tree. If the path field has not been set, "unnamed" is returned.

GetRootNode

public GH_Chunk GetRootNode { get; }

Gets the root node of this archive. Typically you do not need to modify the Root. Use functions like CreateTopLevelNode(), AppendObject() and ExtractObject() instead. If you modify the Root node, you may corrupt the archive.

GH_IO_Version

public static GH_Version GH_IO_Version { get; }

Gets the version number of the current GH_IO build.

GrasshopperBinaryExtension

public static string GrasshopperBinaryExtension { get; }

Gets the file extension (including the dot) associated with Grasshopper® Binary data.

GrasshopperUserExtension

public static string GrasshopperUserExtension { get; }

Gets the file extension (including the dot) associated with Grasshopper® User Object file.

GrasshopperXmlExtension

public static string GrasshopperXmlExtension { get; }

Gets the file extension (including the dot) associated with Grasshopper® XML data.

IsBinaryPath

public bool IsBinaryPath { get; }

Gets a value that indicates whether the Path field points to a Binary Grasshopper file.

IsPath

public bool IsPath { get; }

Gets a value that indicates whether or not the path field has been set.

IsXmlPath

public bool IsXmlPath { get; }

Gets a value that indicates whether the Path field points to an Xml Grasshopper file.

Messages

public List<GH_Message> Messages { get; }

Gets the internal list of messages.

Path

public string Path { get; set; }

Gets the path to the file from which this archive was read and/or written to. If the archive hasn't been read or written yet, this field will be null.

WorstCaseMessageType

public GH_Message_Type WorstCaseMessageType { get; }

Gets the worst case message type. If the record contains at least 1 error, the worst case is GH_Message_Type.error. If the record contains no errors, but at least 1 warning, the worst case is GH_Message_Type.warning. If the record contains no messages or only infos, the worst case type is GH_Message_Type.info.

Methods

AddMessage

public void AddMessage(GH_Message message)

Add a new message to the record.

Parameters:

message (GH_Message)

Message to add

Exceptions:

ArgumentNullException

Thrown if the message is a null reference.

AddMessage

public void AddMessage(string messageText, GH_Message_Type messageType)

Add a new message to the record.

Parameters:

messageText (string)	Message text.
messageType (GH_Message_Type)	Message type.

Exceptions:

ArgumentNullException

Thrown if message text is null or empty.

AppendObject

public bool AppendObject(GH_ISerializable target, string targetName)

Appends a target object into the root node of this archive tree. If the root doesn't exist yet, it will be created. Existing objects at the root scope will not be affected.

Parameters:

target (GH_ISerializable)	Object to append. Cannot be null.
targetName (string)	Name of object to append, name must be unique.

Returns: True on succes, false on failure.

Exceptions:

ArgumentNullException	Thrown if target is a null reference.
ArgumentNullException	Thrown if the target_name is null or empty.

Example:This sample shows how to create a new archive and serialize a single top level object.

bool CreateFile(string file_name, GH_ISerializable target, string target_name) 
{
  GH_Archive archive = new GH_Archive();
  archive.AppendObject(target, target_name);
  return archive.WriteToFile(file_name, true);
}

ClearMessages

public void ClearMessages()

Remove all messages from the log.

CreateNewRoot

public void CreateNewRoot(bool forWriting)

Discards the current data tree and instantiates a new root node. This root node contains some comments, a version value containing the current version of GH_IO.dll and a DateTime value containing the current date and time.

Parameters:

forWriting (bool)

If true, all data fields are reset.

CreateTopLevelNode

public GH_IWriter CreateTopLevelNode(string rootName)

Creates and returns a new root node for this archive in the form of a GH_IWriter instance. Typically you do not call this method. If you want to add an object to the archive, use AppendObject() instead.

Parameters:

rootName (string)

Name of root object.

Returns: The GH_IWriter incarnation of the GH_Chunk that represents the new Node.

Deserialize_Binary

public bool Deserialize_Binary(byte[] data)

Deserializes an array of bytes.

Parameters:

data (byte[])

Byte array to deserialize.

Returns: True on success, false on failure.

Exceptions:

ArgumentNullException

Thrown if data is a null reference.

Deserialize_Xml

public bool Deserialize_Xml(string xmlContent)

Deserializes an Xml string.

Parameters:

xmlContent (string)

Xml to deserialize.

Returns: True on success, false on failure.

Exceptions:

XmlException

Thrown if xml_content is not a valid Grasshopper Xml stream.

ExtractObject

public bool ExtractObject(GH_ISerializable target, string targetName)

Extract a target object from the data tree.

Parameters:

target (GH_ISerializable)	Object to extract. Cannot be null.
targetName (string)	Name of object to extract, name must identify an existing chunk.

Returns: True on succes, false on failure.

Exceptions:

MemberAccessException	Thrown if the Root node hasn't been instantiated yet.
ArgumentNullException	Thrown if target is a null reference.
ArgumentNullException	Thrown if the target_name is null or empty.
MemberAccessException	Thrown if the target_name cannot be resolved.

MessageCount

public int MessageCount()

Gets the number of messages recorded since the most recent IO operation began.

Returns: The number of recorded messages.

MessageCount

public int MessageCount(bool includeInfo, bool includeWarnings, bool includeErrors)

Gets the number of messages recorded since the most recent IO operation began. Message count can be filtered by message type.

Parameters:

includeInfo (bool)	If true, info messages will be included in the count.
includeWarnings (bool)	If true, warnings will be included in the count.
includeErrors (bool)	If true, errors will be included in the count.

Returns: The number of recoded messages that pass the type filters.

OpenFileDialog

public static bool OpenFileDialog(string title, ref string filePath, List<string> additionalFilters)

Displays a standard OpenFileDialog with all the fields set to cater for Grasshopper files.

Parameters:

title (string)	Title of the dialog. If null, the default title will be used.
filePath (ref string)	Path to file picked by user. If file_path represents a valid string, the dialog is set up to match.
additionalFilters (List<string>)	A list of additional file format filters or null. Filter strings must be in typical FileDialog.Filter syntax: `"File Name (.ext)\|.ext"`

Returns: True is user picked a path, False if user cancelled.

ReadFromFile

public bool ReadFromFile(string fileName)

Reads a new archive tree from a file.

Parameters:

fileName (string)

Path of file to parse.

Returns: True on success, false on failure. If the read operation fails, all the member fields of this archive ought to be treated as invalid.

Exceptions:

FileNotFoundException	Thrown if the file doesn't exist.
IOException	Thrown if the file_name doesn't represent a known file extension.

SaveFileDialog

public static bool SaveFileDialog(string title, ref string filePath, List<string> additionalFilters)

Displays a standard SaveFileDialog with all the fields set to cater for Grasshopper files.

Parameters:

title (string)	Title of the dialog. If null, the default title will be used.
filePath (ref string)	Path to file picked by user. If file_path represents a valid string, the dialog is set up to match.
additionalFilters (List<string>)	A list of additional file format filters or null. Filter strings must be in typical FileDialog.Filter syntax: `"File Name (.ext)\|.ext"`

Returns: True is user picked a new path, False if user cancelled.

Serialize_Binary

public byte[] Serialize_Binary()

Serializes the data tree into a Binary byte array.

Returns: A byte array containing the Binary stream.

Exceptions:

MemberAccessException

Thrown if the root of the current archive hasn't been instantiated yet.

Serialize_Xml

public string Serialize_Xml()

Serializes the data tree into an Xml string.

Returns: A string containing the Xml content.

Exceptions:

MemberAccessException

Thrown if the root of the current archive hasn't been instantiated yet.

ShowMessageLog

public DialogResult ShowMessageLog()

Displays the message log viewer. You should typically only display the viewer if the WorstCaseMessageType equals GH_Message_Type.warning or GH_Message_Type.error

Returns: The closing flag for the displayed log form.

WriteToFile

public bool WriteToFile(string fileName, bool overwrite, bool rememberPath)

Writes the current tree to a file.

Parameters:

fileName (string)	Path of file to write to. If the extension is not a recognized Grasshopper extension, an exception will be thrown.
overwrite (bool)	True to overwrite file at specified location.
rememberPath (bool)	If True, the MRU path field will be updated to reflect the new path.

Returns: True on succes, false if file already exists and overwrite is set to false.

Exceptions:

MemberAccessException	Thrown if the root of the current archive hasn't been instantiated yet.
ArgumentNullException	Thrown if file_name is either null or empty.
IOException	Thrown if the file_name doesn't represent a known file extension.