Changeset 7899

Timestamp:

04/01/07 22:30:43 (22 months ago)

Author:

elazutkin

Message:

dnd2: everything is documented, some minor cleanup

Location:

trunk/src/dnd2

Files:

• avatar.js (modified) (3 diffs)
• container.js (modified) (7 diffs)
• manager.js (modified) (10 diffs)
• move.js (modified) (5 diffs)
• selector.js (modified) (16 diffs)
• source.js (modified) (11 diffs)

trunk/src/dnd2/avatar.js

@@ -6 +6 @@
 
 dojo.dnd2.Avatar = function(manager){
+        // summary: an object, which represents transferred DnD items visually
+        // manager: Object: a DnD manager object
         this.manager = manager;
         this.construct();
+        // calculate various offsets
+        this.offX = dojo.dnd2._getOffset(this.node, "left");
+        this.offY = dojo.dnd2._getOffset(this.node, "top");
 };
 
 dojo.dnd2._getOffset = function(node, side){
+        // summary: calculates an offset for a content box
+        // node: Node: a node
+        // side: String: a side of a box ("left", "right", "top", or "bottom")
         var h = dojo.html;
-        return h.getMarginExtent(node, side) + h.getBorderExtent(node, side) + h.getPaddingExtent(node, side);
+        return h.getMarginExtent(node, side) + h.getBorderExtent(node, side) + h.getPaddingExtent(node, side);  // Number
 };
 
 dojo.extend(dojo.dnd2.Avatar, {
         construct: function(){
+                // summary: a constructor function;
+                //      it is separate so it can be (dynamically) overwritten in case of need
                 var h = dojo.html;
                 var a = dojo.doc().createElement("table");
@@ -43 +53 @@
                 a.appendChild(b);
                 this.node = a;
-                // calculate various offsets
-                this.offX = dojo.dnd2._getOffset(a, "left");
-                this.offY = dojo.dnd2._getOffset(a, "top");
         },
         destroy: function(){
+                // summary: a desctructor for the avatar, called to remove all references so it can be garbage-collected
                 this.node.parentNode.removeChild(this.node);
                 this.node = false;
         },
         update: function(){
+                // summary: updates the avatar to reflect the current DnD state
                 dojo.html[(this.manager.canDropFlag ? "add" : "remove") + "Class"](this.node, "dojoDndAvatarCanDrop");
                 // replace text
@@ -64 +73 @@
         },
         _generateText: function(){
+                // summary: generates a proper text to reflect copying or moving of items
                 return (this.manager.copy ? "copy" : "mov") + "ing " + this.manager.nodes.length + " item" + (this.manager.nodes.length != 1 ? "s" : "");       
         }

trunk/src/dnd2/container.js

@@ -16 +16 @@
 
 dojo.declare("dojo.dnd2.Container", null, 
+        // summary: a Container object, which knows when mouse hovers over it, 
+        //      and know over which element it hovers
 function(node, params){
-        // general variables
+        // summary: a constructor of the Container
+        // node: Node: node or node's id to build the container on
+        // params: Object: a dict of parameters, recognized parameters are:
+        //      filter: Function: a filter function, which is used to filter out children of the container
+        //      creator: Function: a creator function, which takes a data item, and returns an object like that:
+        //              {node: newNode, data: usedData, types: arrayOfStrings}
         this.node = dojo.byId(node);
         this.nodeFilter  = (params && params.filter)  ? params.filter  : function(n){ return n.nodeType == 1; };
@@ -49 +56 @@
         dojo.event.connect(this.node, "onmouseout",  this, "onMouseOut");
         // cancel text selection and text dragging
-        dojo.event.connect(this.node, "ondragstart",   this, "cancelEvent");
-        dojo.event.connect(this.node, "onselectstart", this, "cancelEvent");
+        dojo.event.connect(this.node, "ondragstart",   dojo.event.browser, "stopEvent");
+        dojo.event.connect(this.node, "onselectstart", dojo.event.browser, "stopEvent");
 },
 {
         // mouse events
         onMouseOver: function(e){
+                // summary: event processor for onmouseover
+                // e: Event: mouse event
                 if(!dojo.dom.isDescendantOf(e.relatedTarget, this.node)){
-                        this.changeState("Container", "Over");
+                        this._changeState("Container", "Over");
                         this.onOverEvent();
                 }
-                var node = this.getChildByEvent(e);
+                var node = this._getChildByEvent(e);
                 if(this.current == node){ return; }
-                if(this.current){ this.removeItemClass(this.current, "Over"); }
-                if(node){ this.addItemClass(node, "Over"); }
+                if(this.current){ this._removeItemClass(this.current, "Over"); }
+                if(node){ this._addItemClass(node, "Over"); }
                 this.current = node;
         },
         onMouseOut: function(e){
+                // summary: event processor for onmouseout
+                // e: Event: mouse event
                 if(dojo.dom.isDescendantOf(e.relatedTarget, this.node)){ return; }
                 if(this.current){
-                        this.removeItemClass(this.current, "Over");
+                        this._removeItemClass(this.current, "Over");
                         this.current = null;
                 }
-                this.changeState("Container", "");
+                this._changeState("Container", "");
                 this.onOutEvent();
         },
         // methods
         getAllNodes: function(){
+                // summary: returns a list (an array) of all valid child nodes
                 var t = [];
                 var c = this.node.tagName.toLowerCase() == "table" ? this.parent.getElementsByTagName("tr") : this.node.childNodes;
@@ -84 +96 @@
                         }
                 }
-                return t;
+                return t;       // Array
         },
         insertNodes: function(data, before, anchor){
+                // summary: inserts an array of new nodes before/after an anchor node
+                // data: Array: a list of data items, which should be processed by the creator function
+                // before: Boolean: insert before the anchor, if true, and after the anchot otherwise
+                // anchor: Node: the anchor node to be used as a point of insertion
                 if(!this.parent.firstChild){
                         anchor = null;
@@ -111 +127 @@
                         }
                 }
-                return this;
+                return this;    // self
         },
         // utilities
-        onOverEvent: function(){},
-        onOutEvent: function(){},
-        cancelEvent: function(e){ dojo.event.browser.stopEvent(e); },
-        changeState: function(type, newState){
+        onOverEvent: function(){
+                // summary: this function is called once, when mouse is over our container
+        },
+        onOutEvent: function(){
+                // summary: this function is called once, when mouse is out of our container
+        },
+        _changeState: function(type, newState){
+                // summary: changes a named state to new state value
+                // type: String: a name of the state to change
+                // newState: String: new state
                 var prefix = "dojoDnd" + type;
                 var state  = type.toLowerCase() + "State";
@@ -123 +145 @@
                 this[state] = newState;
         },
-        addItemClass:    function(node, type){ dojo.html.addClass(node, "dojoDndItem" + type); },
-        removeItemClass: function(node, type){ dojo.html.removeClass(node, "dojoDndItem" + type); },
-        getChildByEvent: function(e){
+        _addItemClass: function(node, type){
+                // summary: adds a class with prefix "dojoDndItem"
+                // node: Node: a node
+                // type: String: a variable suffix for a class name
+                dojo.html.addClass(node, "dojoDndItem" + type);
+        },
+        _removeItemClass: function(node, type){
+                // summary: removes a class with prefix "dojoDndItem"
+                // node: Node: a node
+                // type: String: a variable suffix for a class name
+                dojo.html.removeClass(node, "dojoDndItem" + type);
+        },
+        _getChildByEvent: function(e){
+                // summary: gets a child, which is under the mouse at the moment
+                // e: Event: a mouse event
                 var node = e.target;
                 if(node == this.node){ return null; }
@@ -133 +167 @@
                         parent = node.parentNode;
                 }
-                return (parent && this.nodeFilter(node)) ? node : null;
+                return (parent && this.nodeFilter(node)) ? node : null; // Node
         }
 });
 
 dojo.dnd2._createNode = function(tag){
+        // summary: returns a function, which creates an element of given tag 
+        //      (SPAN by default) and sets its innerHTML to given text
+        // tag: String: a tag name or empty for SPAN
         if(!tag){ return dojo.dnd2._createSpan; }
-        return function(text){
+        return function(text){  // Function
                 var n = dojo.doc().createElement(tag);
                 n.innerHTML = text;
@@ -147 +184 @@
 
 dojo.dnd2._createTrTd = function(text){
+        // summary: creates a TR/TD structure with given text as an innerHTML of TD
+        // text: String: a text for TD
         var tr = dojo.doc().createElement("tr");
         var td = dojo.doc().createElement("td");
         td.innerHTML = text;
         tr.appendChild(td);
-        return tr;
+        return tr;      // Node
 };
 
 dojo.dnd2._createSpan = function(text){
+        // summary: creates a SPAN element with given text as its innerHTML
+        // text: String: a text for SPAN
         var n = dojo.doc().createElement("span");
         n.innerHTML = text;
-        return n;
-};
-
+        return n;       // Node
+};
+
+// dojo.dnd2._defaultCreatorNodes: Object: a dicitionary, which maps container tag names to child tag names
 dojo.dnd2._defaultCreatorNodes = {ul: "li", ol: "li", div: "div", p: "div"};
+
 dojo.dnd2._defaultCreator = function(node){
+        // summary: takes a container node, and returns an appropriate creator function
+        // node: Node: a container node
         var tag = node.tagName.toLowerCase();
         var c = tag == "table" ? dojo.dnd2._createTrTd : dojo.dnd2._createNode(dojo.dnd2._defaultCreatorNodes[tag]);
         var r = dojo.lang.repr ? dojo.lang.repr : function(o){ return o + ""; };
-        return function(data, hint){
+        return function(data, hint){    // Function
                 var t = r(data);
                 var n = (hint == "avatar" ? dojo.dnd2._createSpan : c)(t);

trunk/src/dnd2/manager.js

@@ -7 +7 @@
 
 dojo.dnd2.Manager = function(){
+        // summary: the manager of DnD operations (usually a singleton)
         this.avatar  = null;
-        
         this.source = null;
         this.nodes = [];
         this.copy  = true;
-        
         this.target = null;
         this.canDropFlag = false;
@@ -20 +19 @@
         // methods
         overSource: function(source){
+                // summary: called when a source detected a mouse-over conditiion
+                // source: Object: the reporter
                 if(this.avatar){
                         this.target = (source && source.targetState != "Disabled") ? source : null;
@@ -27 +28 @@
         },
         outSource: function(source){
+                // summary: called when a source detected a mouse-out conditiion
+                // source: Object: the reporter
                 if(this.avatar){
                         if(this.target == source){
@@ -39 +42 @@
         },
         startDrag: function(source, nodes, copy){
+                // summary: called to initiate the DnD operation
+                // source: Object: the source which provides items
+                // nodes: Array: the list of transferred items
+                // copy: Boolean: copy items, if true, move items otherwise
                 this.source = source;
                 this.nodes  = nodes;
@@ -52 +59 @@
         },
         canDrop: function(flag){
+                // summary: called to notify if the current target can accept items
                 var canDropFlag = this.target && flag;
                 if(this.canDropFlag != canDropFlag){
@@ -59 +67 @@
         },
         stopDrag: function(){
+                // summary: stop the DnD in progress
                 dojo.html.removeClass(dojo.body(), "dojoDndCopy");
                 dojo.html.removeClass(dojo.body(), "dojoDndMove");
@@ -70 +79 @@
                 this.nodes = [];
         },
-        makeAvatar: function(){ return new dojo.dnd2.Avatar(this); },
-        updateAvatar: function(){ this.avatar.update(); },
+        makeAvatar: function(){
+                // summary: makes the avatar, it is separate to be overwritten dynamically, if needed
+                return new dojo.dnd2.Avatar(this);
+        },
+        updateAvatar: function(){
+                // summary: updates the avatar, it is separate to be overwritten dynamically, if needed
+                this.avatar.update();
+        },
         // mouse event processors
         onMouseMove: function(e){
+                // summary: event processor for onmousemove
+                // e: Event: mouse event
                 var a = this.avatar;
                 if(a){
@@ -79 +96 @@
                         s.left = (e.pageX + 10 + a.offX) + "px";
                         s.top  = (e.pageY + 10 + a.offY) + "px";
-                        if(this.copy != e.ctrlKey){ this.setCopyStatus(e.ctrlKey); }
+                        if(this.copy != e.ctrlKey){ this._setCopyStatus(e.ctrlKey); }
                 }
         },
         onMouseUp: function(e){
+                // summary: event processor for onmouseup
+                // e: Event: mouse event
                 if(this.avatar){
                         if(this.target && this.canDropFlag){
@@ -94 +113 @@
         // keyboard event processors
         onKeyDown: function(e){
-                if(this.avatar && e.keyCode == dojo.event.browser.keys.KEY_CTRL && !this.copy){ this.setCopyStatus(true); }
+                // summary: event processor for onkeydown, watching for CTRL for copy/move status
+                // e: Event: keyboard event
+                if(this.avatar && e.keyCode == dojo.event.browser.keys.KEY_CTRL && !this.copy){ this._setCopyStatus(true); }
         },
         onKeyUp: function(e){
-                if(this.avatar && e.keyCode == dojo.event.browser.keys.KEY_CTRL && this.copy){ this.setCopyStatus(false); }
+                // summary: event processor for onkeyup, watching for CTRL for copy/move status
+                // e: Event: keyboard event
+                if(this.avatar && e.keyCode == dojo.event.browser.keys.KEY_CTRL && this.copy){ this._setCopyStatus(false); }
         },
         // utilities
-        setCopyStatus: function(copy){
+        _setCopyStatus: function(copy){
+                // summary: changes the copy status
+                // copy: Boolean: the copy status
                 this.copy = copy;
-                this.source.markDndStatus(this.copy);
+                this.source._markDndStatus(this.copy);
                 this.updateAvatar();
                 dojo.html.replaceClass(dojo.body(), "dojoDnd" + (this.copy ? "Copy" : "Move"), "dojoDnd" + (this.copy ? "Move" : "Copy"));
@@ -108 +133 @@
 });
 
+// summary: the manager singleton variable, can be overwritten, if needed
 dojo.dnd2._manager = null;
 
 dojo.dnd2.manager = function(){
+        // summary: returns the current DnD manager, creates one if it is not created yet
         if(!dojo.dnd2._manager){
                 dojo.dnd2._manager = new dojo.dnd2.Manager();
         }
-        return dojo.dnd2._manager;
+        return dojo.dnd2._manager;      // Object
 };

trunk/src/dnd2/move.js

@@ -5 +5 @@
 
 dojo.dnd2.Mover = function(node, e){
+        // summary: an object, which makes a node follow the mouse
+        // node: Node: a node (or node's id) to be moved
+        // e: Event: a mouse event, which started the move;
+        //      only pageX and pageY properties are used
         this.node = dojo.byId(node);
         this.mouseX = e.pageX;
@@ -10 +14 @@
         var h = dojo.html;
         this.nodePos = h.abs(this.node, true, h.boxSizing.MARGIN_BOX);
+        dojo.event.connectOnce(dojo.doc(), "onmousemove", this, "_makeAbsolute");
         dojo.event.connect(dojo.doc(), "onmousemove", this, "onMouseMove");
-        dojo.event.connect(dojo.doc(), "onmouseup",   this, "onMouseUp");
+        dojo.event.connect(dojo.doc(), "onmouseup",   this, "destroy");
         // cancel text selection and text dragging
         dojo.event.connect(dojo.doc(), "ondragstart",   dojo.event.browser, "stopEvent");
@@ -20 +25 @@
         // mouse event processors
         onMouseMove: function(e){
+                // summary: event processor for onmousemove
+                // e: Event: mouse event
                 var s = this.node.style;
-                s.position = "absolute";        // enforcing the absolute mode
                 s.left = (e.pageX - this.mouseX + this.nodePos.x) + "px";
                 s.top  = (e.pageY - this.mouseY + this.nodePos.y) + "px";
         },
-        onMouseUp: function(e){
-                this.cancel();
+        // utilities
+        _makeAbsolute: function(){
+                // summary: makes the node absolute; it is meant to be called only once
+                this.node.style.position = "absolute";  // enforcing the absolute mode
         },
-        // utilities
-        cancel: function(){
+        destroy: function(){
+                // summary: stops the move, deletes all references, so the object can be garbage-collected
+                dojo.event.disconnect(dojo.doc(), "onmousemove", this, "_makeAbsolute");
                 dojo.event.disconnect(dojo.doc(), "onmousemove", this, "onMouseMove");
                 dojo.event.disconnect(dojo.doc(), "onmouseup",   this, "onMouseUp");
@@ -38 +47 @@
 });
 
-dojo.dnd2.move = function(node, e){ return new dojo.dnd2.Mover(node, e); };
-
 dojo.dnd2.Moveable = function(node, handle){
+        // summary: an object, which makes a node moveable
+        // node: Node: a node (or node's id) to be moved
+        // handle: Node: a node (or node's id), which is used as a mouse handle;
+        //      if omitted, the node itself is used as a handle
         if(!handle){ handle = node; }
         this.node = dojo.byId(node);
@@ -54 +65 @@
         // mouse event processors
         onMouseDown: function(e){
-                dojo.dnd2.move(this.node, e);
+                // summary: event processor for onmousedown, creates a Mover for the node
+                // e: Event: mouse event
+                new dojo.dnd2.Mover(this.node, e);
                 dojo.event.browser.stopEvent(e);
         },
         // utilities
-        cancel: function(){
+        destroy: function(){
+                // summary: stops watching for possible move, deletes all references, so the object can be garbage-collected
                 dojo.event.disconnect(this.handle, "onmousedown", this, "onMouseDown");
                 dojo.event.disconnect(this.handle, "ondragstart",   dojo.event.browser, "stopEvent");

trunk/src/dnd2/selector.js

@@ -14 +14 @@
 */
 
-dojo.declare("dojo.dnd2.Selector", dojo.dnd2.Container, 
+dojo.declare("dojo.dnd2.Selector", dojo.dnd2.Container,
+        // summary: a Selector object, which knows how to select its children
 function(node, params){
-        // general variables
+        // summary: a constructor of the Selector
+        // node: Node: node or node's id to build the selector on
+        // params: Object: a dict of parameters, recognized parameters are:
+        //      singular: Boolean: allows selection of only one element, if true
+        //      the rest of parameters are passed to the container
         this.singular = params && params.singular;
         // class-specific variables
@@ -29 +34 @@
         // mouse events
         onMouseDown: function(e){
+                // summary: event processor for onmousedown
+                // e: Event: mouse event
                 if(!this.current){ return; }
                 if(!this.singular && !e.ctrlKey && !e.shiftKey && (this.current.id in this.selection)){
                         this.simpleSelection = true;
-                        this.cancelEvent(e);
+                        dojo.event.browser.stopEvent(e);
                         return;
                 }
@@ -41 +48 @@
                                         if(!(i in empty)){
                                                 var n = dojo.byId(i);
-                                                this.removeItemClass(n, "Selected");
+                                                this._removeItemClass(n, "Selected");
                                         }
                                 }
@@ -54 +61 @@
                                 }
                                 this.anchor = c[i];
-                                this.addItemClass(this.anchor, "Anchor");
+                                this._addItemClass(this.anchor, "Anchor");
                         }
                         this.selection[this.anchor.id] = 1;
@@ -68 +75 @@
                                         if(!this.nodeFilter(n)){ continue; }
                                         if(n == this.anchor || n == this.current){ break; }
-                                        this.addItemClass(n, "Selected");
+                                        this._addItemClass(n, "Selected");
                                         this.selection[n.id] = 1;
                                 }
-                                this.addItemClass(this.current, "Selected");
+                                this._addItemClass(this.current, "Selected");
                                 this.selection[this.current.id] = 1;
                         }
@@ -78 +85 @@
                                 if(this.anchor == this.current){
                                         if(e.ctrlKey){
-                                                this.removeItemClass(this.anchor, "Anchor");
+                                                this._removeItemClass(this.anchor, "Anchor");
                                                 this.anchor = null;
                                                 this.selection = {};
@@ -84 +91 @@
                                 }else{
                                         if(this.anchor){
-                                                this.removeItemClass(this.anchor, "Anchor");
+                                                this._removeItemClass(this.anchor, "Anchor");
                                         }
                                         this.anchor = this.current;
-                                        this.addItemClass(this.anchor, "Anchor");
+                                        this._addItemClass(this.anchor, "Anchor");
                                         this.selection = {};
                                         this.selection[this.current.id] = 1;
@@ -94 +101 @@
                                 if(e.ctrlKey){
                                         if(this.anchor == this.current){
-                                                this.removeItemClass(this.anchor, "Anchor");
+                                                this._removeItemClass(this.anchor, "Anchor");
                                                 delete this.selection[this.anchor.id];
                                                 this.anchor = null;
                                         }else{
                                                 if(this.current.id in this.selection){
-                                                        this.removeItemClass(this.current, "Selected");
+                                                        this._removeItemClass(this.current, "Selected");
                                                         delete this.selection[this.current.id];
                                                 }else{
@@ -106 +113 @@
                                                         }
                                                         this.anchor = this.current;
-                                                        this.addItemClass(this.current, "Anchor");
+                                                        this._addItemClass(this.current, "Anchor");
                                                         this.selection[this.current.id] = 1;
                                                 }