A static class which gives access to the Alias pick list.

Synopsis

#include <AlPickList.h> class AlPickList enum AlPickMaskType { kMaskUnchanged     = 0x0, kMaskTemplate     = 0x1, kMaskRoot     = 0x2, kMaskInterior    = 0x4, kMaskLeaf    = 0x8, kMaskLight    = 0x10,
kMaskCurveOnSurface     = 0x20, kMaskCamera    = 0x40, kMaskLine    = 0x80, kMaskPoint      = 0x100, kMaskEditPoint    = 0x200, kMaskParamCurve    = 0x400, kMaskUnused     = 0x800, kMaskJoint          = 0x1000, kMaskCluster        = 0x2000, kMaskSelectionHandle= 0x4000, kMaskIKHandle    = 0x8000 }; static boolean    isValid(); static AlObject*    getObject(); static AlDagNode*    getParentOfObject(); static statusCode    firstPickItem(); static statusCode    nextPickItem(); static statusCode    prevPickItem(); static statusCode    applyIteratorToItems( AlIterator*, int& ); static statusCode    applyIteratorToItems( AlIteratorWithParent*, int& ); static statusCode    clearPickList(); static statusCode    pickByName( char* ); static statusCode    pickFromScreen( Screencoord x, Screencoord y ); static statusCode    pickAreaFromScreen( Screencoord x1, Screencoord y1, Screencoord x2, Screencoord y2 ); static statusCode    pushPickList(boolean); static statusCode    popPickList(); static statusCode    setPickMask( int ); static statusCode    getPickMask( int& ); static statusCode    asynchronousPick( AlUserPickList& );

Description

This class gives access to the pick list, that is, those objects which are currently active. Note that this will include objects that are active in the MultiLister and not just those objects active in the modeling windows. Objects on the MultiLister include shaders, textures and lights.

Once an object is selected in the MultiLister, there will always be a selected object returned by the API. Also, the method clearPickList() only clears the pick list of the modeling windows. Therefore, it is possible to clear the pick list and still have one item on it. This item would be on the MultiLister. The method pickByName() will not pick an item within the MultiLister. In addition, the pick mask and pushing and popping pick routines only work for modeling windows.

boolean AlPickList::isValid()

Description

Returns TRUE if the pick list is currently pointing to something. Items will be either in the modeling windows or the MultiLister.

AlObject* AlPickList::getObject()

Description

Returns the object that the pick list is currently referencing from either the modeling windows or the MultiLister.

AlDagNode* AlPickList::getParentOfObject()

Description

Returns the parent AlDagNode of the object that the pick list is currently referencing. Note that this function will only return a valid AlDagNode* if the firstPickItem() function has been called. NULL will be returned if the picked object is in the MultiLister.

statusCode AlPickList::firstPickItem()

Description

Sets the pick list to reference the first object on the list.

Return Codes

sSuccess - there was something on the pick list

sFailure - there is nothing on the pick list

statusCode AlPickList::nextPickItem()

Description

Causes the pick list to reference the next object on the list. The next object could be on the MultiLister or in the modeling windows. Use the iterator for traversing the picklist (it is faster and does not disturb the current context of the PickList).

Return Codes

sSuccess - there was something on the pick list

sFailure - went past the end of the list

sInvalidObject - the picklist is invalid

statusCode AlPickList::prevPickItem()

Description

Causes the pick list to reference the previous object on the list. If nextPickItem() just returned sFailure, this method can be used to reference the last item on the pick list.

Return Codes

sSuccess - there was something on the pick list

sFailure - went past the end of the list

sInvalidObject - the picklist is invalid

statusCode AlPickList::applyIteratorToItems( AlIterator* iter, int& rc )

Description

Applies the given AlIterator to all elements of the pick list. The second argument will be set to the return value of the last application of the iterator’s function. See the AlIterator class for more information.

Note that this method DOES NOT modify the pick list. It also allows you to safely traverse multiple pick lists (caused by pick list pushes, and so on). The firstItem,getObject,nextItem methods are unaffected by this routine. It is possible to push a new list, and call applyIterToItems from within another applyIterToItem (which is operating on another pick list in the stack).

Arguments

< iter - the iterator to be applied to each item on the pick list

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the application of the iterator terminated normally

sFailure - the application of the iterator terminated abnormally

sInvalidArgument - the iterator was NULL.

sInvalidObject - you didn’t initialize the universe

statusCode AlPickList::applyIteratorToItems( AlIteratorWithParent *iter, int& rc )

Description

Same as above. In addition, this routine uses an iterator with a func() that has a second parameter. This parameter is the AlDagNode* parent of the picked item. The AlDagNode pointer is null for any AlObject that is a shader.

Arguments

< iter - the iterator to be applied to each item on the pick list

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the application of the iterator terminated normally

sFailure - the application of the iterator terminated abnormally

sInvalidArgument - the iterator was NULL

sInvalidObject - the universe was not initialized

statusCode AlPickList::clearPickList( void )

Description

Removes all objects from the pick list. Please see the note W.R.T. the MultiLister in the AlPickList class description.

Return Codes

sSuccess - the pick list was successfully cleared

statusCode AlPickList::pickByName( char* name )

Description

Adds all objects that match the given string pattern to the pick list. All objects in the DAG are searched and those that match the pattern are picked in a toggle manner (that is, if an object is picked already, then unpick it). If nothing in the DAG matched the pattern, then all set names are searched.

If only one set name matches, then

• if all set members are already picked, then unpick all members
• if at least one set member is not picked, then pick all members
• If more than one set name matches, then - if all members of all sets are already picked, then unpick all members - if one member of any set is not picked, then pick all members of all sets

If no objects match and no set names match the pattern, then a message is displayed to the user.

This method will not pick an item in the MultiLister.

Return Codes

sSuccess - something was successfully picked

sFailure - nothing was found that matched the string

sInvalidArgument - the given string pointer was NULL

statusCode AlPickList::pickFromScreen( Screencoord x, Screencoord y )

Description

Attempts to pick objects from the screen. Simply pass it the screen coordinates where you want picking to occur, and it will pick any appropriate objects in the window where these coordinates occur, including the SBD window. It will be necessary to do an AlUniverse::redrawScreen(kRedrawActive) to see the effects of the pick. This routine picks the objects in a 8x8 square about the point in question. Note that as would be expected, this routine fails under OpenModel.

Arguments

< x,y - the coordinates to pick from

Return Codes

> sFailure - picking could not be accomplished

< sSuccess - picking worked

statusCode AlPickList::pickAreaFromScreen( Screencoord x1, Screencoord y1, Screencoord x2, Screencoord y2 )

Description

Attempts to pick objects from the screen in the rectangle specified by (x1,y1)-(x2,y2). (x1,y1) is the lower left corner of the rectangle. Simply pass it the screen coordinates where you want picking to occur, and it will pick any appropriate objects in the window where those coordinates occur, including the SBD window. Note that as would be expected, this routine fails under OpenModel.

Arguments

< x1,y1,x2,y2 - the coordinates to pick from

Return Codes

> sFailure - picking could not be accomplished

< sSuccess - picking worked

sInvalidArgument - x2 < x1 or y2 < y1

statusCode AlPickList::pushPickList(boolean copy)

Description

It is possible to keep up to 8 picklists in memory at one time with the pick stack. Pushing and popping the stack allows picklists to be maintained while new ones are created.

The pick stack is limited to 8 levels deep. Exceeding this will cause errors to be reported to the errlog file.

Arguments

< copy - if true the stack is copied when it is pushed

Return Codes

sSuccess - the stack was successfully pushed

sFailure - the stack went too deep

sInsufficientMemory - ran out of memory pushing the stack

statusCode AlPickList::popPickList()

Description

Pops the pushed pick list. Make sure that you never pop more than you push.

Return Codes

sSuccess - the stack was successfully popped

statusCode AlPickList::setPickMask( int mask )

Description

Sets the mask used by picking routines to determine what can and cannot be picked at any given time. The mask passed in should be OR’ed together from all the object types that are valid to pick.

The mask is a bitwise OR of the following flags:

• AlPickList::kMaskUnchanged - no effect
• AlPickList::kMaskTemplate - objects in the template
• AlPickList::kMaskRoot - the root node of the DAG
• AlPickList::kMaskInterior - interior nodes in the DAG
• AlPickList::kMaskLeaf - leaf nodes in the DAG
• AlPickList::kMaskLight - lights
• AlPickList::kMaskUnused
• AlPickList::kMaskCamera - cameras
• AlPickList::kMaskLine - lines
• AlPickList::kMaskPoint - points
• AlPickList::kMaskEditPoint - edit points
• AlPickList::kMaskParamCurve - curves in UV space
• AlPickList::kMaskSkeleton - skeletons
• AlPickList::kMaskCluster - clusters
• AlPickList::kMaskHandle - handles

Arguments

mask - the bit mask to set to pick items

Return Codes

sSuccess - the operation was successful

statusCode AlPickList::getPickMask( int& mask )

Description

Gets the current pick mask and places the result in the mask parameter. This is a bitwise OR of the flags listed in the ’setPickMask’ "method."

Arguments

mask - the returned mask

Return Codes

sSuccess - the operation was successful

statusCode AlPickList::asynchronousPick( AlUserPickList& list )

Description

This method should almost NEVER be used. It is not a way to select a whole list of objects at one time. Instead it is to be used by plug-ins that launch co-operative routines such as those that would wait on the X events queue. Such routines may want to maintain a pick list separately from Alias and at times update Alias’ pick list.

For example, consider a plug-in that implements the SBD window. If the user were doing a trim operation they may choose to select from this new SBD window. If they did so, having the plug-in call AlPickable::pick() would not properly notify the Alias application that the pick list has changed. In some operations the mismatch between what Alias thinks is picked and what is currently picked could cause a segmentation fault. Instead this method should be called with all objects selected in the SBD window. The selection code will then asynchronously update the pick list. It is therefore important that the AlUserPickList be kept consistent.

In general this method allows updating of the pick list when the Alias user is in any other operation which may require them to select something. If this method is invoked when the user is not being prompted to select something, the Alias pick list will not be updated, and the AlUserPickList will not be examined until the next time Alias is in pick mode. The AlUserPickList should be a list of AlUserPickItems.

Return Codes

sSuccess - the method succeeded (always the case in OpenAlias)

sFailure - the method failed (only occurs in OpenModel)