MGPickerView

MGPickerView is NOT undoable, queryable, and editable. Some flags are animatable.

This command queries / edits the picker document level attributes and states.

You need to specify a picker view id string in order to query / edit it, if you does not specify any id then current active picker view will be queried / edited. To retrieve a picker view id, use one of following commands:

   MGPicker -q -currentPickerView;     // Get current script execution view id, eg. picker load command, picker mouse enter command. Only be set during the script being executed.
   MGPicker -q -activePickerView;     // Get current active view id.
   MGPicker -q -findPickerView  "pickerNodeOrFileName"  1 "namespace";             // Find picker view id via picker node name or picker file name and namespace.
   MGPicker -q -listAllPickerViews;          // List ids of all opened picker views.
   MGPicker -e -createTempPicker;     // Create a temporary picker view and return its id.
   MGPicker -e -createPicker "pickerName" "namespace" "filePath" "nodeName";        // Create a picker view 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 in-scene picker node and return its id.
   MGPicker -e -readPickerFile "pickerFilePath" 1;         // Read a picker file and return its id.

Go to: [MEL Examples] [Python Examples]

Synopsis

MGPickerView( activate=boolean, autoLocaliseImages=boolean, animation=(int, string), addPanel=(string, string), activePanelIndex=int, alignSelection=unsignedint, applyStyle=(string, string, string), author=string, activateViewRegion=string, backgroundColor=(float, float, float, float), bgHorizontalAlign=string, backgroundImage=string, bgKeepRatio=boolean, bgMargin=(int, int, int, int), backgroundSVGElement=string, bgScaleFit=boolean, bgVerticalAlign=string, close=boolean, copy=string, copyAll=boolean, clearSelection=boolean, dependencies=boolean, distributeSelection=string, duplicateSelection=unsignedint, email=string, exportPathToNode=(string, string), exist=boolean, freeNavigation=boolean, fileVersion=boolean, getIdFromName=string, groupSelection=boolean, highlighted=unsignedint, inboundSelection=boolean, importFromFile=(string, string), importFromNode=(string, string), isTemp=boolean, listAnimations=boolean, localiseAllImages=boolean, listLinks=string, list=string, listViewRegions=boolean, mirrorSelection=int, message=string, namespaceChangedCommand=(string, string), namespace=string, namespaceSeparator=string, pickerDirPath=boolean, pickerEnterCommand=(string, string), pickerFilePath=boolean, pickerLoadCommand=(string, string), parentSelectionToLast=boolean, paste=string, removeAll=boolean, remove=string, saveAs=(string, boolean), saveAsSceneNode=(string, boolean), saveAsTemplate=(string, boolean), setClean=boolean, select=string, selectGroupButtons=int, selectPickerButtons=int, selectMode=int, selectPanelButtons=int, selectPanelIndexButtons=(int, unsignedint), syncPickerValue=boolean, saveToFolder=(string, boolean), saveWithinSceneFolder=boolean, tabLabel=string, ungroupSelection=boolean, unparentSelection=boolean, updateSceneBoundary=boolean, unstackSelection=(string, unsignedint), website=string, zMoveSelection=string, )

MGPickerView

-activate(-act)   Q E

In query mode, this returns if a picker view id is activated.

In Edit mode, this active a picker view by its id.

-autoLocaliseImages(-ali)   boolean   E

Used with -saveAs, -saveAsSceneNode and -saveWithinSceneFolder flags to turn on/off image localisation during the save/export.

During the image localisation, external images are copied to the relevant folder and relative path will be used.

Note that this flag only take effect during these process, it does not impact the user configuration.

-animation(-ani)   int string   E

Edit only flag to turn other edit operation into an animation.

The first argument is animation duration in millisecond, the second argument is the easing curve type of these predefined values, which can be retrieved by MGPickerAnimation -q -supportedEasingTypes

-addPanel(-ap)   string string   E

Edit only flag, specify the panel label, and the panel layout: horizontal or vertical to add a new panel to picker view. This will return the panel id string.

-activePanelIndex(-api)   int   E A

Edit only flag, specify a panel index number, and the picker view will zoom and pan itself to frame the picker panel. A panel index is the number shown in [ ] in the title area of each picker panel.

-alignSelection(-asl)   unsignedint   E

Edit only flag, align selected picker items in a certain way:

0=ParentHorizontalCenter, 1=ParentVerticalCenter, 2=HorizontalCenter, 3=VerticalCenter, 4=Left, 5=Right, 6=Top, 7=Bottom

-applyStyle(-ast)   string string string   E

Apply a style to picker scene. You need to specify:

1st string: source style, it is either the style family name(s) in default user style directory; absolute path(s) to family directory(s), or absolute to one or more .mgstyle files. Multiple input needs to be joined by the character ,.


2nd string: destination mgpicker items, it is either empty, meaning it will apply style to every item in the picker, or you can specify item IDs joined by the character ,,
e.g. itemId1,itemID2,itemID3 to apply style to these items only.


3rd string: the apply option in the format of key=0,key=1, supported values like restrictType=1,panelbackground=1, for boolean option, you can omit =1, like restrictType,panelbackground.


By default, restrictType=1, and panelbackground=0.

-author(-ath)   string   Q E

When queried, this flag returns a string of the picker author. In edit mode, specify a string to be the author of picker.

-activateViewRegion(-avr)   string   E A

Edit only flag, specify a view region name or ID, and the picker view will zoom and pan itself to frame the region. A view region can be created interactively by view region tool.

-backgroundColor(-bgc)   float float float float   Q E

The background color of the picker scene.

-bgHorizontalAlign(-bha)   string   Q E

The horizontal alignment of the background image as it is fill in the picker viewport area. Valid values are center, left, right.

The alignment only takes effect when bgScaleFit and bgKeepRatio are both on.

-backgroundImage(-bi)   string   Q E

The background image of the picker scene.

-bgKeepRatio(-bkr)   boolean   Q E

When background image scale itself to fit in the picker viewport area, if this option is on, it will keep the width/height ratio while scaling.

-bgMargin(-bmg)   int int int int   Q E

The left, right, top, bottom margin for the background image to the picker viewport area’s corresponding edge if bgScaleFit is off. When it is on, only top and left margin are used relatived to the scene origin point.

-backgroundSVGElement(-bse)   string   Q E

Query/Edit the background image element ID if it is a SVG image.

-bgScaleFit(-bsf)   boolean   Q E

Whether or not the background image should scale itself to fit in the picker viewport area. If it is off, the background image will always anchor at scene origin at its top-left corner.

-bgVerticalAlign(-bva)   string   Q E

The vertical alignment of the background image as it is fill in the picker viewport area. Valid values are center, top, bottom. The alignment only takes effect when bgScaleFit and bgKeepRatio are both on.

-close(-cl)   boolean   Q E

Close the picker view, specify a boolean value of true to force close it even if the edits are not saved.

-copy(-cp)   string   Q E M

Copy the specified picker item to clipboard for a future paste, use an empty string to copy selected items instead.

The flag supports mutli-use, so you can copy multiple items to clipboard in one go. In query mode, this returns the item IDs in the clipboard.

-copyAll(-cpa)   E

Copy all items in a picker to clipboard.

-clearSelection(-csl)   E

Deselect all picker items of the picker view.

-dependencies(-dep)   Q

Query all the external dependency files, at the moment, all the external images actually used in the picker.

-distributeSelection(-dis)   string   E

Edit only flag to evenly space out the selected picker items, with case-insensitive mode string: vertical or horizontal.

-duplicateSelection(-ds)   unsignedint   E

Edit only flag to duplicate the selected items in a certain direction or mode:

0=Right, 1=Down, 2=Up, 3=Left, 4=Mirror

The duplicated new item IDs will be returned.

-email(-eml)   string   Q E

When queried, this flag returns a string of the picker author’s email. In edit mode, specify a string to be the email address of picker.

The animator could use the email address to provide their feedback about your picker.

-exportPathToNode(-epn)   string string   E

Export picker file path to a picker node. Bascially it store a file path to a picker file, in pickerFilePath attribute in picker node.

When picker node is loaded, the picker file will be loaded instead. The file path support environment variable denoted by $ or ${}

Specify the node name to export / edit and the picker file path as arguments.

-exist(-ex)   Q

Return true or false the specify picker view id exists.

-freeNavigation(-fn)   boolean   Q E

If False, then only the positive quadrant will be seen, otherwise, the user can pan / zoom around to see other quadrants in the coordinate. By default it is False.

-fileVersion(-fv)   Q

Query only. This flag return the file version of the picker view.

-getIdFromName(-gin)   string   Q

Query only. Provided a name, return all the picker items that has the name in the picker view.

Even if there is only one match, it will still return a string array that contain only one element.

It is useful for avoiding hard-coding the id in your script, so you just use name to get the id, and do further picker item property query/edit.

-groupSelection(-gs)   E

Edit only flag to group selected picker items and return the new group id.

-highlighted(-hli)   unsignedint   Q

The query only flag to get a list of picker items match the specific highlight mode. 0 for not highlighted, 1 for semi-highlighted, 2 for fully-highlighted, 3 or larger integer for semi/fully-highlighted.

-inboundSelection(-ibs)   E

Edit only flag to move items back into the visible area of a group or picker panel. The previous picker view selection will be cleared and the moved items will be selected.

If you select groups/panels and inboundSelection, all their children will be inbound. Otherwise only selected items will be inbound.

-importFromFile(-iff)   string string   E

Edit only flag to import all content a picker file into current view.

The first string is the picker file full path, the second string is the optional group/panel ID so that items get imported as its children.

Using an empty string for the second argument to import to the scene level.

-importFromNode(-ifn)   string string   E

Edit only flag to import all content a picker node into current view.

The first string is the picker node dagPath, the second string is the optional group/panel ID so that items get imported as its children.

Using an empty string for the second argument to import to the scene level.

Note that only the picker node with the actual picker content is supported, the node only carries a picker file path is not supported.

-isTemp(-it)   Q

Query only flag. Return if the picker view is a temp picker view.

-listAnimations(-la)   Q

Query only flag. Return all animation item IDs.

-localiseAllImages(-lai)   E

Edit only flag to do image localsation. During the image localisation, external images are copied to the relevant folder and relative path will be used.

Query only flag. Return all the link IDs of a certain link type as a string array, in sourceItemId > targetItemId format;

Specify a type string as the argument, values include parentlink, attributelink (case-insensitive), you could specify empty string or parentlink|attributelink to return all types of links.

-list(-ls)   string   Q

Query only flag. Return all the picker item IDs of a certain type as a string array.

Specify a type string as the argument, values include selectButton, commandButton, attributeButton, slider, sliderHandle, text, panel (case-insensitive), a empty string will return all the picker item IDs.

The type string also support combination: say if you wanna list all select buttons and command buttons, you could use selectButton|commandButton.

-listViewRegions(-lv)   Q

Query only flag. Return all the view region IDs as a string array.

-mirrorSelection(-ms)   int   E

Utilize the mirror relationship of picker items, mirror the scene selection in one of these mode:

0 = replace selection ,1 = add selection, 2 = deselect, 3 = invert selection.

-message(-msg)   string   Q E

When queried, this flag returns a string of the picker author’s message. In edit mode, specify a string to be the message of picker.

The picker designer use this to say something to all the animators who use this picker.

-namespaceChangedCommand(-ncc)   string string   Q E

Query/edit the namespace changed command of picker file / node.

The namespace changed command will be executed after you changed the namespace of the picker view.

In query mode, this will return a string array, the first element is mel/python indicate the command type, the second element contains the actual command code.

In edit mode, specify the first argument mel/python and second argument the actual command code to edit the namespace changed command.

-namespace(-ns)   string   Q E

When queried, this flag returns the picker’s namespace. In edit mode, specify a string as the picker’s namespace.

The string should obey to namespace naming convention, any invalid characters will be converted to ‘_’.

-namespaceSeparator(-nsp)   string   Q E

When queried, this flag returns the separator characters between picker’s namespace and object base name or sub-namespace. In edit mode, specify a string as the picker’s namespace separator.

Use empty namespace to use the default namespace separator, e.g. for Maya, it is ‘:’.

-pickerDirPath(-pdp)   Q

This is a query only flag that can be used to query for the directory path name of the picker file.

-pickerEnterCommand(-pec)   string string   Q E

Query/edit the mouse enter command of picker file / node.

The enter command will be executed whenever your mouse enter the picker view.

In query mode, this will return a string array, the first element is mel/python indicate the command type, the second element contains the actual command code.

In edit mode, specify the first argument mel/python and second argument the actual command code to edit the load command.

-pickerFilePath(-pfp)   Q

This is a query only flag that can be used to query for the path name of the picker file.

-pickerLoadCommand(-plc)   string string   Q E

Query/edit the load command of picker file / node.

The load command will be executed once after the picker file / node is loaded.

In query mode, this will return a string array, the first element is mel/python indicate the command type, the second element contains the actual command code.

In edit mode, specify the first argument mel/python and second argument the actual command code to edit the load command.

-parentSelectionToLast(-psl)   E

Edit only flag to parent selected items to the last selection which must be a group or a picker panel. Return the number of items get parented to the last selected group/panel.

-paste(-pst)   string   E

Edit only flag to paste the items from clipboard to current picker scene, use empty string to paste items at scene level, specifying a panel/group ID string to paste items as children of the panel/group.

-removeAll(-ra)   E

This is a edit only flag that can be used to clear all the content of the picker.

-remove(-rm)   string   E

Edit only flag. Specify a picker item id to delete it from the view. Support multiple use in one single command.

-saveAs(-sa)   string boolean   E

This is a edit only flag that can be used to save the picker file / node to another picker name. The saved picker file will be stored within the current picker project folder in the maya’s user application directory / MG_PickerData.

Specify the target picker name and a boolean control whether or not override existed. Notice that the picker view id will stay unchanged.

-saveAsSceneNode(-sas)   string boolean   E

This is a edit only flag that can be used to save picker file / node to another picker node, specify a 0~1 boolean value to indicate the picker view should be changed to refer to the saved node.

So 0 means exporting the picker node, 1 means save current picker as the target picker node. No matter what, it always override if the node already exists.

Notice that the picker view id will stay unchanged.

-saveAsTemplate(-sat)   string boolean   E

This is a edit only flag that can be used to save picker file / node to picker template. Specify a picker template name to save to, a boolean value to control whether or not we override even the template already exist. If empty string is specified, a automatic template name will be used. Notice that the picker view id will stay unchanged.

-setClean(-sc)   E

This is a edit only flag that can be used to mark the picker view as clean, this will remove the * sign from the tab.

-select(-sel)   string   Q E M

In query mode, this returns the selected picker item IDs. Note that starting from v2.4, the button IDs returned are order in selection order, but the selected links still not in selection order.Before v2.4, both are unordered.

In edit mode it is multi-usable, this perform picker item selection via IDs, you might need to use -selectMode to cooperate with this flag.

-selectGroupButtons(-sgb)   int   E

This is a edit only flag to evaluate all the select button within a group, with select mode of:

0 = replace selection ,1 = add selection, 2 = deselect, 3 = invert selection.

This is semi-internal use, as it requires the cursor over the group, it may only work when you implement right-click context menu feature over the group.

-selectPickerButtons(-skb)   int   E

This is a edit only flag that can be used to eval all the select-buttons in picker, select their members in maya scene. This does not select related maya nodes from attribute buttons and sliders.

It is often used in the Select All command button. Use 0~3 int to specify the select mode:

0 = replace selection ,1 = add selection, 2 = deselect, 3 = invert selection.

-selectMode(-sm)   int   E

This is a edit only flag that can be used to with -select falg to select picker items in picker view. Use 0~3 int to specify the select mode:

0 = replace selection ,1 = add selection, 2 = deselect, 3 = invert selection.

-selectPanelButtons(-spb)   int   E

This is a edit only flag that can be used to evaluate all the select-buttons within picker panel, select their members in maya scene.

The command use current mouse position to decide which picker panel to eval all its children select-buttons.

It is often used in the Select All command button for picker panel. Use 0~3 int to specify the select mode:

0 = replace selection ,1 = add selection, 2 = deselect, 3 = invert selection.

This is semi-internal use, as it requires the cursor over the group, it may only work when you implement right-click context menu feature over the panel.

-selectPanelIndexButtons(-spi)   int unsignedint   E

This is a edit only flag that can be used to eval all the select-buttons within the picker panel with the panel index, select their members in maya scene. This does not select related maya nodes from attribute buttons and sliders.

It is often used in the Select * command button for picker panel. Use 0~3 int to specify the select mode:

0 = replace selection ,1 = add selection, 2 = deselect, 3 = invert selection.

You must specify a valid panel index int for the second argument.

-syncPickerValue(-spv)   E

Sync all the picker items values with maya scene, in a programming approach. eg. attr-button value, slider values.

This will validate all sync-watchers for newly created nodes or loaded referenced nodes.

Usually this is done automatically when maya attribute changed.

-saveToFolder(-stf)   string boolean   E

This is a edit only flag that can be used to save picker file / node within target directory. The saved picker file will be within target directory/pickername/ directory.

Specify a boolean to control a force override if file already exist. Notice that the picker view id will stay unchanged.

-saveWithinSceneFolder(-sws)   boolean   E

This is a edit only flag that can be used to save picker file / node to current maya scene directory / pickers folder. This directory will be auto-searched for related picker file.

Specify a boolean to control a force override if file already exist. Notice that the picker view id will stay unchanged.

-tabLabel(-tl)   string   Q E

In query mode, this return the tab label of current picker view.

In edit mode, this edit the tab label of current picker view, as well as the view’s internal picker name.

-ungroupSelection(-ugs)   E

Edit only flag to ungroup selected picker items from their parent groups or picker panels, and remove the groups or picker panels; If groups or panels are selected then they will be removed and their old children will be reparented to the group or panel’s parent. The number of group removed will be returned.

-unparentSelection(-ups)   E

Edit only flag to unparent items from their parent groups or picker panels, these group or panels will not be removed. The number of items unparented will be returned.

The selected items will be parent to scene.

-updateSceneBoundary(-usb)   E

Update the picker scene display area boundary, to show all the picker items.

You may need to use this flag in the converter, after all picker item have been created.

-unstackSelection(-uss)   string unsignedint   E

Edit only flag to unstack selected items that are overlapped with each other.

You need to specify horizontal or vertical for the direction, and unstack mode of 0=simpleMode, 1=hierarchicalMode.

-website(-www)   string   Q E

When queried, this flag returns the website of the current picker author. In edit mode, specify a string to be the website address of current picker.

The animator could visit the website to know more about the picker designer.

-zMoveSelection(-zms)   string   E

Edit only flag to send selected picker items to bottom or bring them to top. Possible argument values are top or bottom. The number of items whose zvalues were changed will be returned.

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
A Flag can animated with -animation flag.

MEL examples

// create a new picker named "myPicker"
//it is a untitled picker, not refer to a picker file / node.
string $view = `MGPicker -e -createPicker "myPicker" "wrongNamespace" "" ""`;
//edit the namespace of the picker.
MGPickerView -e -namespace "rightNamespace" $view;

//To-Do: use MGPickerItem command to created picker items.
//....
//if you does create any picker items, this picker view will be completely empty.
MGPickerView -e -author "Miguel" 
         -website "http://twincodes.com" 
         -email "mgpickerstudio@gmail.com"
         -message "Feel free to send feedback to me!" 
         $view;  //edit the meta info of the current picker file.

//update the scene boundary to show all the picker items.
MGPickerView -e -updateSceneBoundary $view;
MGPickerView -e -setClean $view;   //set the picker we just created clean.

Python examples

from mgpicker import mgp

# Create a new picker named "myPicker"
# it is a untitled picker, not refer to a picker file / node.
viewId = mgp.MGPicker(edit=True, createPicker=("myPicker", "wrongNamespace", "", ""))
# edit the namespace of the picker.
mgp.MGPickerView(viewId, edit=True, namespace="rightNamespace")

# To-Do: use MGPickerItem command to created picker items.
# ....
# if you does create any picker items, this picker view will be completely empty.
# edit the meta info of the current picker file.
mgp.MGPickerView(
    viewId,
    edit=True,
    author="Miguel",
    website="http://twincodes.com",
    email="mgpickerstudio@gmail.com",
    message="Feel free to send feedback to me!",
)
# update the scene boundary to show all the picker items.
mgp.MGPickerView(viewId, edit=True, updateSceneBoundary=True)
# set the picker we just created clean.
mgp.MGPickerView(viewId, edit=True, setClean=True)