pymel.core.language.scriptJob

scriptJob(*args, **kwargs)

This command creates a “script job”, which is a MEL command or script. This job is attached to the named condition, event, or attribute. Each time the condition switches to the desired state (or the trigger is triggered, etc), the script is run. Script jobs are tied to the event loop in the interactive application. They are run during idle events. This means that script jobs do not exist in the batch application. The scriptJob command does nothing in batch mode. This triggering happens very frequently so for speed considerations no events are forwarded during playback. This means that you cannot use scriptJob -tc tcCallback;to alter animation behaviour. Use an expression instead, or the rendering callbacks “preRenderMel” and “postRenderMel”. When setting up jobs for conditions, it is invalid to setup jobs for the true state, false state, and state change at the same time. The behaviour is undefined. The user can only setup jobs for the true and/or false state, or only for the state change, but not three at the same time. i.e. if you do: // Set up a job that runs for the life of the application. // This job cannot be deleted with the “kill” command no matter what. scriptJob -e “SelectionChanged” “print “Annoying Message!\n”” -permanent;// set up a job for the true state scriptJob -ct “playingBack” playBackCallback;// set up a job for the false state scriptJob -cf “playingBack” playBackCallback;then you should NOT do scriptJob -cc “playingBack” playBackCallback;otherwise it will lead to undefined behaviour. This command can also be used to list available conditions and events, and to kill running jobs.

Flags:

Long name (short name)		Argument Types	Properties
allChildren (alc)		bool
	This flag can only be used in conjunction with the -ac/attributeChange flag. If it is specified, and the job is attached to a compound attribute, then the job will run due to changes to the specified attribute as well as changes to its children.
attributeAdded (aa)		<type ‘unicode’>, script
	Run the script when the named attribute is added. The string must identify both the dependency node and the particular attribute. If the dependency node is deleted, this job is killed (even if the deletion is undoable).
attributeChange (ac)		<type ‘unicode’>, script
	Run the script when the named attribute changes value. The string must identify both the dependency node and the particular attribute. If the dependency node is deleted, this job is killed (even if the deletion is undoable).
attributeDeleted (ad)		<type ‘unicode’>, script
	Run the script when the named attribute is deleted. The string must identify both the dependency node and the particular attribute. If the dependency node is deleted, this job is killed (even if the deletion is undoable).
compressUndo (cu)		bool
	If this is set to true, and the scriptJob is undoable, then its action will be bundled with the last user action for undo purposes. For example; if the scriptJob was triggered by a selection change, then pressing undo will undo both the scriptJob and the selection change at the same time.
conditionChange (cc)		<type ‘unicode’>, script
	Run the script when the named condition changes state. The string must be the name of a pre-defined, or a user-defined boolean condition. To get a list of what conditions exist, use the -listConditions flag.
conditionFalse (cf)		<type ‘unicode’>, script
	Run the script when the named condition becomes false. The string must be the name of a pre-defined, or a user-defined boolean condition. To get a list of what conditions exist, use the -listConditions flag.
conditionTrue (ct)		<type ‘unicode’>, script
	Run the script when the named condition becomes true. The string must be the name of a pre-defined, or a user-defined boolean condition. To get a list of what conditions exist, use the -listConditions flag.
connectionChange (con)		<type ‘unicode’>, script
	Run the script when the named attribute changes its connectivity. The string must identify both the dependency node and the particular attribute. If the dependency node is deleted, this job is killed (even if the deletion is undoable).
disregardIndex (dri)		bool
	This flag can only be used in conjunction with the -ac/attributeChange flag. If it is specified, and the job is attached to a multi (indexed) attribute, then the job will run no matter which attribute in the multi changes.
event (e)		<type ‘unicode’>, script
	Run the script when the named event occurs. This string must be the name of a pre-defined maya event. To get a list of what events exist, use the -listEvents flag.
exists (ex)		int
	Returns true if a scriptJob with the specified “job number” exists, and false otherwise. The “job number” should be a value that was returned on creation of a new scriptJob.
force (f)		bool
	This flag can only be used with -kill, -killAll, or -replacePrevious. It enables the deletion of protected jobs.
idleEvent (ie)		script
	Run the script every time maya is idle. WARNING, as long as an idle event is is registered, the application will keep calling it and will use up all available CPU time. Use idleEvents with caution.
kill (k)		int
	Kills the job with the specified job number. Permanent jobs cannot be killed, however, and protected jobs can only be killed if the -force flag is used in the command.
killAll (ka)		bool
	Kills all jobs. Permanent jobs will not be deleted, and protected jobs will only be deleted if the -force flag is used.
killWithScene (kws)		bool
	Attaches the job to the current scene, and when the scene is emptied. The current scene is emptied by opening a new or existing scene.
listConditions (lc)		bool
	This causes the command to return a string array containing the names of all existing conditions. Below is the descriptions for all the existing conditions: Events Based on Available Maya FeaturesThese events are true when the given feature is available. Event NameMaya FeatureAnimationExistsAnimationAnimationUIExistsUser Interface for AnimationBaseMayaExistsAny Basic MayaBaseUIExistsAny Interactive MayaDatabaseUIExistsDeformersExistsDeformer FunctionsDeformersUIExistsUser Interface for DeformersDevicesExistsDevice SupportDimensionsExistsDimensioningDynamicsExistsDynamicsDynamicsUIExistsUser Interface for DynamicsExplorerExistsExplorerImageUIExistsUser Interface for ImagingKinematicsExistsKinematicsKinematicsUIExistsUser Interface for KinematicsManipsExistsManipulatorsModelExistsBasic Modeling ToolsModelUIExistsUser Interface for Basic ModelingNurbsExistsNurbs Modeling ToolsNurbsUIExistsUser Interface for Nurbs ModelingPolyCoreExistsBasic Polygonal SupportPolygonsExistsPolygonal ModelingPolygonsUIExistsUser Interface for Polygonal ModelingPolyTextureExistsPolygonal TexturingRenderingExistsBuilt-in RenderingRenderingUIExistsUser Interface for RenderingOther EventsautoKeyframeState:true when Maya has autoKeyframing enabledbusy:true when Maya is busy.deleteAllCondition:true when in the middle of a delete-all operationflushingScene:true while the scene is being flushed outGoButtonEnabled:true when the Go button in the panel context is enabled.hotkeyListChange:true when the list of hotkey definitions has changedplayingBack:true when Maya is playing back animation keyframes.playbackIconsCondition:instance of the playingBackcondition used on the time sliderreadingFile:true when Maya is reading a file.RedoAvailable:true when there are commands available for redo.SomethingSelected:true when some object(s) is selected.UndoAvailable:true when there are commands available for undo.Flag can appear in Create mode of commandFlag can have multiple arguments, passed either as a tuple or a list.
listEvents (le)		bool
	This causes the command to return a string array containing the names of all existing events. Below is the descriptions for all the existing events: angularToleranceChanged:when the tolerance on angular units is changed. This tolerance can be changed by: using the MEL command, “tolerance” with the “-angular” flagchanging the pref under Options-GeneralPreferences-Modeling tab-Tangential ToleranceangularUnitChanged:when the user changes the angular unit.axisAtOriginChanged:when the axis changes at the origin.axisInViewChanged:when the axis changes at a particular view.ColorIndexChanged:when the color index values change.constructionHistoryChanged:when construction history is turned on or off.currentContainerChanged:when the user set or unset the current container.currentSoundNodeChanged:whenever the sound displayed in the time slider changes due to: the sound being removed (or no longer displayed) [RMB in the time slider]a new sound being displayed [RMB in the time slider]sound display being toggled [animation options]sound display mode being changed [animation options]DagObjectCreated:when a new DAG object is created.deleteAll:when a file new occursDisplayColorChanged:when the display color changes.displayLayerChange:when a layer has been created or destroyed.displayLayerManagerChange:when the display layer manager has changed.DisplayRGBColorChanged:when the RGB display color changes.glFrameTrigger:for internal use only.gridDisplayChanged:for internal use only.idle:when Maya is idle and there are no high priority idle tasksidleHigh:when Maya is idle. This is called before low priority idle tasks. You should almost always use “idle” instead.lightLinkingChanged:when any change occurs which modifies light linking relationships.lightLinkingChangedNonSG:when any change occurs which modifies light linking relationships, except when the change is a change of shading assignment.linearToleranceChanged:when the linear tolerance has been changed. This tolerance can be changed by: using the MEL command, “tolerance” with the “-linear” flagchanging the pref under Options-GeneralPreferences-Modeling tab-Positional TolerancelinearUnitChanged:when the user changes the linear unit through the Options menu.MenuModeChanged:when the user changes the menu set for the menu bar in the main Maya window (for example, from “Modeling” to “Animation”).RecentCommandChanged:for internal use only.NewSceneOpened:when a new scene has been opened.PostSceneRead:after a scene has been read. Specifically after a file open, import or all child references have been read.nurbsToPolygonsPrefsChanged:when any of the nurbs-to-polygons prefs have changed. These prefs can be changed by: using the Mel command, “nurbsToPolygonsPref”changing the prefs under Polygons- Nurbs To Polygons-Option BoxplaybackRangeChanged:when the playback keyframe range changes.playbackRangeSliderChanged:when the animation start/end range (i.e. the leftmost or rightmost entry cells in the time slider range, the inner ones adjust the playback range) changequitApplication:when the user has chosen to quit, either through the quit MEL command, or through the Exit menu item.Redo:when user has selected redo from the menu and there was something to redo. This callback can be used for updating UI or local storage. Do not change the state of the scene or DG during this callback.renderLayerChange:when creation or deletion of a render layer node has occured.renderLayerManagerChange:when the current render layer has changed.RebuildUIValues:for internal use only.SceneOpened:when a scene has been opened.SceneSaved:when a scene has been saved.SelectionChanged:when a new selection is made.SelectModeChanged:when the selection mode changes.SelectPreferenceChanged:for internal use only.SelectPriorityChanged:when the selection priority changes.SelectTypeChanged:when the selection type changes.setEditorChanged:obsolete. No longer used.SetModified:when the set command is used to modify a setSequencerActiveShotChanged:when the active sequencer shot is changed.snapModeChanged:when the snap mode changes. E.g. changes to grid snapping.timeChanged:when the time changes.timeUnitChanged:when the user changes the time unit.ToolChanged:when the user changes the tool/context.PostToolChanged:after the user changes the tool/context.NameChanged:when the user changes the name of an object with the rename command.Undo:when user has selected undo from the menu and there was something to undo. This callback can be used for updating UI or local storage. Do not change the state of the scene or DG during this callback.modelEditorChanged:when the user changes the options of a model editor.
listJobs (lj)		bool
	This causes the command to return a string array containing a description of all existing jobs, along with their job numbers. These numbers can be used to kill the jobs later.
nodeDeleted (nd)		<type ‘unicode’>, script
	Run the script when the named node is deleted
nodeNameChanged (nnc)		<type ‘unicode’>, script
	Run the script when the name of the named node changes
parent (p)		unicode
	Attaches this job to a piece of maya UI. When the UI is destroyed, the job will be killed along with it.
permanent (per)		bool
	Makes the job un-killable. Permanent jobs exist for the life of the application, or for the life of their parent object. The -killWithScene flag does apply to permanent jobs.
protected (pro)		bool
	Makes the job harder to kill. Protected jobs must be killed or replaced intentionally by using the -force flag. The -killWithScene flag does apply to protected jobs.
replacePrevious (rp)		bool
	This flag can only be used with the -parent flag. Before the new scriptJob is created, any existing scriptJobs that have the same parent are first deleted.
runOnce (ro)		bool
	If this is set to true, the script will only be run a single time. If false (the default) the script will run every time the triggering condition/event occurs. If the -uid or -nd flags are used, runOnce is turned on automatically.
timeChange (tc)		script
	Run the script whenever the current time changes. The script will not be executed if the time is changed by clicking on the time slider, whereas scripts triggered by the “timeChanged” condition will be executed.
uiDeleted (uid)		<type ‘unicode’>, script
	Run the script when the named piece of UI is deleted.

Derived from mel command maya.cmds.scriptJob

Example:

import pymel.core as pm

# create a job that deletes things when they are seleted
jobNum = pm.scriptJob( ct= ["SomethingSelected","pm.delete()"], protected=True)

# Now display the job
jobs = pm.scriptJob( listJobs=True )

# Now kill it (need to use -force flag since it's protected)
pm.scriptJob( kill=jobNum, force=True)

# create a sphere, but print a warning the next time it
# is raised over 10 units high
def warn():
        height = pm.getAttr( 'mySphere.ty' )
        if height " 10.0:
                print 'Sphere is too high!'
pm.sphere( n='mySphere' )
# Result: [nt.Transform(u'mySphere'), nt.MakeNurbSphere(u'makeNurbSphere1')] #

pm.scriptJob( runOnce=True, attributeChange=['mySphere.ty', warn] )

# create a job to detect a new attribute named "tag"
#
def detectNewTagAttr():
        print "New tag attribute was added"

pm.scriptJob( runOnce=True, attributeAdded=['mySphere.tag',detectNewTagAttr] )
pm.addAttr( 'mySphere', ln='tag', sn='tg', dt='string')

# list all the existing conditions and print them
# nicely
conds2 = pm.scriptJob( listConditions=True )
for cond in sorted(conds2):
        print cond