MGPickerAnimation

MGPickerAnimation is NOT undoable, queryable, and editable.

This command creates / queries / edits / plays picker animation item.

Go to: [MEL Examples] [Python Examples]

Synopsis

MGPickerAnimation( allProperties=string, backward=boolean, clearKey=boolean, clear=boolean, deferHiding=boolean, duplicate=boolean, duration=boolean, easingType=string, exist=boolean, getIdFromName=string, keyframe=boolean, loadInEditor=boolean, mirror=boolean, name=string, play=boolean, playByName=string, properties=string, removeKey=boolean, remove=boolean, removeProperties=string, supportedEasingTypes=boolean, startValueBlending=boolean, time=unsignedint, view=string, value=float, )

MGPickerAnimation

-allProperties(-aps)   string   C Q E M

In query mode, this returns all the properties get animated in this animation item, each property is of “pickerItemID.propertyName” form.

In edit mode, this set the properties to be animated, the keyframes of included properties will remain, but those not in the properties will be removed.

An empty list of properties means clearing the content of the animation item; If there is any invalid properties, the whole action will be given up.

-backward(-b)   boolean   C E

Part of playback api, to play the animation backward.

-clearKey(-ck)   E

This is a edit only flag to clear all keyframes for an animated property.

With -properties flag it only clears the keyframes from the specified properties, without -properties flag it will clear keyframes for all animated properties.

Note that it only clears the keyframe, the properties are still left included in the animation item, but just not animated.

-clear(-cl)   E

Clear all the properties and keyframes, which leaves this animation item empty.

-deferHiding(-dh)   boolean   C Q E

Part of playback api, to solve one specific problem when this API is used in an attribute button’s post change command.

An attribute button can control other picker items’ visibility, switching the attribute value will potentially turn off visibilities of some picker items.

Without defer hiding flag on, these picker items may be hidden immediately when the attribute value changed, the possible animation on them will not be seen. With defer hiding, these items will only be hidden when the animation on them finish playing.

-duplicate(-dup)   E

This is an edit-only only flag to duplicate an animation item, the duplicated new item ID will be returned.

-duration(-dur)   Q

Query only flag to get the keyframe duration of the animated property in milliseconds. 1000 mean one second.

The duration always count from frame 0, regardless the first keyframe is larger than 0 or not.

With -properties flag it gives you the duration of specified properties, without -properties flag it will return duration for all animated properties.

You can then get the maximum number of these returned duration intergers to know the overall duration of the animation item.

-easingType(-et)   string   C Q E

In query mode with -properties flag, it returns the easing types of the animated properties, of all keyframes. Without -properties flag it returns for all animated properties.

In create/edit mode it works with -properties, -value -keyframe and -time flag to specify the easing type of the keyframe to set for the property at the specific time.

The possible values can be known by running MGPickerAnimation -q -supportedEasingTypes.

The type string is case-insensitive.

-exist(-ex)   Q

Query only flag to check if the animation item with ID exists or not.

-getIdFromName(-gin)   string   Q

To get the animation item ID by its name.

-keyframe(-k)   C Q E

In query mode with -properties flag, it returns the keyframe information of the animated properties, without -properties flag it returns the keyframe information for all the properties. The return values will be a string array whose each three elements be of the form ["time", "value", "eashingType"].

In create/edit mode it works with -properties, -value -easingType and -time flag to set keyframe for the property at the specific time.

-loadInEditor(-lie)   C Q E

In query mode this returns the current animation item ID that is loaded in the Animation Editor.

In create/edit mode this load the animation item in the Animation Editor, note that only the one belongs to the currently active picker view will be loaded in the Animation Editor.

-mirror(-mrr)   E

This is an edit-only only flag to mirror duplicate an animation item, the item properties will be replaced to the mirrored item properties, as well as there mirror-sensitive property values, e.g. X, HAlignment, etc.

The name of animation item will also be processed to switch betwen _L and _R, etc.

-name(-n)   string   C Q E

The name of the animation item.

-play(-p)   C Q E

Edit only flag to playback an existing animation item by its ID.

-playByName(-pbn)   string   E

Edit only flag to playback all animation items that have the name. All the matched animation item will be played back at the same time.

With this flag set, you don’t need to specify a ID for this command, if you do, only the animation item of the ID will be played.

-properties(-pps)   string   C Q E M

This flag is mainly used for query / edit api to specify property filer, so that the query and edit are limited to the specific properties.

All the animatable propery names of a picker item can be queried by MGPickerItem -q -animatableProperties itemID.

-removeKey(-rk)   E

Edit only flag to remove keyframe at the time specified by -time flag for properties specified by -properties flag. If not time specific, it will clear out all times, works the same as -clearKey flag.

-remove(-rm)   E

Edit only flag to remove the animation item from the scene.

-removeProperties(-rps)   string   M E

Remove the properties from the animation item.

-supportedEasingTypes(-ses)   Q

Query only flag to get all the supported easing types.

-startValueBlending(-svb)   boolean   C E

Part of playback api, to avoid popping at the start of the animation playback.

This flag ensure that from the starting keyframe and on, the current actual value of the property will be used until there is a different keyframe value.

This applies to both forward playback and backward playback, it is just for backward playback this will blend last couple keyframe values.

-time(-t)   unsignedint   C Q E

In query mode with -properties flag, it returns the time intergers of the animated properties of all keyframes. Without -properties flag it returns time intergers for all animated properties.

In create/edit mode it works with -properties, -value -keyframe and -easingType flag to specify the time where the keyframe will be set.

-view(-v)   string   C Q E

This controls which picker view that the animation item belongs to, if this flag is not specified, then current view will be used by default. A picker view id string should be specified for this flag in query, create, edit mode.

The picker view id could be retrieved by MGPicker commands such as: (Please refer to MGPicker command manual for further details.)

   // Get current script execution view id, 
   // eg. picker load command, picker mouse enter command. 

   // This is only set during the script being executed.
   MGPicker -q -currentPickerView;
   // Get current active view id.
   MGPicker -q -activePickerView;

   // Find picker view id via picker node name or picker file name and namespace.
   MGPicker -q -findPickerView  "pickerNodeOrFileName"  1 "namespace";
   // List ids of all opened picker views.
   MGPicker -q -listAllPickerViews;
   // Create a temporary picker view and return its id.
   MGPicker -e -createTempPicker;

   // Create a picker view and return its id.
   MGPicker -e -createPicker "pickerName" "namespace" "filePath" "nodeName";
   // Read in-scene picker node and return its id.
   MGPicker -e -readPickerNode "nodeName";

   // Read in-scene picker node and return its id.
   MGPicker -e -readScenePicker "nodeName" "pickerName" "namespace" "pickerDataString";
   // Read a picker file and return its id.
   MGPicker -e -readPickerFile "pickerFilePath" 1;

-value(-val)   float   C Q E

In query mode with -properties flag, it returns the values of the animated properties of all keyframes. Without -properties flag it returns values for all animated properties.

In create/edit mode it works with -properties, -time -keyframe and -easingType flag to specify the value of the keyframe to be set. If this flag is not presented when keyframing, the current property values will be used.

C Flag can appear in Create mode   E Flag can appear in Edit mode
Q Flag can appear in Query mode   M Flag can be used more than once.

MEL examples

// Make sure there is an active picker view, got at least one selection button.
$properties = {"selectButton1.X", "selectButton1.Y", "selectButton1.Width", "selectButton1.Height"};
$name = "testAnim";

$animItem = `MGPickerAnimation 
                -allProperties $properties[0] 
                -allProperties $properties[1] 
                -allProperties $properties[2] 
                -allProperties $properties[3]
                -name $name`;

// Set keyframe all properties at the frame zero using easing type linear and current values:
MGPickerAnimation -e -time 0 -keyframe -easingType "Linear" $animItem;

// Set another keyframe at frame 500msec using custom value:
$values = {160.0, 240.0, 80.0, 50.0};
for($i=0; $i<4; $i++)
{
    MGPickerAnimation -e -time 500 -properties $properties[$i] 
            -keyframe -easingType "Linear" -value $values[$i] $animItem;
}

// Now try to playback the animation by name.Note that if more then one item with the name, 
// it will only plays the first one.
MGPickerAnimation -e -playByName $name;

// Or play the animation by ID, in backward:
MGPickerAnimation -e -play -backward 1 $animItem;

Python examples

from mgpicker import mgp

# Make sure there is an active picker view, got at least one selection button.
properties = (
    "selectButton1.X",
    "selectButton1.Y",
    "selectButton1.Width",
    "selectButton1.Height",
)
name = "testAnim"
animItem = mgp.MGPickerAnimation(allProperties=properties, name=name)

# Set keyframe all properties at the frame zero using easing type linear and current values:
mgp.MGPickerAnimation(animItem, e=True, time=0, keyframe=True, easingType="Linear")

# Set another keyframe at frame 500msec using custom value:
values = (160.0, 240.0, 80.0, 50.0)
for property, value in zip(properties, values):
    mgp.MGPickerAnimation(
        animItem,
        e=True,
        time=500,
        properties=property,
        keyframe=True,
        easingType="Linear",
        value=value,
    )

# Now try to playback the animation by name.Note that if more then one item with the name,
# it will only plays the first one.
mgp.MGPickerAnimation(e=True, playByName=name)

# Or play the animation by ID, in backward:
mgp.MGPickerAnimation(animItem, e=True, playByName=name, backward=True)