DocumentIO

References
public sealed class DocumentIO
Utility methods for saving and opening documents.

Constructors

DocumentIO

#
public DocumentIO(Document document = null, bool trackFiles = true, bool reportErrors = true, bool retainRoot = false, bool resolvePlugins = true)
Create a new empty IO class. Use this constructor if you wish to Open/Load a file.
Parameters:
document (Document = null)Document to operate on.
trackFiles (bool = true)True to add recent-file records.
reportErrors (bool = true)True to show exceptions in an error window.
retainRoot (bool = false)True to keep the archive root after opening.
resolvePlugins (bool = true)True to offer the user a way to fetch plugins the file needs but does not have. Turn this off for loads which happen behind the user's back — snippet previews, dependency reads — where a modal window would arrive unbidden.

Fields

ClipboardDocumentType

#
public const string ClipboardDocumentType = "GH2DOC"

G1BinaryExtension

#
public const string G1BinaryExtension = ".gh"
Gets the extension (including the period) for Grasshopper 1.0 binary files.

G1DataExtension

#
public const string G1DataExtension = ".ghdata"
Gets the extension (including the period) for Grasshopper 1.0 data files.

G1XmlExtension

#
public const string G1XmlExtension = ".ghx"
Gets the extension (including the period) for Grasshopper 1.0 Xml files.

G2AutoSaveExtension

#
public const string G2AutoSaveExtension = ".ghautosave"
Gets the extension (including the period) for Grasshopper 2.0+ autosave files.

G2BackupExtension

#
public const string G2BackupExtension = ".ghbackup"
Gets the extension (including the period) for Grasshopper 2.0+ backup files.

G2SmlExtension

#
public const string G2SmlExtension = ".sml"
Gets the extension (including the period) for Sml files.

G2ZipExtension

#
public const string G2ZipExtension = ".ghz"
Gets the extension (including the period) for Grasshopper 2.0+ files.

Properties

Compression

#
public Compression Compression { get; set; }
Gets or sets the compression level used when writing GHZ files.

Document

#
public Document Document { get; }
Gets the document currently associated with this IO utility.

DocumentRoot

#
public Node DocumentRoot { get; }
When a document is saved or loaded, and RetainRoot is true, the archive root node is stored here.

ReportErrors

#
public bool ReportErrors { get; }
Gets or sets whether exceptions are displayed in an Error feedback window.

ResolvePlugins

#
public bool ResolvePlugins { get; }
Gets whether opening a file offers the user a way to fetch plugins it needs but does not have.

Deliberately separate from ReportErrors. That one governs whether a failure is shown in an error window; this one governs whether the user is asked a question. Session restore wants the second without the first — it reopens the user's own files and should certainly offer to fetch what they need, while a per-file error box at startup would be a menace.

RetainRoot

#
public bool RetainRoot { get; }
Retain the root of the archive used to open a document.

RootFolder

#
public string RootFolder { get; set; }
Gets or sets the root folder for Save/Open dialogs to revert to in case the file itself doesn't have a directory yet.

TrackFiles

#
public bool TrackFiles { get; }
Gets or sets whether save and open operations on this instance add recent file records.

Window

#
public Window Window { get; set; }
Gets or sets the window which functions as the parent of any Save or Open dialogs. If left unset, the Grasshopper2.UI.Editor.Instance will be used.

Methods

Copy

#
public bool Copy(ClipboardKind kind)
Copy the selected objects of the loaded document into the specified clipboard.
Parameters:
kind (ClipboardKind)

Examine

#
public void Examine()
Ask the user to pick a file and then examine that file in a custom browser.

Examine

#
public void Examine(string path, bool useConsole)
Examine a specific file using a custom browser.
Parameters:
path (string)
useConsole (bool)

Export

#
public bool Export(FileContents contents = FileContents.All)
Export the loaded document to an SML file.
Parameters:
contents (FileContents = FileContents.All)

Export

#
public bool Export(string path, FileContents contents = FileContents.All)
Execute the regular 'Save A Copy' operation on the document hosted in this DocumentIO instance. This is the fundamental save method, all other save methods ultimately call this method, while doing some additional work. This save method will not update the FileUtility.Path of the document getting saved, although it will track the save if the TrackFiles property is true.
Parameters:
path (string)
contents (FileContents = FileContents.All)

FindScribbleTexts

#
public static string[] FindScribbleTexts(string file)
Try and harvest all scribble texts from a document file. This method will read the file, but it will not construct a new Document instance.
Parameters:
file (string)
Returns: All scribble texts in this document.

Open

#
public bool Open(IEnumerable<Document> blockingList = null, Action<Document> blockingCallback = null)
Display the open file dialog and load the selected document.
Parameters:
blockingList (IEnumerable<Document> = null)List of already loaded documents used to block a specific file from being opened.
blockingCallback (Action<Document> = null)Optional callback in case an already loaded document is picked.
Returns: True if file was opened, false if opening failed or the loadedList prevented opening.

Open

#
public bool Open(string path, IEnumerable<Document> blockingList = null, Action<Document> blockingCallback = null)
Open the specified file, unless it collides with one of the files in the blocking list.
Parameters:
path (string)
blockingList (IEnumerable<Document> = null)List of already loaded documents used to block a specific file from being opened.
blockingCallback (Action<Document> = null)Optional callback in case an already loaded document is picked.
Returns: True if file was opened, false if opening failed or the blockingList prevented opening.

Paste

#
public bool Paste(ClipboardKind kind)
Paste the data in the specified clipboard into the document inside this instance.
Parameters:
kind (ClipboardKind)

Save

#
public bool Save(FileContents contents = FileContents.All)
Execute the regular 'Save' operation on the loaded document. This will either override the current file if the document is already associated with a URI, or it will open the SAVE FILE dialog.
Parameters:
contents (FileContents = FileContents.All)
Returns: True if the file was saved one way or another.

Save

#
public bool Save(string path, FileContents contents = FileContents.All)
Execute the regular 'Save' operation on the loaded document. This will update the document's file association.
Parameters:
path (string)
contents (FileContents = FileContents.All)

SaveAs

#
public bool SaveAs(FileContents contents = FileContents.All)
Execute the regular 'Save As' operation on the loaded document. This will always show the SAVE FILE dialog, possibly anchored to the current document URI.
Parameters:
contents (FileContents = FileContents.All)
Returns: True if the file was saved one way or another.

SaveCopy

#
public bool SaveCopy(FileContents contents = FileContents.All)
Execute the regular 'Save A Copy' operation on the loaded document. This will always show the SAVE FILE dialog, possibly anchored to the current document URI, but it will not override the document URI path.
Parameters:
contents (FileContents = FileContents.All)

SaveCopy

#
public bool SaveCopy(string path, FileContents contents = FileContents.All, BackupMethod method = BackupMethod.Default, string stampFormat = null)
Execute the regular 'Save A Copy' operation on the document hosted in this DocumentIO instance. This is the fundamental save method, all other save methods ultimately call this method, while doing some additional work. This save method will not update the FileUtility.Path of the document getting saved, although it will track the save if the TrackFiles property is true.
Parameters:
path (string)
contents (FileContents = FileContents.All)
method (BackupMethod = BackupMethod.Default)
stampFormat (string = null)

SaveSnippet

#
public bool SaveSnippet()
Save the document to the central Snippets folder.
Returns: True if snippet was saved.

ShowExportDialog

#
public string ShowExportDialog(string title, string pathHint)
Show the Export to Sml dialog and return the selected path.
Parameters:
title (string)Dialog title.
pathHint (string)Optional initial path.

ShowOpenDialog

#
public static string ShowOpenDialog(Window window, string title, string pathHint)
Parameters:
window (Window)
title (string)
pathHint (string)

ShowSaveDialog

#
public string ShowSaveDialog(string title, string pathHint)
Show the Save dialog and return the selected path.
Parameters:
title (string)Dialog title.
pathHint (string)Optional initial path.

TryHarvestCanvasThumbnail

#
public static Bitmap TryHarvestCanvasThumbnail(string file)
Try and get the canvas thumbnail image stored inside a GHZ file.
Parameters:
file (string)File location.
Returns: Canvas thumbnail if available.

TryHarvestViewportThumbnail

#
public static Bitmap TryHarvestViewportThumbnail(string file)
Try and get the viewport thumbnail image stored inside a GHZ file.
Parameters:
file (string)File location.
Returns: Viewport thumbnail if available.