Scripting Glossary |
This file contains a complete glossary of the methods and procedures accessible from the scripting environment. This is a reference document. For more of an introductory environment, see the Introduction to Slim Scripting.
As mentioned in the introduction, Slim's scripting interface is also used by MTOR for communication with Slim, and by Slim itself when parsing files. It is for this reason that some methods available in the slim scripting environment may not actually be useful for scripting the behavior of Slim and are not germaine when Slim is used with RenderMan for Maya Pro.
Methods that fit this criteria are listed here but with minimal documentation and are formatted in italics. For example:
These methods are used to establish the scripting environment, and while available for all objects, are not generally useful.
These are the methods defined for the slim object:
Create backup versions of all palettes loaded. This method is called by MTOR when it detects that Maya has crashed.
Generate and build all shaders associated with attachable functions.
Optional arguments:
Completely reset Slim's state. The method is called by MTOR when it opens a new scene file.
Send a command or message to MTOR.
This method is used by MTOR to inform Slim that the selection in Maya has changed.
CommitCmds will:
Create or open a Slim palette. One of the following arguments is required:
Optional arguments:
Provides a complete encapsulation of the current state of Slim. This is used by MTOR to save Slim data into the Maya scene. The state can be restored using the Instantiate method.
Optional arguments:
Returns the object handle for the palette with the given name. If no name is provided, the first palette handle is returned. If a match cannot be found, the empty string is returned.
Returns the list of appearances from all palettes which match the criteria specified in the arguments. The criteria can use glob style notation, which means that you can use the standard wild card characters: *, ?, etc. If no arguments are provided, the result is equivalent to the request:
slim GetAppearances -name * -id * -master * -template * -type * -selected ignore -dirty ignore
Criteria are specified by the following optional arguments:
Example uses:
Returns a list of names of items selected in Maya that would have resulted from an attachment of type apptype.
Returns whether Slim's user interface is visible, or whether it is being run in batch mode.
Returns an encapsulation of the specified object. This can be used in combination with the Instantiate method.
Attachable types like Surface may have several types mapped to them. This method returns all of the types that have been defined to map to the specified type.
Example usage:% slim GetEquivalentTypes surface
shadingmodel shadingmodel_aov visualizer
Get object handles for all top-level palettes (i.e., subpalettes are excluded).
Optional arguments:
Given a template identifier, returns a version suitable for displaying to the user. This will match the string that the user sees elsewhere in the Slim interface. If the user has turned on Expert Menus, the version will be indicated by parentheses.
Optional arguments:
Example usage (in this example, the user has Expert Menus on):
% set app [slim GetAppearances -name Fractal*]
func5
% set tmpltID [$app GetTemplateID]
pixar,C_Fractal#0
% set tmpltLabel [slim GetPresentableTemplateName $tmpltID]
Fractal (v0)
Invokes the GetRIB method on the appearance with the specified unique ID. This is used by MTOR for rib generation.
Returns whether Slim is being run in conjunction with RfM ("server") or as a standalone application ("solo").
Always returns the message "Slim is active." This is used by MTOR to verify that Slim is operational.
Get a list of all active templates.
Optional arguments:
Returns the workspace object.
Instantiate Slim with the specified state string. This is how MTOR initializes Slim when opening a scene file.
Initialize the user interface for Slim. This creates all of the palette editors when opening a scene file.
Execute a command and journal it. That is, make it undoable. Journaling works by specifying a command to execute, a command to execute if the user hits undo, and (optionally) a command to execute if the user hits redo.
Arguments:
Most methods invoked by the user interface (e.g. SetValue) are automatically journalled. If you find that a method used in a script isn't journalled, you can use this command to make it undoable. More commonly, though, this method is used to gather together several journalled methods into one action.
For example, the following script operates on three different parameters and sets them to zero:set kd [$apph GetProperties -name Kd]
set ks [$apph GetProperties -name Ks]
set kr [$apph GetProperties -name Kr]
$kd SetValue 0
$ks SetValue 0
$kr SetValue 0
SetValue is automatically journalled. But if a user were to execute this script and then change his mind, he'd have to hit Redo three times. The following code groups this code into one action by disabling the journalling in SetValue and explicitly specifying undo behavior.
proc SetValues {p1 v1 p2 v2 p3 v3} {
# temporarily disable journalling
set old [::RAT::SetJournalingState 0]
$p1 SetValue $v1
$p2 SetValue $v2
$p3 SetValue $v3
# restore journalling
::RAT::SetJournalingState $old
}
set kd [$apph GetProperties -name Kd]
set ks [$apph GetProperties -name Ks]
set kr [$apph GetProperties -name Kr]
set curKd [$kd GetValue]
set curKs [$ks GetValue]
set curKr [$kr GetValue]
slim JournalCmd \
-doit "SetValues $kd 0 $ks 0 $kr 0" \
-undoit "SetValues $kd $curKd $ks $curKs $kr $curKr" \
-title "Zero Out K Values" \
-cmdkey [$apph GetID]
JournalCmd is most frequently used in CustomUIs, which
must often group several low-level commands into one action.
You will find several example uses of JournalCmd in
the CustomUIs that ship with Slim.
Set the workspace root to dir and read the specified workspace file.
This method is used by MTOR when importing a scene file
These methods are used for communication from MTOR to Slim.
These method are used by the SlimParser when reading a palette file.
Read the specified Slim file into the context given by context. If not provided the file is read into the global context. You can use this command to load additional Slim templates anytime Slim is running. You can also cause appearances or palettes encapsulated within a slim file to be imported into an existing palette by specifying the container palette's handle as the context.
This operates like ReadSlimFile, only reads data directly from the specified string.
Reload extensions to Slim. Class is the class of extension, which you will find in the LoadExtension calls in slim.ini:
With the class argument omitted, this will reload all extensions
Write user preferences to disk. This is usually performed when Slim shuts down.
This method is used by Slim for Pick Objects in Maya.
These methods are used by MTOR to intialize Slim.
Shut down Slim. This is usually used by RfM to indicate that Maya is shutting down.
This method is deprecated.
Same as the tcl/tk "update" builtin
Issue a command to a specified window
Example uses:
These are the methods defined for the workspace object. For more background on workspaces, please refer to the Workspace Editor documentation.
Add a directory mapping from fromPath to toPath. The mapping will only be applied on systems in the specified zone. Directory maps are also applied by workspace ResolvePath path.
The following is an example of two directory mappings that would allow any paths beginning with /users to always be replaced with C:/users on windows machines, and vice versa on unix machines:
% workspace AddDirMap /users C:/users UNC
% workspace AddDirMap C:/users /users NFS
Add the path p to the search paths. The optional argument which, if provided, should be either local or server, which indicates whether to add the path to the project or server paths. If not provided, the default is to add to the project paths.
Apply directory mapping to the specified path. The first mapping with a fromPath that matches a portion of path will be applied. Returns the mapped path.
Create all of the directories associated with the workspace definition.
Clear directory mappings. With no additional arguments, all directory mappings are cleared.
Optional arguments:
Remove the path p from the searchpath list associated with which. The optional argument which, if provided, should be either local or server, which indicates whether to clear the path from the project or server paths. If not provided, the default is to clear from the project paths.
Create a temporary workspace file. This method is used for deferred ribgen
Determine the location of the abstract directory type given by name. The list of known abstractions can be obtained via the GetDirNames method. The optional dosubst argument controls whether variable substitution is performed on the directory value, and defaults to 0 (do not perform substitution). The optional createit argument, if set to 1, causes the directory to be created; it defaults to 0.
Determine the zone in which the system is operating. The system's zone is specified by a preference called WSDirMapZone, which is set in the default RAT.ini. The default zoning scheme is based on filesystem type. Windows systems are in the UNC zone, while all other systems are in NFS. The list of all possible zones is specified by the pref called WSDirMapZoneList, also set in RAT.ini.
Get the list of possible zones in which directory mappings can be applied. Each directory mapping must be associated with one zone. A list of possible zones is given by the preference called WSDirMapZoneList, which is set to {NFS UNC} in the default RAT.ini. As you may have guessed, the default zoning scheme is based on file system type. Unices would be NFS and windows would be UNC. A systems's zone is specified by the preference called WSDirMapZone, also set in RAT.ini.
Get the list of directory mappings. Each element in the list a sub-list containing a {to from zone} triplet. Here's an example list of dirmaps (paths containing spaces are surrounded by an extra set of braces):
{{foo bar UNC} {bar foo NFS} {{C:/Documents
And Settings} /users NFS}}Get the list of names of project resource locations. Use workspace GetDir name to get the actual directory name of the resource location, relative to the project root.
Get the name of the workspace file.
Get the current root directory. This method is equivalent to: workspace GetDir WSRoot.
Get the directory in which the Maya scene file resides.
Get the list of resource types (shader, texture, etc.) for which searchpaths are defined. The which argument specifies whether to check local (the default) or server searchpaths.
Get the current project or server search paths depending on the which argument. To get the default project or server search paths, which should be local or server, respectively. Or to get the search paths used by a particular resource type, the which argument can be the name of the resouce type, like shader or texture. Note that if the search paths for a resource type are emtpy, the default will be used instead. The optional dosubst argument indicates whether to perform variable substitution when set to 1 (it defaults to 0). You can choose the format of the return value using the optional fmt argument which can be one of: list or RIB; the default is to return a list.
Prepend the current project root directory to the relative pathname given by subpath, and return the result.
Determines whether the specified type of path is locked.
Possible values for type:
Convert an absolute file reference given by path to a relative one by stripping off known leading path components. You can choose to strip only if the path is below the current workspace root by setting the optional argument w to workspace. The default behavior is to consider all directories in the current local search paths.
Operates like SetDir method, but locks the directory to prevent future changes.
Set and lock the root directory.
Operates like SetSearchPaths method, but locks the searchpaths to prevent future changes.
Encapsulate the current state of the workspace object.
Reload the last workspace file associated with the current workspace root. i.e., revert to the saved version of the current workspace file.
Determine a fully qualified pathname to the file given by path by traversing search paths to resolve the file. This command returns the empty string if the file can't be found. The which argument can be used to indicate that only the searchpaths for the given resource type should be searched. Otherwise the default local search paths are used. You can also provide an optional list of space separated potential extensions (in a single string) which are appended to the filename during the search; for example:
% workspace ResolvePath fish {} "tif tex"
will search for fish.tif and fish.tex in the default searchpaths.
A list of the found files (full pathnames) will be returned.
% workspace ResolvePath fish texture "tif tex"
will search for fish.tif and fish.tex in the texture searchpaths.
Also note that directory mappings will be applied to the path before it is resolved. For example, if a dirmap exists which maps /home to C:/home in the UNC zone, then the following command on a UNC system:
% workspace ResolvePath /home/somefile
could return:
C:/home/somefile
Restore searchpaths to application defaults.
Restore setup files to application defaults.
Sets the resource abstraction given by name to the value given by location. These abstractions are used to determine where rendering related resources are to be found; the list of known abstractions can be obtained via the GetDirNames method.
Set the list of directory mappings to the specified maplist. Each entry in the list must be a {to from zone} triplet (list). Any pathnames that contain spaces should be surrounded by an extra set of braces. For example:
% workspace SetDirMaps {{foo bar UNC} {bar foo NFS} {{C:/Program Files/goo}
/users/goo NFS}}
Set the current workspace root and initialize the workspace object's state using the contents of the last workspace file in use at that location or the file specified via the optional projectFile argument.
Setthe search paths in the workspace object to p, which should be a single string (or list) containing one or several space-separated paths. Paths containing spaces should each be enclosed in an extra set of braces. The optional argument which can be local, server, or the name of a resource type, like texture or shader. local and server indicate that the default project or server paths should be updated. If not specified the default is to modify the local project paths.
This method is used by MTOR to update the workspace's scripting state after making changes.
Write the current state of the workspace to the current workspace file.
The TreeNode base class implements the support for organizing objects in tree structures. Refer to the Class Hierarchy diagram to see the list of classes that inherit from TreeNode. Because the classes representing the palettes, appearances, and parameters that you manipulate all inherit from this class, the following methods are common to all of them:
Re-parent the specified object under this object. By default, the new child will be last in its parent's list of children. You can make the child the first in the parent's list by passing 1 for the front parameter. Note that you can use this command to move appearances and sub-palettes between palettes.
Get a list of the handles to the children of this object.
Get the list of all descendents of this object. The descendents are sorted according to the mode argument which can take one of these values:
Get the draw mode for the object. For inlined functions, this is set to "inline".
Get the handle to this object's parent.
Get the handle to the object that parents all objects in this object's tree.
Removes the specified child. By default, the child will also be deleted.
Note: using this command to delete a node may not remove all references to the child object, which can cause problems when working with appearances. We recommend that you use the Delete method to delete an appearance.
Explicitly set the list of children for the object.
PaletteEntry is another base class that defines a common set of functionality for palettes and appearances. The following methods are defined for these classes:
Deletes the entry. By default, the entry is only
scheduled for deletion, which allows it to be
easily undeleted.
Setting the optional remove
argument to 1 causes the entry to be immediately deleted. Using
Delete 1 repeatedly is not recommended, as
Delete 1 can be slow if called many times in a row.
The recommended method for forcing the deletion of multiple
objects is:
foreach object $objects {
$object Delete 0
}
update
slim CommitCmds
Generate a new unique ID for the entry.
Get the description for the object. The description is what is displayed when the user raises the help balloon for that object.
Get the display level for the entry.
Possible levels:
Get the unique ID for the entry.
Get the label for the object. For palette entries, this is usually identical the name.
Get the name of the object.
Get the type for the entry.
User data is additional information associated with a PaletteEntry. It is stored as a series of name-value pairs. Other than that, the contents are completely arbitrary. You may find it to be a valuable way to store extra information for your scripts, or to communicate information from templates to CustomUIs. UserData is not visible in the Slim interface.
GetUserData accesses the user data stored with the specified key. If no user data is defined for this key, the empty string is returned.
Get the entire array of user data. This can be useful when copying user data from one object to another.
Because of the undoable nature of Delete, nodes that have been deleted via the interface may still be accessible from the scripting environment. This method allows you to check for this case.
Returns whether the node is "dirty" and needs to be saved.
This method allows you to quickly check whether a node is hidden.
Set the entry's description to the specified string.
Set the display level for the entry.
Set the unique ID for the entry to id.
Set the image using the specified encoded string. This method is used when reading a palette file.
Set the entry's label to the specified string.
Set the user data for key to value.
Set the entire array of user data. This can be useful when copying user data from one object to another.
Recover an entry scheduled for deletion. Note that this will not work if an entry has been immediately deleted.
In addition to the methods defined in the PaletteEntry and TreeNode base classes, the following methods are defined for the objects representing the palettes and subpalettes in your scene:
Change the mode in which this palette is saved:
Creates a new appearance inside this palette.
Valid options:
Delete any nodes in the graph that are not attachable and are not connected to any other attachable nodes.
Deletes the appearances represented by any object handles listed. This method acts like the Delete method in that nodes are, by default, not immediately deleted. The optional -remove flag specifies immediate deletion.
Remove of all unused appearances in the palette. Appearances are deemed unused if they are not attached to any geometry in the Maya scene. This method is only meaningful if Slim is is connected to MTOR.
Because it interacts with MTOR, this method cannot be called via MEL using slimcmd).
Raise the Palette Editor for this palette.
Get the write permissions for this palette:
Get the appearances in this palette matching the specified criteria. See the entry for slim GetAppearances specifics on criteria.
Get the filename associated with an external palette. This filename is generally derived from the palette's label. Returns the string untitled if the palette is internal or has never been saved.
This method is deprecated.
Get the save mode for this palette. Possible modes are discussed in ChangeSaveMode.
Determine whether palette is internal (stored with a Maya scene) or external (stored as a separate file).
Import the compiled shader (fully) specified by file. The optional -render flag triggers a subsequent preview render of the shader.
Determine whether palette is internal (stored with a Maya scene) or external (stored as a separate file).Instantiate the object that has been previously encapsulated in the string slimstr. Typically you would obtain slimstr from a call to slim Encapsulate obj with an appearance or sub-palette handle. (Though Instantiate and InstantiateApp are equivalent, InstantiateApp is the preferred usage.)
Convert an external slim palette to an internal one. Note that because the file containing the external palette will still exist, this amounts to copying the data inside the palette. As such, Slim will regenerate unique IDs for all elements inside the palette to prevent any possible conflicts with the palette stored in the file. RfM will update the attachment data in the Maya scene.
These methods are used by the SlimParser when reading a palette file.
Read the palette encapsulation in filename into the palette object.
Revert the palette to a checkpoint file saved in filename. The checkpointed file should be one created using Save with the -checkpoint option enabled, though this is not strictly enforced.
The palette stored in the checkpointed file should have a unique ID identical to that of the current palette. Reverting to a palette with a different unique ID may result in the loss of shader attachments.
Save the palette into the the external file filename. If the palette is currently internal, it will be converted into an external palette.
Optional arguments:
Select the appearances specified by applist.
Set the write permissions for the palette.
Set the save mode for this palette. Note that this only used by the parser and will not perform any conversion for your palette. To change the save mode via scripting, use ChangeSaveMode.
These methods are used by the SlimParser when reading a palette file.
Undelete the appearances represented by any object handles listed. This method acts like the Undelete method in that it will only undelete appearances that are scheduled for deletion.
Generate new unique IDs for all appearances in the palette. If MTOR is connected, it will be updated with new unique IDs to maintain appearance connections. Unless the -keepnames flag is passed, each will receive a new name.
Update the Palette Editor for the palette. It is sometimes necessary to invoke this method after making changes to the palette via scripting. If no editor is associated with the palette, a value of 1 is returned. Otherwise a value of 0 is returned.
Appearance is a base class representing Functions (dynamic nodes that generate a shader) and Instances (which refer to an existing shader).
The following methods are defined for appearances:
Attach the appearance to the current Maya selection. This is only meaningful if called when Slim is connected to MTOR.
The optional subtype argument is used to specify the subtype for volume shaders.
Because it interacts with MTOR, this method cannot be called via MEL using slimcmd. Instead, you can use the following MEL:
mtor control attach surface `slimcmd apph GetID`;
Detach the appearance to the current Maya selection. This is only meaningful if called when Slim is connected to MTOR.
The optional subtype argument is used to specify the subtype for volume shaders.
Because it interacts with MTOR, this method cannot be called via MEL using slimcmd. Instead, you can use the following MEL:
mtor control detach surface `slimcmd apph GetID`;
Create a duplicate of the appearance and store it in the same palette.
Optional arguments:
Edit the appearance in the Appearance Editor. If the appearance is already being edited, this will raise the Appearance Editor.
Optional arguments:
This method is deprecated.
Encapsulate and export the appearance to a file specified by filename.
Get the type of attachment (ensemble, surface, displacement, etc.) the appearance makes to geometry. Some appearance types like shadingmodel can be mapped to an attachment type like surface. These mappings are defined by the SlimAttachableMap preference set in slim.ini. For appearances that cannot be attached to geometry, the empty string is returned.
For light shaders, get the type of light (e.g. distant).
Get the master of the appearance: the base string used to refer to the shader in the RIB file. Set the optional parameter dosubst to 1 to perform variable substitution on the returned result. If not specified, dosubst defaults to 0.
Get the appearance's namespace. Usually this is the empty string, indicating the global namespace. The namespace is usually set when the enclosing palette is loaded and is useful when storing palettes within Maya scene files undergoing import or reference operations.
These methods get the settings used for preview renders in the Appearance Editor.
Get the list of an appearance's properties that match the search criteria, specified using one of the following flags. The criteria can use glob style notation, which means that you can use the standard wild card characters: *, ?, etc. If no arguments are provided, the result is equivalent to the request:
apph GetProperties -name * -access * -type * -class * -provider * -private
Optional filtering criteria:
Options:
Get the root of the tree of properties for this appearance. All parameters, collections, and attributes in the appearance are descendents of this property. You can use this method along with the GetChildren method to descend through the property tree.
Get the subtype of this appearance. Currently, this only applies to volume appearances, which can be defined to be of subtype atmosphere, interior, or exterior.
Get a list of actions that must be performed before rendering. This applies to nodes like ImageFile, which must sometimes convert an image to a texture before it is used.
Though these methods are primarily used by the SlimParser, they can also be used to add parameters to a dynamic template. The method creates a property and returns a handle to it that you can then use to specify more information.
Example usage:
For a real example, see the source of the AddParam customui.set newProp [$apph NewParameter float Kd] $newProp SetLabel "Diffuse Component" $newProp SetDescription "Amount of diffuse light" $newProp SetDefaultValue 1
Pick all objects to which this appearance is attached. With the -adapt flag, this script acts like the Pick Objects (Computed) command. That is, attachable shaders that use this appearance (including adaptors) will also be considered.
Because this method interacts with MTOR, it cannot be called from a slimcmd.
Mark all properties in the appearance as set. This will protect the values from any changes to templates.
Initiate a render of the preview swatch for this appearance.
Reload the source of the appearance, whether it be a template, or a shader or slim file on disk.
For functions, the Reload method will track when the template file was loaded and when it was last changed. By default, it will only successfully reload the template, if the file on disk has changed since the palette was loaded. To force a template reload, use the -force flag.
Unset the values for all properties in the appearance editor. These properties will revert to their default value.
Set the type of light (e.g. distant) for this appearance. This is only applicable to light shaders.
Set the master of the appearance: the base string used to refer to the shader in the RIB file.
Set the appearance's namespace. The namespace is usually set when the enclosing palette is loaded and is useful when storing palettes within Maya scene files undergoing import or reference operations.
Set the subtype of this appearance. Currently, this only applies to volume appearances, which can be defined to be of subtype atmosphere, interior, or exterior.
Update the Appearance Editor for the appearance. This sometimes necessary when making changes to an appearance's properties. If no editor is associated with apph a value of 1 is returned. Otherwise a value of 0 is returned.
Functions are nodes created from a template, and are combined to create a shader. Function is a subclass of Appearance, so Functions support all of the Appearance methods listed above.
The following methods are defined for functions:
Generate and compile the shader for this appearance. By default, Slim will check the dirty status of the appearance and only continue if it has changed since the shader was last generated. You can override this and force shader generation by using the -force flag.
Create a new Instance of this shader. By default, the Palette Editor will be updated. This behavior can be overridden by passing -update 0.
Delete this function and any function in its network. Technically, these functions are only scheduled for deletion, and may be recovered with either Undelete or UndeleteNetwork.
Indicate that the shader for the function needs to be regenerated. For most changes to functions, Slim is able to detect dirtiness. This method allows one to force dirtiness for a situation that Slim does not handle. The layering customui, for example, makes use of this method when rearranging layers.
Duplicate the entire network for this function and store it in the same palette.
Optional arguments:
Create a new appearance by flattening an active function network into a single frozen instance. The new appearance will have a name based on the name of this appearance, and will be flattened according to the Instance Structure preference.
Optional arguments:
Get the list of downstream attachable appearances that -- directly or indirectly -- connect to this appearance. By default, the returned list will consist of object handles. To get a list of unique IDs instead, pass -return id.
Return the list of properties that connect to this function.
Get the list of functions to which properties have connected. Even if multiple properties connect to the same function. This list is guaranteed not to have any redundant listings, and is therefore useful when writing recursive procedures.
Get a list of instances that have been created from this function. Note that this will only return instances that exist in the same palette as the function.
Get the shading language source for this function.
Determine the kind of shading language generator used by this function (e.g. StaticFunction, DynamicFunction, GenerativeFunction, etc.)
Get the object handle for the template that begat this function.
Get the template identifier (e.g. pixar,SurfacePoint#0) for this function.
Determine whether the template used by this function is obsolete. This is often used in conjunction with UpgradeTemplate
Determine whether the shader for this function needs to be regenerated and recompiled before it is used for a render. Slim will automatically dirty a master when, for example, changes are made to internal parameters. The master can also be dirtied via the DirtyMaster method.
These methods are used by the SlimParser when reading a palette file.
Undo the execution of Delete Network.
Update all instances of this function. This command regenerates the shader (if necessary), and then reloads any instances of this function that are stored in the same palette.
Upgrade the template used by this function to its latest version. You can determine whether the current template is obsolete by using the IsDownRev method.
The Template class is a subclass of Function. As mentioned above, you can access the Template object for a function via the GetTemplate method. For your convenience, however, this is usually not necessary. Most methods that access template information like GetSLSource can be called straight from the function.
Therefore, the methods specific to the Template class are not especially useful for scripting, but are listed below:
These methods are all used by the SlimParser when reading template and palette descriptions.
Instance objects represent appearances in shader that work with an existing shader. Instance objects are used to represent proper Instances created from functions, as well as any appearances created by importing a shader. Instances do not have templates. Their source is a shader on disk, and perhaps a function in the palette. As such, the methods specific to instances are fairly limited:
Get the file or function which begat this instance. The file is returned for instances created from imported shaders. For proper Instances, the progenitor is the unique ID for the original function.
Get the object handle for the original function. If the instance was created from an imported shader, this method returns the empty string.
Set the progenitor for this instance.
Property is a base class representing the Parameters, Collections, and Attributes inside of an appearance. You will mainly deal with subclasses of Property. The only true Property objects are the roots of the Property Tree for each appearance. This root, not visible in the user interface, is accessed using the GetPropertyTree method for appearances.
The following methods are common to all subclasses of Property:
Create the widget for this property as it is seen in the Appearance Editor. This is most often used from within a CustomUI to build a Value Editor for a property. Arguments detail the specific canvas and window information for the widget, along with suggested width and height. By default, the Property Menu will appear for any property without a default connection. You can override this behavior using the -menu switch. See some of the factory customui scripts for example usage.
Build the icon for this property. Like BuildDefaultWidget, this method is most often used from within a CustomUI.
Create an instance of the specified template and connect it to this property.
Determine access -- whether it as input or output -- for this property.
Get the object handle for the appearance that uses this property.
Useful when journaling a command, this method accesses the proper command key for the property. This is useful for properties inside of appearances that may be inlined.
Get the object handle for the function to which this property connects. This method will only return the connected function if it is being used. That is, if the property's ValueProvider is not set to connection, it will return the empty string.
Return the unique ID for the function to which this property connects. Unlike GetConnectedFunction, this method will return an ID as long as it exists. The ValueProvider is not consulted. For this reason, and because the unique ID is returned, rather than the (more useful) object handle, GetConnectedFunction is the preferred method to use when scripting.
Get the connection style for the property. For inline connections, this will return "inline". Otherwise, this will return an empty string.
Get the detail for this property. Possible values for detail:
Get the label for the object. The label is primarily used for interface, and can therefore contain special characters (including spaces).
Get a reference to the variable which stores the label. You can use the result of this as the -textvariable when creating Tk widgets in a CustomUI.
The name will often be used within RIB or shading language and must therefore resemble a variable.
Get the property's msghandler defined for the specified message.
Get the entire array of msghandlers for this property.
Get subtype for this property. Subtype is most often used to define a specific editor for a property. Properties representing a texture name, for example, are of type string, but of subtype texture.
User data is additionalinformation associated with a property. It is stored as a series of name-value pairs. Other than that, the contents are completely arbitrary. You may find it to be a valuable way to store extra information for your scripts, or to communicate information from templates to CustomUIs. UserData is not visible in the Slim interface.
GetUserData accesses the user data stored with the specified key. If no user data is defined for this key, the empty string is returned.
Get the entire array of user data. This can be useful when copying user data from one object to another.
Get the source of a property's value. Valid ValueProviders depend on the specific subclass of Property. This is the complete list of possible values:
Get the range of valid value providers for the property. An empty list (the default) signifies no change from the default behavior.
Set whether this property is an input or output.
Connect the property to the function with the specified unique ID. When using this method, you must also make sure that the property's ValueProvider is set to connection. To disconnect the property from a function, pass the empty string as id. The optional args list is used by Slim for more customized undo behavior.
Set the detail for the property, as defined in GetDetail. For properties with detail mustvary, the optional default parameter can be used to specify the default template to make a connection to. For an inline connection, pass inline for style.
Set the Draw Mode for a property. The default Draw Mode is all. When a Collection has a Draw Mode of children, it will not be drawn, but its children will.
Set the entry's label to the specified string.
Set the property's msghandler for msg to be cmd.
Set the state of the property. Most often, this is used with Collections, which can either be open or closed. Properties without any children have a barren state.
Set the user data for key to value.
Set the entire array of user data. This can be useful when copying user data from one object to another.
Set the ValueProvider for the property to p. Valid options for ValueProvider are discussed in the GetValueProvider method.
Set the range of valid ValueProviders to the provided list, e.g. {constant connection}. You can use this to, for example, prevent a property from being marked external. Valid entries for the range are discussed in the GetValueProvider method.
Collection objects are used to group Parameters and Attributes. Since they do not have a value, there is but a small number of methods specific to Collection objects:
CustomUIs are defined on Collection properties. These methods access the CustomUI information for a collection.
Like their counterpart methods defined for the Appearance class, these methods are used both for parsing a palette file, and for creating new properties in a dynamic template. When using these methods, any properties will be created as children of the collection.
Set the customui information for the collection.
The AtomicProperty base class represents all properties which have a value. Because of this, the majority of the methods listed below relate to the property's value. Parameter and all of the *Attribute classes are all subclasses of AtomicProperty, and from a scripting point of view, are relatively similar.
If the property is an element of an array, get its index. If the property is not an element of an array, this method will return -1.
Get the default value for this property.
Get the TCL expression that is set for this property. Note that this may return an expression, even if the property's ValueProvider is not set to expression.
Get the current value of the property.
Get the context in which a TCL expression will be evaluated. By default, TCL expressions are evaluated in the mtor context, allowing them to make use of information such as the object name, frame, etc. TCL expressions that wish to evaluate before rib generation and/or make use of the Slim scripting environment will be evaluated in the slim context.
Get the user range for the property, which is set when the user enters a value beyond the template-specified range (including precision).
Revert the value for this property to its default.
Set the index for a property that is an element of an array. An index of -1 indicates that this property is not an element in an array.
Set the default value for this property to be v.
Set the TCL expression for this property to be the specified string. To use this effectively, you will want to make sure that the property's ValueProvider is set to expression.
Set range to r, where r is a list containing {min max} or {min max precision}.
Set the context in which a TCL expression is evaluated.
Set the user-overridden range for a property. This is mainly used by the SlimParser.
Set the current value of the property. The dynamic flag is used to indicate that the value is being set interactively. This will, among other things, keep the value from making its way onto the Undo stack. A slider, for example, would have dynamic set to 1 when the user is dragging the slider back and forth and set to 0 when the user releases the slider.
Evaluate the expression specified by str. Results of the validation will be sent to the Message Log. If the evaluation generates an error, it will be returned. A successful evaluation will return an empty string.
Validate a property that has a TCL expression for its value. This is useful for properties that, for example, contain a txmake expression.
What sets the Parameter class apart from other subclasses is its existence inside of the shader. It is for this reason that the methods specific to Parameter are oriented toward its presencing in shading language.
Get the name of the parameter as it exists in shading language. The uniqueify parameter specifies whether to guarantee the the parameter has a unique name by prepending it with the name of the appearance. This is necessary for non root-level Functions.
Get the parameter's value in a format suitable for shading language. For example:
% $parmh GetType
color
% $parmh GetValue
{1 0 0}
% $parmh GetValueSL
color(1,0,0)
Attribute objects represent RIB attributes associated with your shader. This is the only method unique to the Attribute class:
It is briefly mentioned in the listing for GetValueProvider that for an Attribute, a value provider of variable indicates that the Attribute is disabled. This is admittedly not very intuitive, so the IsEnabled method is provided as a convenience.
Though internally these classes differ from the AtomicProperty base class, from a scripting perspective they are the same. There are no methods specific to these classes.
This index lists all of the classes of objects with which you will interact. These classes all derive from the TreeNode class, as demonstrated by the Class Hierarchy diagram.
This index lists the common name (how we refer to the class in documentation), the internal name (how the class is used within Slim internals), and the scripting name (how the class is used within the Slim scripting environment). Base classes like TreeNode do not have a scripting representation.
| Common Name | Internal Name | Scripting Name |
| TreeNode | ::Slim::TreeNode | |
| PaletteEntry | ::Slim::PaletteEntry | |
| Palette | ::Slim::Palette | ::Slim::AlterEgo::plt |
| Appearance | ::Slim::Appearance | |
| Function | ::Slim::Function | ::Slim::AlterEgo::func |
| Template | ::Slim::Template | ::Slim::AlterEgo::tmplt |
| Instance | ::Slim::Instance | ::Slim::AlterEgo::inst |
| Property | ::Slim::Property | ::Slim::AlterEgo::prop |
| Collection | ::Slim::Collection | ::Slim::AlterEgo::coll |
| AtomicProperty | ::Slim::AtomicProperty | |
| Parameter | ::Slim::Parameter | ::Slim::AlterEgo::parm |
| Attribute | ::Slim::Attribute | ::Slim::AlterEgo::attr |
| SlimAttribute | ::Slim::SlimAttribute | ::Slim::AlterEgo::slimattr |
| TCLAttribute | ::Slim::TCLAttribute | ::Slim::AlterEgo::tclattr |
| TORAttribute | ::Slim::TORAttribute | ::Slim::AlterEgo::torattr |
The following procedures are defined in the Slim scripting environment:
This procedure returns the name of the current application. (Hint: it's "slim".)
Get the value of the specified environment variable. You can use the optional default argument to specify a value to return if the environment variable is not defined.
Get the name of the host machine that is running Slim.
Get a name-value list of platform information, suitable for setting as an array, e.g.:
% array set platform [GetPlatform] % set platform(os) Linuxtcl veterans will recognize this as the tcl_platform global.
Get the value of the specified preference. You can use the optional default argument to specify a value to return if the preference is not set. Note that querying an unset preference will have the side effect of setting that preference to the specified default.
Get the name of the user that is running Slim.
Get the current version of the application. The optional
variation parameter dictates
how much version information to print. By default,
the numeric variation is used:
6.5.
6.5b3.
slim -version.
Generate a new unique identifier.
Send the message msg to the Slim Message Log. Valid values for level are: COPIOUS, INFO, NOTICE, WARNING, ERROR, SEVERE, in order of rising priority.
Invoke the File Picker. Arguments to this command specify how to configure the File Picker and the command to execute when the user has selected a file:
Set the specified preference to the specifed value.
These procedures are defined via the Custom Commands that ship with Slim. You may find them useful to use in your own scripts.
Enumerate external resource usage and point out unresolved resources. The report is printed to the Slim Message Log. By default the report is verbose. The only valid arg is -short, which trims the report down to only workspace information and warnings about unresolved resources. Source can be found in the file customcmd.slim.
Searches for pattern in string entry fields of appearances and replaces with replace. Information about each match replacement that occurs is printed to Slim's Message Log. Note that expression fields (ie. fields with the orange tcl button to their right) are not included in this search/replace. You may also provide one or more of the following optional arguments:
|
Pixar Animation Studios
|