## CreateObjectFromPreset

### Introduced

v1.0

### Description

Creates and returns a new object based on a preset. The object is created in the TransientObjectContainer meaning that it is not persisted in the scene or visible in the scene explorer. This area is flushed each time a new scene is loaded. This command can be useful for creating temporary CustomProperty objects as shown in the example below.

### Scripting Syntax

    oReturn = CreateObjectFromPreset( PresetObj, [Name] );

### Return Value

Returns the newly created object.

### Parameters

Parameter | Type | Description
--- | --- | ---
PresetObj | String | Preset object or full path of the preset file. See Model Presets, Pass Presets, Primitive Presets, Property Presets, and Shader Presets
Name | String | Name to give the created object

### Examples

#### JScript Example

    /*

    	Example of creating a temporary custom property (aka custom pset).

    	This can be useful for showing a temporary yet non-modal custom pset

    	to the user.  The user doesn//t have to close the PPG immediately

    	yet the object does not clutter up the scene file.

    */

    NewScene( "", false );

    // Demonstrate how you can use it to create a built-in custom pset

    var oAnnotation = CreateTemporaryCustomPSet( "Annotation", Application.InstallationPath(siFactoryPath), "MyA" );

    if ( oAnnotation ) {

    	InspectObj( oAnnotation, "", "Annotation Test", siModal, false );

    }

    // Create an instance of one of the SDK workgroup sample psets

    var presetpath = XSIUtils.BuildPath(

    	Application.InstallationPath( siFactoryPath ),

    	"XSISDK", "examples", "workgroup", "Addons", "PSetUIDemo"

    );

    var oPSetUIDemo = CreateTemporaryCustomPSet( "PSetUIDemo", presetpath, "" );

    if ( oPSetUIDemo ) {

    	InspectObj( oPSetUIDemo, "", "PSetUIDemo Test", siModal, false );

    }

    // Now the following lines will log, declaring that these instances live inside the TransientObjectContainer:

    // INFO : Full path of Annotation instance is: TransientObjectContainer.MyA

    // INFO : Full path of PSetUIDemo instance is: TransientObjectContainer.PSetUIDemo

    // ... but nothing exists under the Scene_Root...

    var oProp = Application.ActiveSceneRoot.Properties("PSetUIDemo");

    if (oProp == null || typeof(oProp) == "undefined") {

    	Application.LogMessage( "No instances found." );

    } else {

    	Application.LogMessage( "Found an instance." );

    }

    // INFO : No instances found.

    // ... until you apply it

    Application.ActiveSceneRoot.AddProperty( XSIUtils.BuildPath(presetpath, "Data", "DSPresets", "Properties", "PSetUIDemo.Preset") );

    oProp = Application.ActiveSceneRoot.Properties("PSetUIDemo");

    if (oProp == null || typeof(oProp) == "undefined") {

    	Application.LogMessage( "No instances found." );

    } else {

    	Application.LogMessage( "Found an instance." );

    }

    // INFO : Found an instance.

    // Function CreateTemporaryCustomPSet

    // Creates a temporary custom property set.  This does not appear in the scene explorer and you do not have to

    // worry about deleting it.

    //

    // in_PresetName - Name of the preset, which normally matches the name of the spdl file.  Do not include the extension

    // in_PresetLocation - May be one of the siInstallationPath values (e.g. siUserPath, siUserAddonPath, etc.) or a string path

    // in_CustomPSetName - Desired name for the new object, or leave empty for default behavior

    //

    // Return Value: newly created custom pset

    function CreateTemporaryCustomPSet( in_PresetName, in_PresetLocation, in_CustomPSetName )

    {

    	var oPSet;

    	// Last argument is optional

    	if ( in_CustomPSetName == "" ) {

    		in_CustomPSetName = in_PresetName;

    	}

    	// Figure out whether this is a string path or an siInstallationPath value

    	in_PresetLocation = ( typeof(in_PresetLocation) == "string" )

    		? in_PresetLocation

    		: Application.InstallationPath(in_PresetLocation);

    	var presetFullPath = XSIUtils.BuildPath(

    		in_PresetLocation, "Data", "DSPresets", "Properties", in_PresetName + ".Preset"

    	);

    	try {

    		oPSet = CreateObjectFromPreset( presetFullPath, in_CustomPSetName );

    		Application.LogMessage( "Full path of " + in_PresetName + " instance is: " + oPSet.FullName );

    	} catch(e) {

    		Application.LogMessage( "Failed to create temporary instance of " + in_PresetName + " preset", siWarning );

    		return null;

    	}

    	return oPSet;

    }

### See Also

XSIFactory.CreateObjectFromPreset CreatePreset LoadPreset SavePreset SIGetPreset SILoadPreset SIAddPropEx