From 85e065c29d09d4d3e949e1253a571d94e3e7acc6 Mon Sep 17 00:00:00 2001 From: Damien Churchill Date: Thu, 30 Oct 2008 14:07:43 +0000 Subject: [PATCH] change a few names and add better documentation --- .../ajax/static/js/deluge-torrent-grid.js | 65 +++++-- .../templates/ajax/static/js/deluge-ui.js | 178 +++++++++++++++--- 2 files changed, 201 insertions(+), 42 deletions(-) diff --git a/deluge/ui/webui/templates/ajax/static/js/deluge-torrent-grid.js b/deluge/ui/webui/templates/ajax/static/js/deluge-torrent-grid.js index a18a50bdf..e110cc97c 100644 --- a/deluge/ui/webui/templates/ajax/static/js/deluge-torrent-grid.js +++ b/deluge/ui/webui/templates/ajax/static/js/deluge-torrent-grid.js @@ -1,11 +1,25 @@ /* - * Script: deluge-torrent-grid.js - * The class for controlling the main torrent grid. - * - * Copyright: - * Damien Churchill (c) 2008 - */ +Script: deluge-torrent-grid.js + Contains the Deluge torrent grid. +License: + General Public License v3 + +Copyright: + Damien Churchill (c) 2008 +*/ + +/* + 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(' ', ''); - this.filterer = function (r) { - if (r.torrent.state == state) { return true } else { return false }; - }; - this.render(); - }, - + /* + Property: updateTorrents + Event handler for when a list item is clicked + + 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) { diff --git a/deluge/ui/webui/templates/ajax/static/js/deluge-ui.js b/deluge/ui/webui/templates/ajax/static/js/deluge-ui.js index d55a77c7d..4d8938fab 100644 --- a/deluge/ui/webui/templates/ajax/static/js/deluge-ui.js +++ b/deluge/ui/webui/templates/ajax/static/js/deluge-ui.js @@ -1,11 +1,22 @@ /* - * Script: deluge-ui.js - * The main UI script. - * - * Copyright: - * Damien Churchill (c) 2008 - */ +Script: deluge-ui.js + Ties all the other scripts together to build up the Deluge AJAX UI. +License: + General Public License v3 + +Copyright: + Damien Churchill (c) 2008 +*/ + +/* + 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), - resized: this.resized.bindWithEvent(this), - toolbarClick: this.toolbarClick.bindWithEvent(this), - filePriorities: this.filePriorities.bindWithEvent(this), - filterChanged: this.filterChanged.bindWithEvent(this) + onUpdate: this.onUpdate.bindWithEvent(this), + onResize: this.onResize.bindWithEvent(this), + onToolbarClick: this.onToolbarClick.bindWithEvent(this), + onFilesAction: this.onFilesAction.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.details.addEvent('filesAction', this.bound.filePriorities); - this.labels.addEvent('filterChanged', this.bound.filterChanged); + this.toolbar.addEvent('buttonClick', this.bound.onToolbarClick); + this.details.addEvent('filesAction', this.bound.onFilesAction); + 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':