change a few names and add better documentation

deluge/ui/webui/templates/ajax/static/js/deluge-torrent-grid.js

@@ -1,11 +1,25 @@
 /*
- * Script: deluge-torrent-grid.js
+Script: deluge-torrent-grid.js
- *  The class for controlling the main torrent grid.
+    Contains the Deluge torrent grid.
- *
- * Copyright:
- *   Damien Churchill (c) 2008 <damoxc@gmail.com>
- */
 
+License:
+    General Public License v3
+
+Copyright:
+    Damien Churchill (c) 2008 <damoxc@gmail.com>
+*/
+
+/*
+    Class: Deluge.Widgets.TorrentGrid
+        Extending Widgest.DataGrid to manage the torrents in the main
+        grid.
+
+    Example:
+        grid = new Deluge.Widgets.TorrentGrid('torrentGrid');
+
+    Returns:
+        An instance of the class wrapped about the torrent grid.
+*/
 Deluge.Widgets.TorrentGrid = new Class({
     Extends: Widgets.DataGrid,
     
@@ -31,10 +45,25 @@ Deluge.Widgets.TorrentGrid = new Class({
         'Queued': '/pixmaps/queued16.png',
         'Paused': '/pixmaps/inactive16.png',
         'Error': '/pixmaps/alert16.png',
-        'Checking': '/pixmaps/inactive16.png'
+        'Checking': '/pixmaps/checking16.png'
     },
     
-    getSelectedTorrents: function() {
+    /*
+        Property: getSelectedTorrentIds
+            Helper function to quickly return the torrent ids of the currently
+            selected torrents in the grid.
+        
+        Example:
+            var ids = '';
+            grid.getSelectedTorrentIds.each(function(id) {
+                ids += id + '\n';
+            });
+            alert(ids);
+        
+        Returns:
+            A list containing the currently selected torrent ids.
+    */
+    getSelectedTorrentIds: function() {
         var torrentIds = [];
         this.getSelected().each(function(row) {
             torrentIds.include(row.id);
@@ -42,14 +71,16 @@ Deluge.Widgets.TorrentGrid = new Class({
         return torrentIds;
     },
     
-    setTorrentFilter: function(state) {
+    /*
-        state = state.replace(' ', '');
+        Property: updateTorrents
-        this.filterer = function (r) {
+            Event handler for when a list item is clicked
-            if (r.torrent.state == state) { return true } else { return false };
-        };
-        this.render();
-    },
         
+        Arguments:
+            e - The event args
+        
+        Example:
+            listItem.addEvent('click', this.clicked.bindWithEvent(this));
+    */
     updateTorrents: function(torrents) {
         torrents.each(function(torrent, id) {
             torrent.queue = (torrent.queue > -1) ? torrent.queue + 1 : '';
@@ -77,6 +108,8 @@ Deluge.Widgets.TorrentGrid = new Class({
                 this.addRow(row, true);
             };
         }, this);
+        
+        // remove any torrents no longer in the grid.
         this.rows.each(function(row) {
             if (!torrents.has(row.id)) {
                 if (this.selectedRow && this.selectedRow.id == row.id) {

deluge/ui/webui/templates/ajax/static/js/deluge-ui.js

@@ -1,11 +1,22 @@
 /*
- * Script: deluge-ui.js
+Script: deluge-ui.js
- *  The main UI script.
+    Ties all the other scripts together to build up the Deluge AJAX UI.
- *
- * Copyright:
- *   Damien Churchill (c) 2008 <damoxc@gmail.com>
- */
 
+License:
+    General Public License v3
+
+Copyright:
+    Damien Churchill (c) 2008 <damoxc@gmail.com>
+*/
+
+/*
+    Object: Deluge.UI
+        The object that manages 
+
+    Example:
+        Deluge.Grid.initialize();
+        Deluge.Grid.run();
+*/
 Deluge.UI = {
     initialize: function() {
         this.torrents = {};
@@ -17,19 +28,28 @@ Deluge.UI = {
         else this.setTheme('classic');
         
         this.bound = {
-            updated: this.updated.bindWithEvent(this),
+            onUpdate: this.onUpdate.bindWithEvent(this),
-            resized: this.resized.bindWithEvent(this),
+            onResize: this.onResize.bindWithEvent(this),
-            toolbarClick: this.toolbarClick.bindWithEvent(this),
+            onToolbarClick: this.onToolbarClick.bindWithEvent(this),
-            filePriorities: this.filePriorities.bindWithEvent(this),
+            onFilesAction: this.onFilesAction.bindWithEvent(this),
-            filterChanged: this.filterChanged.bindWithEvent(this)
+            onFilterChanged: this.onFilterChanged.bindWithEvent(this)
         };
-        this.loadUi.delay(250, this);
+        this.loadUI.delay(250, this);
         window.addEvent('load', function(e) {
             if (this.vbox) this.vbox.calculatePositions();
         }.bindWithEvent(this));
     },
     
-    loadUi: function() {
+    /*
+        Property: loadUI
+            A method to load the UI after a delayed period of time until
+            mooui has been fixed to allow a refresh of the widgets to gather
+            the new style information.
+        
+        Example:
+            Deluge.UI.loadUI();
+    */
+    loadUI: function() {
         this.vbox = new Widgets.VBox('page', {expand: true});
         
         this.toolbar = new Deluge.Widgets.Toolbar();
@@ -62,18 +82,25 @@ Deluge.UI = {
         this.vbox.calculatePositions();
         this.details.expand()
         
-        this.toolbar.addEvent('buttonClick', this.bound.toolbarClick);
+        this.toolbar.addEvent('buttonClick', this.bound.onToolbarClick);
-        this.details.addEvent('filesAction', this.bound.filePriorities);
+        this.details.addEvent('filesAction', this.bound.onFilesAction);
-        this.labels.addEvent('filterChanged', this.bound.filterChanged);
+        this.labels.addEvent('filterChanged', this.bound.onFilterChanged);
         details.addEvent('resize', function(e) {
             this.details.expand();
         }.bindWithEvent(this));
         
-        window.addEvent('resize', this.bound.resized);
+        window.addEvent('resize', this.bound.onResize);
         Deluge.UI.update();
         this.overlay = $('overlay').dispose();
     },
     
+    /*
+        Property: initializeGrid
+            Initializes the Deluge torrent grid.
+        
+        Example:
+            Deluge.UI.initializeGrid();
+    */
     initializeGrid: function() {
         this.grid = new Deluge.Widgets.TorrentGrid('torrents')
         
@@ -100,7 +127,19 @@ Deluge.UI = {
         }.bindWithEvent(this))
     },
     
-    setTheme: function(name, fn) {
+    
+    /*
+        Property: setTheme
+            Change the theme of the AJAX UI by unloading the current stylesheet
+            and reloading a different one.
+        
+        Arguments:
+            name: the name of the theme to be switched too.
+        
+        Example:
+            Deluge.UI.setTheme('white');
+    */
+    setTheme: function(name) {
         if (this.overlay) {
             this.overlay.inject(document.body);
         }
@@ -125,12 +164,28 @@ Deluge.UI = {
         };
     },
     
+    /*
+        Property: run
+            Start the Deluge UI polling the server to get the updated torrent
+            information.
+        
+        Example:
+            Deluge.UI.run();
+    */
     run: function() {
         if (!this.running) {
             this.running = this.update.periodical(2000, this);
         }
     },
     
+    /*
+        Property: stop
+            Stop the Deluge UI polling the server to get the updated torrent
+            information.
+        
+        Example:
+            Deluge.UI.stop();
+    */
     stop: function() {
         if (this.running) {
             $clear(this.running);
@@ -138,6 +193,13 @@ Deluge.UI = {
         }
     },
     
+    /*
+        Property: update
+            The function that is called to perform the update to the UI.
+        
+        Example:
+            Deluge.UI.update();
+    */
     update: function() {
         filter = {};
         var type = this.labels.filterType, name = this.labels.filterName
@@ -145,11 +207,23 @@ Deluge.UI = {
             filter[this.labels.filterType] = this.labels.filterName;
         }
         Deluge.Client.update_ui(Deluge.Keys.Grid, filter, {
-            onSuccess: this.bound.updated
+            onSuccess: this.bound.onUpdate
         });
     },
     
-    updated: function(data) {
+    /*
+        Property: onUpdate
+            Event handler for when the update data is returned from the server.
+        
+        Arguments:
+            data - The data returned from the server
+        
+        Example:
+            Deluge.Client.update_ui(Deluge.Keys.Grid, filter, {
+                onSuccess: this.onUpdate.bindWithEvent(this)
+            });
+    */
+    onUpdate: function(data) {
         if (!$defined(data)) return;
         this.torrents = new Hash(data.torrents);
         this.stats = data.stats;
@@ -168,7 +242,17 @@ Deluge.UI = {
         this.labels.update(this.filters);
     },
     
-    filePriorities: function(event) {
+    /*
+        Property: onFilesAction
+            Event handler for when a torrents file priorities have been changed.
+        
+        Arguments:
+            e - The event args
+        
+        Example:
+            details.addEvent('filesAction', this.onFilesAction.bindWithEvent(this));
+    */
+    onFilesAction: function(event) {
         Deluge.Client.get_torrent_status(event.torrentId, ['file_priorities'], {
             onSuccess: function(result) {
                 var priorities = result.file_priorities
@@ -186,20 +270,62 @@ Deluge.UI = {
         })
     },
     
-    resized: function(event) {
+    /*
+        Property: onResize
+            Event handler for when the page is resized
+        
+        Arguments:
+            e - The event args
+        
+        Example:
+            window.addEvent('resize', this.onResize.bindWithEvent(this));
+    */
+    onResize: function(e) {
         this.vbox.calculatePositions();
     },
     
-    toolbarClick: function(event) {
+    /*
-        this.torrentAction(event.action);
+        Property: onToolbarClick
+            Event handler for when a list item is clicked
+        
+        Arguments:
+            e - The event args
+        
+        Example:
+            toolbar.addEvent('buttonClick', this.onToolbarClick.bindWithEvent(this));
+    */
+    onToolbarClick: function(e) {
+        this.torrentAction(e.action);
     },
     
-    filterChanged: function(event) {
+    /*
+        Property: onFilterChanged
+            Event handler for when a filter is changed in the sidebar.
+        
+        Arguments:
+            e - The event args
+        
+        Example:
+            labels.addEvent('filterChanged', this.onFilterChanged.bindWithEvent(this));
+    */
+    onFilterChanged: function(e) {
         this.update();
     },
     
+    /*
+        Property: torrentAction
+            Peform either a global action or and action on selected torrents
+            and then update the UI after performing the action.
+        
+        Arguments:
+            action - The action to perform
+            value - The value accompanying the action, if there is one.
+        
+        Example:
+            Deluge.UI.torrentAction('resume');
+    */
     torrentAction: function(action, value) {
-        var torrentIds = this.grid.getSelectedTorrents();
+        var torrentIds = this.grid.getSelectedTorrentIds();
         var client = Deluge.Client;
         switch (action) {
             case 'resume':