[jokosher-devel] [PATCH] more doc strings, api documentation

[John Kelly <kelly_worth2003 yahoo co uk>]

Hello everyone,

This patch adds more doc strings into the time files TimeLine.py,
TimeLineBar.py and TimeView.py

John

Index: TimeView.py
===================================================================
--- TimeView.py	(revision 1050)
+++ TimeView.py	(working copy)
@@ -14,12 +14,21 @@
 #=========================================================================
 
 class TimeView(gtk.EventBox):
+	"""
+	This class updates the time label which displays the time position of a loaded project.
+	"""
 
 	__gtype_name__ = 'TimeView'
 
 	#_____________________________________________________________________
 
 	def __init__(self, project):
+		"""
+		Creates a new instance of TimeView
+		
+		Parameters:
+			project -- reference to Project (Project.py)
+		"""
 		gtk.EventBox.__init__(self)
 		self.set_events(gtk.gdk.BUTTON_PRESS_MASK)
 		self.connect("button_press_event", self.OnClick)
@@ -31,7 +40,10 @@
 		
 	#_____________________________________________________________________
 		
-	def UpdateTime(self):		
+	def UpdateTime(self):
+		"""
+		This method will update the time label
+		"""		
 		transport = self.project.transport
 		formatString = "<span font_desc='Sans Bold 15'>%s</span>"
 		if transport.mode == transport.MODE_BARS_BEATS:
@@ -45,11 +57,29 @@
 	#_____________________________________________________________________
 	
 	def OnStateChanged(self, obj, change=None, *extra):
+		"""
+		This method is called when there is a change to be made
+		
+		Parameters:
+			obj -- an object to inform when this method is called.
+			change -- the change which has occured.
+			extra -- the extra parameters to be passed.
+		"""
 		self.UpdateTime()
 	
 	#_____________________________________________________________________
 
 	def OnClick(self, widget, event):
+		"""
+		This method is called when the label is double clicked
+		It will then change the time label to represent either MODE_HOURS_MINS_SECS or MODE_BARS_BEATS.
+		MODE_HOURS_MINS_SECS - time in seconds, minutes and hours.
+		MODE_BARS_BEATS - time in how many beats are in each bar.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			event -- reserved for GTK callbacks, don't use it explicitly.	
+		"""
 		if event.type == gtk.gdk._2BUTTON_PRESS:
 			transport = self.project.transport
 			if transport.mode == transport.MODE_BARS_BEATS:
Index: TimeLineBar.py
===================================================================
--- TimeLineBar.py	(revision 1050)
+++ TimeLineBar.py	(working copy)
@@ -19,7 +19,20 @@
 _=gettext.gettext
 
 class TimeLineBar(gtk.Frame):
+	"""
+	This class contains the TimeLine widget as well as the click track button and the bpm label in a gtk.Frame widget.
+	"""
+	#_____________________________________________________________________
+	
 	def __init__(self, project, projectview, mainview):
+		"""
+		Creates a new instance of TimeLineBar
+		
+		Parameters:
+			project -- reference to Project (Project.py).
+			projectview -- reference to RecordingView (RecordingView.py).
+			mainview -- reference to MainApp (JokosherApp.py).
+		"""
 		gtk.Frame.__init__(self)
 		
 		self.project = project
@@ -104,11 +117,27 @@
 	#_____________________________________________________________________
 
 	def OnAllocate(self, widget, allocation):
+		"""
+		From:
+		http://www.moeraki.com/pygtkreference/pygtk2reference/class-gtkwidget.html#signal-gtkwidget--size-allocate
+		The "size-allocate" signal is emitted when widget is given a new space allocation.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly. 
+			allocation -- reserved for GTK callbacks, don't use it explicitly.
+		"""
 		self.allocation = allocation
 
 	#_____________________________________________________________________
 	
 	def Update(self, width):
+		""" 
+		This method updates the contents TimeLineBar, updating the values in the beats per minute box and time signature box,
+		as well as updating the click button sensitivity and instrument header width.
+		
+		Parameters:
+			width -- the instrument header width.
+		"""
 		if not self.Updating:
 			instrumentviews=[]
 			if self.mainview.recording:
@@ -141,6 +170,14 @@
 	#_____________________________________________________________________
 	
 	def OnEditBPM(self, widget, event):
+		"""
+		This method is called when the user clicks the beats per minute box.
+		This method will show a spin button widget with a value inside which the user can change.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			event -- reserved for GTK callbacks, don't use it explicitly.
+		"""
 		#self.parentUpdateMethod()
 		if event.type == gtk.gdk.BUTTON_PRESS:
 			self.bpmframe.remove(self.bpmeventbox)
@@ -159,6 +196,14 @@
 	#_____________________________________________________________________
 
 	def OnEditSig(self, widget, event):
+		"""
+		This method is called when the user clicks the time signature box.
+		This method will show a text entry widget with a value inside it which the user can change.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			event -- reserved for GTK callbacks, don't use it explicitly.
+		""" 
 		#self.parentUpdateMethod()
 		if event.type == gtk.gdk.BUTTON_PRESS:
 			self.sigframe.remove(self.sigeventbox)
@@ -176,6 +221,15 @@
 	#_____________________________________________________________________
 	
 	def OnAcceptEditBPM(self, widget=None):
+		"""
+		This method is called when the user finishes editing the beats per minute box.
+		This method then updates the beats per minute value to the value the user 
+		enters and then writes that change to disk if the user saves the project. 
+		If anything but OnEditBPM calls this method, it will update the contents of the beats per minute box.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+		"""
 		if self.bpmeditPacked:
 			self.bpmframe.remove(self.bpmedit)
 			#FIXME: find a better way to do project.PrepareClick() it doesn't take a really long time with large bpm
@@ -198,6 +252,15 @@
 	#_____________________________________________________________________
 
 	def OnAcceptEditSig(self, widget=None):
+		"""
+		This method is called when the user finishes editing the time signature box.
+		This method then updates the time signature value to be the value the user 
+		enters and then writes that value to disk if the user saves the project.
+		If anything but OnEditSig calls this method, it will update the contents of the time signature box.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+		"""
 		if self.sigeditPacked:
 			self.sigframe.remove(self.sigedit)
 			sigstring = _("Please enter a correct time signature")
@@ -236,6 +299,14 @@
 	#_____________________________________________________________________
 	
 	def OnMouseMoveBPM(self, widget, event):
+		"""
+		This method is called when the mouse pointer enters or leaves the beats per minute box.
+		This method also changes the type of cursor if the mouse pointer is hovered over the beats per minute box.
+				
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			event -- reserved for GTK callbacks, don't use it explicitly.
+		"""
 		if not widget.window: 
 			return
 		if (event.type == gtk.gdk.ENTER_NOTIFY):
@@ -246,6 +317,14 @@
 	#_____________________________________________________________________
 	
 	def OnMouseMoveSig(self, widget, event):
+		"""
+		This method is called when the mouse pointer enters or leaves the time signature box.
+		This method also changes the type of cursor if the mouse pointer is hovered over the time signature box.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			event -- reserved for GTK callbacks, don't use it explicitly.
+		"""
 		if not widget.window: 
 			return
 		if (event.type == gtk.gdk.ENTER_NOTIFY):
@@ -256,6 +335,11 @@
 	#_____________________________________________________________________
 
 	def OnClick(self, widget):
+		"""
+		This method is called when the click button is clicked.
+		This method will also set the clicked button to appear pressed in if clicked.
+		If the click button is clicked while in a 'pressed in' state. It will appear as it did originally.
+		""" 
 		if widget.get_active() == True:
 			self.project.EnableClick()
 			self.clicktip.set_tip(self.clickbutton, _("Turn click track off"), None)
Index: TimeLine.py
===================================================================
--- TimeLine.py	(revision 1050)
+++ TimeLine.py	(working copy)
@@ -40,7 +40,10 @@
 
 	def __init__(self, project, timelinebar, mainview):
 		"""
-			project - reference to the active project
+		Creates a new instance of TimeLine
+		
+		Parameters:
+			project - reference to Project (Project.py)
 			timelinebar - reference of TimeLineBar (TimeLineBar.py)
 			mainview - reference to JokosherApp (JokosherApp.py) - Not used atm.
 		"""
@@ -71,9 +74,13 @@
 
 	def OnAllocate(self, widget, allocation):
 		"""
-			From:
-			http://www.moeraki.com/pygtkreference/pygtk2reference/class-gtkwidget.html#signal-gtkwidget--size-allocate
-			The "size-allocate" signal is emitted when widget is given a new space allocation.
+		From:
+		http://www.moeraki.com/pygtkreference/pygtk2reference/class-gtkwidget.html#signal-gtkwidget--size-allocate
+		The "size-allocate" signal is emitted when widget is given a new space allocation.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			allocation -- reserved for GTK callbacks, don't use it explicitly.
 		"""
 		self.allocation = allocation
 		# Reconstruce timeline because allocation changed
@@ -85,9 +92,12 @@
 		
 	def OnDraw(self, widget, event):
 		"""
-			Fires off the drawing operation.
+		This method fires off the drawing operation.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			event -- reserved for GTK callbacks, don't use it explicitly.
 		"""
-		
 		if self.savedLine == None:
 			self.DrawLine(widget)
 		if self.project.transport.RedrawTimeLine:
@@ -118,9 +128,12 @@
 		
 	def DrawLine(self, widget):
 		""" 
-			Draws the timeline and saves it to memory
-		    - Must be called initially and to redraw the timeline
-				  after moving the project start
+		This method draws the timeline and saves it to memory
+		Must be called initially and to redraw the timeline
+		after moving the project start.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
 		"""
 		d = widget.window
 
@@ -244,13 +257,19 @@
 	
 	def OnStateChanged(self, obj, change=None, *extra):
 		""" 
-			Called when there is a change of state in transport
-			manager or project. Could be one of
-			 *  Mode changed from bars/beats to minutes or vice versa
-			    (requires a complete redraw of timeline - flag set)
-			 *  Change in playing position -only needs partial redraw
-			 *  Project change e.g. a scroll or zoom change
-			    (requires a complete redraw of timeline - flag set)
+		This method is called when there is a change of state in transport
+		manager or project. 
+		Could be one of
+			*  Mode changed from bars/beats to minutes or vice versa
+			(requires a complete redraw of timeline - flag set)
+			*  Change in playing position -only needs partial redraw
+			*  Project change e.g. a scroll or zoom change
+			(requires a complete redraw of timeline - flag set)
+				
+		Parameters:
+			obj -- an object to inform when this method is called.
+			change -- the change which has occured.
+			extra -- the extra parameters to be passed.
 		"""
 		#if the timeline is not currently on screen then quit
 		if not self.window:
@@ -286,6 +305,13 @@
 	#_____________________________________________________________________
 		
 	def onMouseDown(self, widget, event):
+		"""
+		This method is called when a mouse button is clicked.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			event -- reserved for GTK callbacks, don't use it explicitly.
+		"""
 		self.buttonDown = True
 		self.dragging = False
 		self.moveHead(event.x)
@@ -294,6 +320,13 @@
 	#_____________________________________________________________________
 
 	def onMouseMove(self, widget, event):
+		"""
+		This method is called when the mouse pointer has moved.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			event -- reserved for GTK callbacks, don't use it explicitly. 
+		"""			
 		if not self.buttonDown:
 			return
 		self.dragging = True
@@ -308,6 +341,13 @@
 	#_____________________________________________________________________
 		
 	def onMouseUp(self, widget, event):
+		"""
+		This method is called when a mouse button is released.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			event -- reserved for GTK callbacks, don't use it explicitly.
+		"""
 		self.dragging = False
 		self.buttonDown = False
 		
@@ -315,7 +355,10 @@
 		
 	def moveHead(self, xpos):
 		"""
-			Changes the project position to the time matching xpos.
+		This method changes the project position to the time matching xpos.
+		
+		Parameters:
+			xpos -- the time of the new project position.
 		"""
 		pos = self.project.viewStart + xpos/ self.project.viewScale
 		self.project.transport.SeekTo(pos)
@@ -324,11 +367,13 @@
 	
 	def GetZoomFactor(self, viewScale):
 		"""
-			To be used for drawing the MODE_HOURS_MINS_SECS timeline
-			
-			Returns:
-				- an integer factor to be multiplied with the viewScale to zoom the timeline in/out
-				- a boolean indicating if milliseconds should be displayed
+		To be used for drawing the MODE_HOURS_MINS_SECS timeline.
+		
+		Parameters:
+			viewScale -- the view scale in pixels per second.
+		Returns:
+			- an integer factor to be multiplied with the viewScale to zoom the timeline in/out
+			- a boolean indicating if milliseconds should be displayed
 			The default factor is 1000, meaning that the distance between the short lines of the timeline
 			symbolizes 1000 milliseconds. The code will increase of decrease this factor to keep the
 			timeline readable. The factors can be set with the zoomLevels array. This array