made the progress bar close button optional + written some docs...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

ui/files.js

@@ -106,11 +106,36 @@ function statusNotify(prefix, loader, not_queued){
 }
 
 
-// XXX
+// Report progress status via a progress bar...
-function statusProgress(msg, tracker){
+//
+// This will connect to a tracker (Deferred) and report progress based 
+// on progress notifications on the tracker object.
+//
+// 		<msg> (5 of 500)					x
+// 		|============>----------------------|
+//
+//
+// msg is the message displayed on the progress bar.
+//
+// Two types of notification are supported:
+// 	- deferred
+// 		the .progress(..) handler will receive a deferred as a last 
+// 		argument, this will in turn do two things:
+// 			1) increment the max value of the progress bar
+// 			2) when the defered is done, increment the value of the 
+// 				progress bar
+// 	- simple
+// 		increment both max and value of the progress bar
+//
+// The progress bar will go into a "done" state if the tracker is 
+// explicitly resolved.
+//
+// NOTE: closing the progress bar will not do anything...
+function statusProgress(msg, tracker, close_button){
 	tracker = tracker == null ? $.Deferred() : null
+	close_button = close_button == null ? false : close_button
 
-	var progress = progressBar(msg)
+	var progress = progressBar(msg, null, close_button)
 	var total = 0
 	var done = 0
 

ui/ui.js

@@ -472,6 +472,8 @@ function getProgressContainer(mode, parent){
 
 // Make or get progress bar by name...
 //
+// Setting close to false will disable the close button...
+//
 // Events:
 // 	- progressUpdate (done, total)
 // 		Triggered by user to update progress bar state.
@@ -536,10 +538,14 @@ function progressBar(name, container, close, hide_timeout){
 		// progress state...
 		.append(state)
 	// the close button...
+	if(close !== false){
+		widget
 			.append($('<span class="close">&times;</span>')
 				.click(function(){
 					$(this).trigger('progressClose')
 				}))
+	}
+	widget
 		.append(bar)
 		.appendTo(container)
 		.on('progressUpdate', function(evt, done, total){
@@ -573,7 +579,11 @@ function progressBar(name, container, close, hide_timeout){
 			})
 		})
 
-	if(close != null){
+	if(close === false){
+		widget.on('progressClose', function(){
+			widget.trigger('progressDone') 
+		})
+	} else if(close != null){
 		widget.on('progressClose', close)
 	}