added more comments and fixed toolbar event handlers which went missing somehow

1 files changed, 103 insertions, 60 deletions

diff --git a/pyclic.py b/pyclic.py
index df42477..2aa8d5b 100644
--- a/pyclic.py
+++ b/pyclic.py
@@ -589,11 +589,13 @@ class PyClicAdmin:
         if response == gtk.RESPONSE_OK:
             colorsel = cdia.colorsel
             self.colour = colorsel.get_current_color()
+	    #assign the colours as values pycairo understands
             self.colorred = self.colour.red/65535.0
 	    self.colorgreen = self.colour.green/65535.0
 	    self.colorblue = self.colour.blue/65535.0
   
         cdia.destroy()
+	#queue the drawing to X
 	self.window.queue_draw()
 
     #Start the main constructor of our class, where the magic happens, kinda... not really...
@@ -602,7 +604,7 @@ class PyClicAdmin:
         # the application
         self.window = gtk.Window(gtk.WINDOW_TOPLEVEL)
 	
-	#set icon for app
+	#set icon for app (set at 48x48 pixels)
 	try:
 		self.window.set_icon_from_file("pyclicicon.png")
 	except Exception, e:
@@ -611,67 +613,82 @@ class PyClicAdmin:
 
 	#instantiate the pycliccomon class which we imported... yay... now I know what instantiate means :-)
 	self.pcc=PyClicCommon()
-
+	#add the delete_event handler to pyclic common close application method
         self.window.connect("delete_event", self.pcc.close_application)
+	#set size for window
 	self.window.set_size_request(775,544)
+	#set the window to have no border
         self.window.set_border_width(0)
 
-	self.vbox2 = gtk.VBox(False, 2)
 
 	#set an empty xml file on program start	
 	self.xml_file=None
 	
 
-	#Insert menubar containing 2 columns
+	#Insert menubar containing 2 columns, file and About or help
+	#create menu bar
 	mb = gtk.MenuBar()
+	#create file menu
 	filemenu = gtk.Menu()
-
+	#add File menu item
 	filem = gtk.MenuItem("File")
+	#add a submenu to the file menu, basically everything that shows up below file
 	filem.set_submenu(filemenu)
-
+	#An about menu suboption, linked by the activate handler to the about_program function
 	aboutm = gtk.MenuItem("About PyClicAdmin")
 	aboutm.connect("activate",self.pcc.about_program)
+	#add it to the filemenu
 	filemenu.append(aboutm)
-
+	#Create a new quiz or clear the screen. This basically deletes all the variable contents
+	#so you have a clean page. Connect it via the activate handler to the on_file_new function
 	newquiz = gtk.MenuItem("New File / Clear")
 	newquiz.connect("activate",self.on_file_new)
+	#add it to the filemenu
 	filemenu.append(newquiz)
-
-
+	#create open quiz menu item
 	openquiz = gtk.MenuItem("Open Quiz")
+	#connect the openquiz activator to on_file_open
 	openquiz.connect("activate",self.on_file_open)
+	#add openquiz to filemenu
 	filemenu.append(openquiz)
 
+	#create save option
 	save = gtk.MenuItem("Save Quiz")
+	#connect the activate handler to the save_details function
 	save.connect("activate",self.save_details)
+	#add save to the filemenu
 	filemenu.append(save)
-
+	#create exit option
 	exit = gtk.MenuItem("Exit")
+	#connect handler to integrated gtk.quit function
 	exit.connect("activate",gtk.main_quit)
+	#add exit to the filemenu
 	filemenu.append(exit)
 
-	viewmenu = gtk.Menu()
-        view = gtk.MenuItem("Options")
-        view.set_submenu(viewmenu)
-
-	open = gtk.MenuItem("Open Image")
-	open.connect("activate",self.open_image)
-	viewmenu.append(open)
-
-        stat = gtk.MenuItem("Change Color")
-        stat.connect("activate", self.on_clicked)
-        viewmenu.append(stat)
-
+	#create options submenu
+	optionsmenu = gtk.Menu()
+	#create options option
+        options = gtk.MenuItem("Options")
+	#set optionsmenu as a submenu
+        options.set_submenu(optionsmenu)
+	#create open image option
+	openimage = gtk.MenuItem("Open Image")
+	#add activate handler to open_image function
+	openimage.connect("activate",self.open_image)
+	#add open to the optionsmenu
+	optionsmenu.append(openimage)
+	#create change color option
+        colormenu = gtk.MenuItem("Change Color")
+	#add activate handler to on_clicked function
+        colormenu.connect("activate", self.on_clicked)
+	#add color option to optionsmenu
+        optionsmenu.append(colormenu)
+	#add filemenu and options to menubar
 	mb.append(filem)
-	mb.append(view)
-	self.hbox = gtk.HBox(False, 2)
-
-
-	#define and start vertical area
-	vbox = gtk.VBox(False, 2)
-	vbox.pack_start(mb,False,False,0)
+	mb.append(options)
 	
-	#Insert Toolbar with several options, and icons taken from stock library, toolbar only contains icons.
+	#Insert Toolbar with several options, and icons taken from stock library, 
+	#toolbar only contains icons. Add tooltips to iconic toolbar too.
         toolbar = gtk.Toolbar()
         toolbar.set_style(gtk.TOOLBAR_ICONS)
 
@@ -689,6 +706,7 @@ class PyClicAdmin:
         quittb = gtk.ToolButton(gtk.STOCK_QUIT)
 	quittb.set_tooltip_text("Quit the Program, C u l8r")
 
+	#place positions of toolbar options in toolbar
         toolbar.insert(newtb, 0)
         toolbar.insert(opentb, 1)
         toolbar.insert(savetb, 2)
@@ -696,36 +714,41 @@ class PyClicAdmin:
 	toolbar.insert(importtb,4)
         toolbar.insert(sep, 5)
         toolbar.insert(quittb, 6)
-        
-        
-
-        vbox.pack_start(toolbar, False, False, 0)
-
-
-        # A drawing area inside a fixed()
-
-	fix = gtk.Fixed()
 
+	#connect toolbar handlers to their functions on click
+        quittb.connect("clicked", gtk.main_quit)
+	newtb.connect("clicked", self.on_file_new)
+	opentb.connect("clicked", self.on_file_open)
+	savetb.connect("clicked", self.save_details)
+	colortb.connect("clicked", self.on_clicked)
+	importtb.connect("clicked",self.open_image)
 
+	#create a drawing area where we will place the image        
 	self.darea=gtk.DrawingArea()
-
+	#introduce a startup image called pyclic.png which gives usage instructions
 	self.image = cairo.ImageSurface.create_from_png("pyclic.png")
+	#make initial image filename pyclic.png
 	self.image_filename="pyclic.png"
+	#connect the drawing area to the expose_event handler via the expose function.
+	#Expose makes X draw everything, so one needs to call this function whenever
+	#one needs to add something new to the canvas. This is done using the queue_draw
+	#function, found in several places in this program.
 	self.darea.connect("expose_event", self.expose)
+	#create the events mask, in this case a button click
 	self.darea.set_events(gtk.gdk.BUTTON_PRESS_MASK)
+	#add another handler on button_press_event to the grab_click function which takes
+	#care of grabbing x,y coordinates
 	self.darea.connect("button_press_event",self.grab_click)
-
+	#set the drawing area size
 	self.darea.set_size_request(606,540)
-	fix.put(self.darea,0,0)
+	#define empty coordinates list
 
-	#define coordinates list
 	self.coordinates=[]
-
-	#define text entries list
+	#define empty text entries list
 	self.entry_list=[]	
-
+	#define empty labels list
 	self.label_list=[]
-
+	#define empty question list
 	self.question_list=[]
 
 	#define color values for question circle
@@ -733,28 +756,47 @@ class PyClicAdmin:
 	self.colorblue=0
 	self.colorgreen=0
 
-	# Layout
+	# Generate Layout
+	#create vertical box
+	vbox = gtk.VBox(False, 2)
+	#add the menubar to the vertical box
+	vbox.pack_start(mb,False,False,0)
+	#add toolbar to vertical box
+        vbox.pack_start(toolbar, False, False, 0)
+	#add the vertical box to the window
 	self.window.add(vbox)
+	#create a horizontal box under the menu and toolbar
+	self.hbox = gtk.HBox(False, 2)
+	#add the horizontal box to the vertical box
 	vbox.add(self.hbox)
+	#create a fixed area for the drawing area
+	fix = gtk.Fixed()
+	#add the fixed area to the horizontal box
 	self.hbox.add(fix)
+	#add the drawing area to fixed area at position 0,0, that is to say top left
+	#corner
+	fix.put(self.darea,0,0)
+	#add second vertical box
+	self.vbox2 = gtk.VBox(False, 2)
 
-	# Title and category entry boxes
+
+	# Add a title label
 	title_label=gtk.Label("Title")
 	self.vbox2.pack_start(title_label,False,False,0)
-
+	#Add a Title entry box
 	self.title_entry=gtk.Entry(max=50)
 	self.vbox2.pack_start(self.title_entry,False,False,0)
-
+	#Add an author label
 	author_label=gtk.Label("Author")
 	self.vbox2.pack_start(author_label,False,False,0)
-
+	#Add an author entry box
 	self.author_entry=gtk.Entry(max=50)
 	self.vbox2.pack_start(self.author_entry,False,False,0)
-
-	
+	#Add a Category label	
 	title_category=gtk.Label("Category")
 	self.vbox2.pack_start(title_category,False,False,0)
-
+	#Add a combobox called category to the right hand side and connect changed
+	#handler to on_changed, which captures the category selected
 	self.cb_category=gtk.combo_box_new_text()
 	self.cb_category.connect("changed", self.on_changed)
 	self.cb_category.append_text("Geography")
@@ -768,31 +810,32 @@ class PyClicAdmin:
 	self.cb_category.append_text("Art")
 	self.vbox2.pack_start(self.cb_category,False,False,0)
 
-
 	#submit button for entries
 	submit_button=gtk.Button("Submit")
 	self.vbox2.pack_start(submit_button,False,False,0)
+	#add an event handler to submit button via save_details function
 	submit_button.set_events(gtk.gdk.BUTTON_PRESS_MASK)
 	submit_button.connect("clicked",self.save_details)
-
+	#add event handler to clear button via on_file_new function
 	clear_button=gtk.Button("Clear")
 	self.vbox2.pack_start(clear_button,False,False,0)
 	clear_button.set_events(gtk.gdk.BUTTON_PRESS_MASK)
 	clear_button.connect("clicked",self.on_file_new)
-
+	#make a scrolledwindow and connect to vertical box 2
 	self.scrollw = gtk.ScrolledWindow()
 	self.scrollw.set_policy(gtk.POLICY_NEVER,gtk.POLICY_AUTOMATIC)
         self.hbox.pack_start(self.scrollw)
         self.scrollw.add_with_viewport(self.vbox2)
 
-#	self.hbox.add(self.vbox2)
-
+	#show all the showable items
 	self.window.show_all()
 
+#initiate main loop
 def main():
     gtk.main()
     return 0
 
+#instantiate pyclicadmin class
 if __name__ == "__main__":
     PyClicAdmin()
     main()