com.judah.controls

class dndList

mx.updatedcontrols.List | +--com.judah.controls.dndList

class dndList extends List
Drag and drop list class
Extended and enhanced list component based off the Macromedia List. It follows the same model as the Macromedia List and can follow the same examples. The dndList inherits all the public properties and methods of the classes it inherits including all the properties and methods of the MovieClip > UIObject class > UIComponent class > View > ScrollView > ScrollSelectList > SelectableRow > List component > List classes chain. To begin, study the List class documentation and properties and methods it inherits.
  • Example:
    This example shows to different methods how to fill the list with data.
    // load data into List
    function loadData() {
    	// method 1
    	var arr:Array = new Array();
    	arr.push({label:"File 1",data:"file"});
    	arr.push({label:"File 1",data:"file"});
    	arr.push({label:"File 3",data:"file"});
    	theList.dataProvider = arr;
    	
    	// method 2
    	theList.removeAll();
    	theList.addItem({label:".. ",data:"folder"});
    	theList.addItem({label:"Folder 1",data:"folder"});
    	theList.addItem({label:"Folder 2",data:"folder"});
    	theList.addItem({label:"File 1",data:"file"});
    	theList.addItem({label:"File 2",data:"file"});
    	theList.addItem({label:"File 3",data:"file"});
    }
    loadData()
    

Field Summary

public ADD_BRANCH: Number
Add Branch constant
public ADD_ITEM: Number
Add Item constant
public addBranchPastePosition: Number
Position to paste new branch items.
Event generated when an item is added
public addItemPastePosition: Number
Position to add new items
public canDropOnEmptyRows: Boolean
Enable drag and drop on empty rows
public className: String
Class name of the component class
public clickThreshold: Number
time in milliseconds to separate doubleclick from a delayed click
public cm: ContextMenu
Reference to the ContextMenu
public COPY_ITEM: Number
Copy Item constant
public copyIcon: MovieClip
Copy icon shown when dragging
Event generated when a item is copied
public CUT_ITEM: Number
Cut Item constant
Event generated when a item is cut
public data: Array
Default data in the items in the list
public defaultBranchItem: Object
Default branch item to use when adding a new list item
Default icon to show in the list
public defaultItem: Object
Default item to use when adding a new list item
Event generated when a row is delayed clicked
public dndEnabled: Boolean
Enables or disables drag and drop
public dndGutter: Number
The height in pixels of the gutter space inbetween list items
public dndReadOnly: Boolean
Enables all move operations to be copy operations
public doNotInsertOnDrop: Boolean
Do not insert a row on drop
Event generated when a row is double clicked
public drag_mc: MovieClip
Reference to movieclip when dragging and dropping rows
public dragDuplicateRow: Boolean
Creates an exact duplicate of the row you are dragging.
public dragHighlightAlpha: Number
Transparency amount of the highlight rectangle when dragging
public dragOnRollOut: Boolean
Start dragging when you mouse moves outside of the row
public dragOverPos: Number
Contains current or last position of dragged item
public dragRowStyle: String
The default row style of the rows in the drag mc
public DROP_EVENT: Number
Drop Event constant
public enableBranchMenuItem: Boolean
Enable branch menu item
public enabled: Boolean
Enables or disables the list
public enableDragHighlight: Boolean
Displays or hides the highlight rectangle when dragging. Deprecated
public enableDragIcon: Boolean
Displays or hides an item's icon when dragging
public enableDragLabel: Boolean
Displays or hides the item label while dragging. Deprecated
public enableDragLine: Boolean
Draws a drag line over rows
public enableGenericIcon: Boolean
Displays or hides the default generic drag icon when dragging
public enableKeySearch: Boolean
Determines if keypresses in the list find and select rows
public enableRenameItem: Boolean
Determines if an item can be renamed
public enableToolTip: Boolean
Enable tooltip
public errorMsg: String
Error message variable
public labels: Array
Default list of labels in the list
public lastMovedIndex: Number
Index of the last moved item
public lastMovedIndices: Array
Indices of the last moved list items
public lastMovedItem: Object
Reference to the last item moved
public lastMovedItems: Array
Reference to an array of the last moved list items
public lastMovedParent: Object
Parent item of the last moved item
public lastMovedParents: Array
Parent list items of the last moved list items
public lastMovedSource: Object
Owner of the last moved item
public lastMovedSources: Object
Reference to array of the owners of the last moved list items
public lastOver: Number
Absolute index of the row the mouse was last over
public lastOverIndex: Number
Relative index of the row the mouse was last over
public menu
Reference to the current ContextMenu.
public MENU_EVENT: Number
Menu Event constant
public METHOD_CALL: Number
Method Call constant
public movementBeforeDrag: Number
Number of pixels the mouse must move before we start dragging
public multipleSelection: Boolean
Enables mutiple selection of rows
public nodeIcon: MovieClip
Item icon shown when dragging
Event generated after a drag and drop
public PASTE_AFTER: Number
Paste After constant
public PASTE_BEFORE: Number
Paste Before constant
public PASTE_INTO: Number
Paste Into constant
Event generated after pasteItem method is called
public REMOVE_ITEM: Number
Remove Item constant
Event generated when an item is removed
public RENAME_ITEM: Number
Rename Item constant
public renameField: String
Name of rename label to access when using a cellrenderer
Event generated when a item is renamed
public renameTextRestrict: String
Indicates set of characters user may enter into the rename text field.
public root_mc: MovieClip
Reference to the root movieclip
public scrollDragSpeed: Number
Scroll drag speed in milliseconds
public showDebug: Boolean
Shows debug information
public showToolTipsOnAllRows: Boolean
Show tooltips on all rows
Event generated when a row is single clicked
public strAddBranch: String
Context Menu Item Add Branch string. Deprecated
public strAddItem: String
Context Menu Item Add Leaf string. Deprecated
public strCopyIcon: String
Id of icon to show when copying an item
public strCopyItem: String
Context Menu Item Copy string. Deprecated
public strCutItem: String
Context Menu Item Cut string. Deprecated
public strGenericIcon: String
Id of generic icon. Deprecated
public strNoDropIcon: String
Id of icon when dragging is not permitted
public strPasteAfter: String
Context Menu Item Paste After string. Deprecated
public strPasteBefore: String
Context Menu Item Paste Before string. Deprecated
public strPasteInto: String
Context Menu Item Paste Into string. Deprecated
Context Menu Item Remove string. Deprecated
Context Menu Item Rename string. Deprecated
static symbolName: String
The name of the ActionScript class
static symbolOwner: Object
The fully qualified class name
public targetItem: Object
Reference to the target item after drag and drop
public theCopyGridItems: Array
Reference to array of datagrid items created on cut or copy events
public theCopyItems: Array
Reference to array of items created from cut or copy events
public theCopyNodes: Array
Reference to array of items converted to tree nodes on cut or copy events
public thePasteIntoItem: Object
Parent item where list items were pasted into
public thePasteToPosition: Number
Relative index in the parent item where list items were pasted into
public toolTipDelay: Number
Tooltip delayed response in milliseconds
public toolTipDepth: Number
Tooltip depth
public trackDebug: Boolean
Track debug messages in errorMsg variable
public trashCan: MovieClip
Deprecated. Since version 2
public versionNumber: String
Current version number for this component
public visible: Boolean
Displays or hides the list

Property Summary

public copyIconX: Number (write)
Sets the X coordinate for the copy icon
public copyIconX (read)
Gets the X coordinate for the copy icon
public copyIconY: Number (write)
Sets the Y coordinate for the copy icon
public copyIconY (read)
Gets the Y coordinate for the copy icon
public enableContextMenu: Boolean (read, write)
getterEnables or disables the right-click context menu

Constructor

public dndList ( )
Constructor used when creating a new list

Method Summary

public convertToGridItem ( theItem )
Converts single list item into a datagrid item
public convertToNode ( theItem )
Converts single list item into a tree node
public copyItem ( theItems, eventSource )
A function to copy list items from the list
public cutItem ( theItems, eventSource, eventType )
A function to cut items from the list
public drawSeparator ( objPoint, row, dragOverPos, bCanDrop )
Draws separator line when dragging
public getIsBranch ( item )
Method to determine if the item is a branch
public getIsOpen ( theItem )
Method to check if item is open.
public getItemIcon ( theItem, subIcon )
Gets the icon id of the item
public getItemIndex ( theItem )
Method to get index of item in list
public getItemLabel ( theItem, subLabel )
Gets the label of the item
public getRoot ( mc )
find root movieclip
public hideToolTip ( )
Method to hide tooltip
public iconFunction ( item )
Method to dynamically set the icon of the row
public labelFunction ( item )
Method to manually set the text of the row label
public modifyDragMC ( drag_mc )
Modifies the drag movieclip before dragging
User customizable function for manipulating the context menu
public pasteItem ( theSourceItem, theTargetItem, pastePosition, moveItem, eventSource, eventConstant )
Method to insert or move list items
public permitContextMenu ( theItem, theAction, theMenuItem, theContextMenu )
A user defined function to display context menu items
public permitDropFunction ( theItem, theTargetItem, theAction )
A user defined function to allow or prevent drop
public permitRemove ( obj, menuItem, menuCaption, eventType )
Lets the user show an alert before a cut or remove event
public permitRename ( theItem )
A user defined function to allow rename on a item
removes items from copy and paste clipboard
public renameFunction ( rowIndex, eventSource )
Lets the user override the normal rename method
public setItemLabel ( theItem: Object, labelText: String, originalText: String ): String
A method to call to set the item label
public showRenameItem ( rowIndex: Number, eventSource )
Shows renaming textfield over row
public showToolTip ( )
Method to display tooltip
public toolTipFunction ( row_mc )
Method to modify tooltip movieclip directly after it has been created
public validateItemLabel ( newText: String, renameTextField: TextField ): Boolean
Validates renamed item labels

Field Documentation

cm

public var cm: ContextMenu
Reference to the ContextMenu
ContextMenu; Reference to ContextMenu. The ContextMenu class is documented in the Help Panel. You can change the context menu items easily by following the examples in the Help Panel or by following the examples provided with the component.

The contextMenu has an additional method called, "find(caption:String)" that returns the item by matching the item's caption. Each customItem in the customItems array, the array of items that make up the context menu, have an additional "action" property that contains one of the dndTree contants, PASTE_INTO, PASTER_AFTER, etc. useful for internal dndTree methods.

When you create your own context menu items add the owner property. The owner should be a reference to the component. This allows the component to work inside nested movieclips.

This is also a duplicate of the menu property. You do not want to over write the menu property with your own menu because the menu will not work in nested movieclips in Flash Player 7 and 8. Instead add or remove items from the existing menu or if you would like to use a different menu add it to the contextMenu property. This will provide the necessary behaviors to work in nested movieclips and to handle selecting the node the mouse is over (which is not always the selected node). You can always revert back to the default contextMenu by setting contextMenu to the cm property.

To change the text of any of the existing menu items use the caption property. For example, theList.cm.customItems[0].caption = "new text".

onDrop_Event

public var onDrop_Event
Event generated after a drag and drop
Event. Event generated after a drag and drop of items. This event includes three properties. Target contains a reference to the List, eventSource contains an internal constant for the DROP_EVENT and pastePosition contains the location in the target item where the paste occured (PASTE_INTO, PASTE_BEFORE, PASTE_AFTER). The onDrop event is to be used in favor of drop.
  • Example:
    The example below adds a listener to the onDrop event.
    // include delegation class
    import mx.utils.Delegate;
    // Drop Event
    function itemDrop(evt) {
    	// reference to the list
    	var theList = evt.target;
    	// references to all the items and components involved 
    	trace("pastePosition="+evt.pastePosition);
    	trace("targetItem="+evt.targetItem);
    	trace("targetIndex="+evt.targetIndex);
    	trace("thePasteToPosition="+theList.thePasteToPosition);
    	trace("thePasteToParentItem="+theList.thePasteToParentItem);
    	trace("lastMovedItem="+theList.lastMovedItem);
    	trace("lastMovedIndex="+theList.lastMovedIndex);
    	trace("lastMovedParent="+theList.lastMovedParent);
    	trace("lastMovedSource="+theList.lastMovedSource);
    	trace("lastMovedItems="+theList.lastMovedItems);
    	trace("lastMovedIndices="+theList.lastMovedIndices);
    	trace("lastMovedParents="+theList.lastMovedParents);
    	trace("lastMovedSources="+theList.lastMovedSources);
    	trace("targetItem="+theList.targetItem);
    }
    // we add a function that "listens" for the onDrop event. When an onDrop event is generated this function gets called. 
    theList.addEventListener("onDrop", Delegate.create(this, itemDrop));
    

Property Documentation


Constructor Documentation


Method Documentation

drawSeparator

public function drawSeparator (
objPoint,
row,
dragOverPos,
bCanDrop)
Draws separator line when dragging
Draws separator line when dragging. This method is provided for you to customize how the drag and drop looks to the user. Be careful not to do to many things in this function as it is run on every move and can tax the cpu. An interesting method is the row.setState method. This method highlights the row. Example code is shown below.
  • Example:
    Here is the original function you can over write
    // a lot of options are in the comments - you can uncomment to see what they do
    function drawSeparator(objPoint, row, dragOverPos, bCanDrop) {
    	//var maxWidth = 24;
    	var maxWidth = _width/2;
    	//var maxWidth = objPoint.x - 5;
    	//trace("maxWidth="+maxWidth)
    	
    	if (dragOverPos == PASTE_BEFORE) {
    		separator._visible = true;
    		if (row.state!="normal") {
    			//row.setState("normal", false);
    		}
    		separator._y = row._y;
    	}
    	else if (dragOverPos == PASTE_AFTER) {
    		separator._visible = true;
    		//row.icon_mc._alpha = 100;
    		//row.setState("normal", false);
    		//row.icon_mc.gotoAndStop(1);
    		// this unhighlights the row
    		if (row.state!="normal") {
    			//row.setState("normal", false);
    		}
    		separator._y = row._y + rowHeight;
    		//trace("_rowHeight="+rowHeight)
    		//trace("rowHeight="+rowHeight)
    	}
    	else if(dragOverPos == PASTE_INTO) {
    		//separator._visible = false;
    		// row.icon_mc._alpha = 100;
    		// this highlights the row
    		if (row.state!="highlighted") {
    			//row.setState("highlighted", false);
    		}
    		separator._y = row._y + (rowHeight/2);
    		//separator._y = objPoint.y;
    		//row.icon_mc.gotoAndStop(2);
    		// hide separator if we cannot drop
    		//if (bCanDrop) {
    		//	trace("bCanDrop = true")
    		//	separator._visible = false;
    		//}
    		//else {
    		//	separator._visible = true;
    		//}
    		//
    	}
    	separator._alpha  = 100;
    	separator._width  = maxWidth;
    	separator._height = 1;
    	separator.clear();
    	separator.lineStyle(1, 0x666666, 50);
    	separator.moveTo(0, 0);
    	separator.lineTo(width,0);
    	//separator._y = objPoint.y;
    	// we can track the depth that we are at but it doesn't look that good.
    	//separator._x = row.nodeIcon._x;
    	separator._x = 5;
    }
    

labelFunction

public function labelFunction (
item)
Method to manually set the text of the row label
Method to manually set the text of the row label. You can use this function to display the label text of the row. Normally the label text is the value of the item's "label" property. This method will allow you to display whatever text you want based on what you return. You can return undefined to show the label value. I also recommend you use this function rather than the labelField property for better control and compatibility. You must redefine the setItemLabel function if you use the dndList rename feature because the labelFunction only renders the display label. The setItemLabel converts text entered into the rename field back to the label property. If the labelFunction is concatenating the label from multiple properties then you must redefine the setItemLabel.

pasteItem

public function pasteItem (
theSourceItem,
theTargetItem,
pastePosition,
moveItem,
eventSource,
eventConstant)
Method to insert or move list items
Method to insert or move list items in the list at specific places. Please use addItem or addItemAt before using this method. A pasteItem event is generated when this method is called. The event contains the target, which is a reference to the list, the eventSource, which indicates if the method was called from the context menu, the target item and the pastePosition, which indicates the position above, below or in the target item. When items are cut, copied or removed they are copied into the dndComponent.theCopyItems, dndComponent.theCopyNodes and the dndComponent.theCopyGridItems arrays. If enableCrossDrag property is true then the cut, copied or removed items will be available to any dndComponent that also has their cross drag property enabled. When paste from the context menu this is where those items come from.

permitContextMenu

public function permitContextMenu (
theItem,
theAction,
theMenuItem,
theContextMenu)
A user defined function to display context menu items
A user defined function to show or hide context menu items on an item by item basis. This function is called when the menu is created and allows you to show or hide menu items based on the list item being passed in. Be aware that the scope changes in this function. The default value returned by this function is true meaning all menu items are shown.
  • Parameters:
    theItem
    Object - The selected item
    theAction
    Number Constant - Reference to a static event variable if one is assigned such as (PASTE_INTO, PASTE_BEFORE, PASTE_AFTER, ADD_ITEM, etc).
    theMenuItem
    ContextMenu - Reference to the context menu
    theContextMenu
    Object - Reference to custom item object
  • Returns:
    Boolean
  • Usage:
    myInstance.permitContextMenu = function(theItem,theAction,theMenuItem,theContextMenu) {};
  • Example:
    The code below is the default code in the permitContextMenu function. The code hides the "Paste Into" menu item unless the item is a branch, preventing a user from pasting the copied item into another item.
    theList.permitContextMenu = function (theItem, theAction, theMenuItem, theContextMenu) {
    	// "this" keyword does **NOT** reference the list here because we are in a different scope
    	// use the list instance name directly
    	
    	// theList.PASTE_INTO is a static variable for paste into
    	// if the action is to paste into then we allow it on branch items
    	if (theAction==theList.PASTE_INTO) {
    		// we are checking if the item we selected is a branch item
    		// if true then we show the "paste into" menu item
    		if (theList.getIsBranch(theItem)) {
    			return true;
    		}
    		else {
    			return false;
    		}
    	}
    	return true;
    }
     
    // if we define this function we can use it to let the dndList drop INTO another row
    // when a user is dragging over a row that is defined as a branch
    theList.getIsBranch = function(item){
    	var type = item.data;
    	if (type=="folder") {
    		return true;
    	}
    	return false;
    }
    

permitDropFunction

public function permitDropFunction (
theItem,
theTargetItem,
theAction)
A user defined function to allow or prevent drop
A user defined function used to prevent or allow drop. This function is also used for visual feedback when the user is dragging over rows. This default value returned by this function is true. See permissions example.
  • Parameters:
    theItem
    Object - The selected item.
    theTargetItem
    Object - The target item. The item the mouse is over.
    theAction
    Number Constant - The current drag operation. This can be PASTE_INTO, PASTE_AFTER or PASTE_BEFORE.
  • Returns:
    Boolean
  • Usage:
    myInstance.permitDropFunction = userFunctionName;
  • Example:
    The example below prevents a user from dropping into anything but a branch item.
    // add items to the list
    // we set the arbitrary fileType property for use in icon function
    theList.addItem({label:".. ",data:"green",icon:"folder",fileType:"parentFolder"});
    theList.addItem({label:"Folder 1",data:"red",icon:"folder",fileType:"folder"});
    theList.addItem({label:"Folder 2",data:"red",icon:"folder",fileType:"folder"});
    theList.addItem({label:"File 1",data:"blue",icon:"file",fileType:"file"});
    theList.addItem({label:"File 2",data:"blue",icon:"file",fileType:"file"});
    theList.addItem({label:"File 3",data:"blue",icon:"file",fileType:"file"});
     
    // the permit drop function is used when dragging and dropping
    theList.permitDropFunction = function (theSourceItem, theTargetItem, theAction) {
    	// we are in a different scope. the keyword "this" references the dndList
    	//trace("theSourceItem ="+theSourceItem.label);
    	//trace("theTargetItem ="+theTargetItem.label);
    	
    	// we are checking if the item we are dragging over is a branch item
    	// we have to define the getIsBranch method to enable dropping into an item.
    	// if true then we can paste into it. if not then no pasty
    	// we return false to prevent a drop from occuring
    	// returning false also shows the "no drop" allowed icon
    	if (this.getIsBranch(theTargetItem)) {
    		// this.PASTE_INTO is a static variable for paste into
    		// if the action is to paste into then we allow it
    		if (theAction==this.PASTE_INTO) {
    			return true;
    		}
    	}
    	// if we are not dragging into the branch we do not allow it
    	return false;
    }
     
    // define the getIsBranch function 
    theList.getIsBranch = function(item) {
    	// if the item has a property called isBranch and it is true
    	if (item.fileType=="folder") {
    		// this is branch
    		return true;
    	}
    	return false;
    }
    

permitRemove

public function permitRemove (
obj,
menuItem,
menuCaption,
eventType)
Lets the user show an alert before a cut or remove event
Lets the user show an alert before a cut or remove event. You can define this to pop up an alert prompt similar to windows explorer. Because of the nature of the Alert component we cannot get the button clicked syncronously. Therefore, we have to manually call the method we would have performed when the user clicks the OK button. See permissions example.
  • Parameters:
    obj
    Object - The list.
    menuItem
    Object - The menuItem.
    menuCaption
    String - The caption of the menu item.
    eventType
    String - The current event operation. This can be REMOVE_ITEM or CUT_ITEM.
  • Returns:
    Boolean Returns false to prevent cut or remove. Return true to continue cut or remove.
  • Usage:
    myInstance.permitRemove = functionName;
  • Example:
    The example prompts the user before removing the selected item.
    // import the alert contol - add to the library
    import mx.controls.Alert;
     
    // prompt user on remove event
    theList.permitRemove = function (theDataGrid, menuItem, menuCaption, eventType) {
    	// BE CAREFUL of SCOPE ISSUES HERE
    	var itemLabel = theList.selectedItem.label;
    	var eventName = "cut";
    	var output = "";
    	// check if this is a remove event
    	if (eventType == theList.REMOVE_ITEM) {
    		eventName = "remove";
    	}
    	
    	myClickHandler = function (evt) {
    		if (evt.detail == Alert.OK) {
    			theList.cutItem(theList.selectedItems, theList.MENU_EVENT, eventType);
    		}
    	}
    	output = "Are you sure you want to " + eventName + " " + itemLabel + "?";
    	var myAlert = Alert.show(output, "Confirm File Delete", Alert.OK | Alert.CANCEL, this, myClickHandler, "stockIcon", Alert.OK);
    	return false;
    }
    

The documentation was generated from the following file:
  • dndList.as, Last Modified: 6/16/2006 1:34:06 AM