Merge with 3.4

Lib/idlelib/SearchDialogBase.py

@@ -1,16 +1,19 @@
 '''Define SearchDialogBase used by Search, Replace, and Grep dialogs.'''
-from tkinter import *
+
+from tkinter import (Toplevel, Frame, Entry, Label, Button,
+                     Checkbutton, Radiobutton)
 
 class SearchDialogBase:
-    '''Create most of a modal search dialog (make_frame, create_widgets).
+    '''Create most of a 3 or 4 row, 3 column search dialog.
 
-    The wide left column contains:
-    1 or 2 text entry lines (create_entries, make_entry);
-    a row of standard radiobuttons (create_option_buttons);
-    a row of dialog specific radiobuttons (create_other_buttons).
+    The left and wide middle column contain:
+    1 or 2 labeled text entry lines (make_entry, create_entries);
+    a row of standard Checkbuttons (make_frame, create_option_buttons),
+    each of which corresponds to a search engine Variable;
+    a row of dialog-specific Check/Radiobuttons (create_other_buttons).
 
     The narrow right column contains command buttons
-    (create_command_buttons, make_button).
+    (make_button, create_command_buttons).
     These are bound to functions that execute the command.
 
     Except for command buttons, this base class is not limited to
@@ -19,16 +22,27 @@ class SearchDialogBase:
     The other dialogs override methods to replace and add widgets.
     '''
 
-    title = "Search Dialog"
+    title = "Search Dialog"  # replace in subclasses
     icon = "Search"
-    needwrapbutton = 1
+    needwrapbutton = 1  # not in Find in Files
 
     def __init__(self, root, engine):
+        '''Initialize root, engine, and top attributes.
+
+        top (level widget): set in create_widgets() called from open().
+        text (Text being searched): set in open(), only used in subclasses().
+        ent (ry): created in make_entry() called from create_entry().
+        row (of grid): 0 in create_widgets(), +1 in make_entry/frame().
+
+        title (of dialog): class attribute, override in subclasses.
+        icon (of dialog): ditto, use unclear if cannot minimize dialog.
+        '''
         self.root = root
         self.engine = engine
         self.top = None
 
     def open(self, text, searchphrase=None):
+        "Make dialog visible on top of others and ready to use."
         self.text = text
         if not self.top:
             self.create_widgets()
@@ -44,11 +58,17 @@ class SearchDialogBase:
         self.top.grab_set()
 
     def close(self, event=None):
+        "Put dialog away for later use."
         if self.top:
             self.top.grab_release()
             self.top.withdraw()
 
     def create_widgets(self):
+        '''Create basic 3 row x 3 col search (find) dialog.
+
+        Other dialogs override subsidiary create_x methods as needed.
+        Replace and Find-in-Files add another entry row.
+        '''
         top = Toplevel(self.root)
         top.bind("<Return>", self.default_command)
         top.bind("<Escape>", self.close)
@@ -61,12 +81,13 @@ class SearchDialogBase:
         self.top.grid_columnconfigure(0, pad=2, weight=0)
         self.top.grid_columnconfigure(1, pad=2, minsize=100, weight=100)
 
-        self.create_entries()
-        self.create_option_buttons()
-        self.create_other_buttons()
-        return self.create_command_buttons()
+        self.create_entries()  # row 0 (and maybe 1), cols 0, 1
+        self.create_option_buttons()  # next row, cols 0, 1
+        self.create_other_buttons()  # next row, cols 0, 1
+        self.create_command_buttons()  # col 2, all rows
 
     def make_entry(self, label, var):
+        "Return gridded labeled Entry."
         l = Label(self.top, text=label)
         l.grid(row=self.row, column=0, sticky="nw")
         e = Entry(self.top, textvariable=var, exportselection=0)
@@ -74,7 +95,12 @@ class SearchDialogBase:
         self.row = self.row + 1
         return e
 
+    def create_entries(self):
+        "Create one or more entry lines with make_entry."
+        self.ent = self.make_entry("Find:", self.engine.patvar)
+
     def make_frame(self,labeltext=None):
+        "Return gridded labeled Frame for option or other buttons."
         if labeltext:
             l = Label(self.top, text=labeltext)
             l.grid(row=self.row, column=0, sticky="nw")
@@ -83,19 +109,8 @@ class SearchDialogBase:
         self.row = self.row + 1
         return f
 
-    def make_button(self, label, command, isdef=0):
-        b = Button(self.buttonframe,
-                   text=label, command=command,
-                   default=isdef and "active" or "normal")
-        cols,rows=self.buttonframe.grid_size()
-        b.grid(pady=1,row=rows,column=0,sticky="ew")
-        self.buttonframe.grid(rowspan=rows+1)
-        return b
-
-    def create_entries(self):
-        self.ent = self.make_entry("Find:", self.engine.patvar)
-
     def create_option_buttons(self):
+        "Fill frame with Checkbuttons bound to SearchEngine booleanvars."
         f = self.make_frame("Options")
 
         btn = Checkbutton(f, anchor="w",
@@ -128,11 +143,9 @@ class SearchDialogBase:
                 btn.select()
 
     def create_other_buttons(self):
+        "Fill frame with buttons tied to other options."
         f = self.make_frame("Direction")
 
-        #lbl = Label(f, text="Direction: ")
-        #lbl.pack(side="left")
-
         btn = Radiobutton(f, anchor="w",
                 variable=self.engine.backvar, value=1,
                 text="Up")
@@ -147,11 +160,25 @@ class SearchDialogBase:
         if not self.engine.isback():
             btn.select()
 
+    def make_button(self, label, command, isdef=0):
+        "Return command button gridded in command frame."
+        b = Button(self.buttonframe,
+                   text=label, command=command,
+                   default=isdef and "active" or "normal")
+        cols,rows=self.buttonframe.grid_size()
+        b.grid(pady=1,row=rows,column=0,sticky="ew")
+        self.buttonframe.grid(rowspan=rows+1)
+        return b
+
     def create_command_buttons(self):
-        #
-        # place button frame on the right
+        "Place buttons in vertical command frame gridded on right."
         f = self.buttonframe = Frame(self.top)
         f.grid(row=0,column=2,padx=2,pady=2,ipadx=2,ipady=2)
 
         b = self.make_button("close", self.close)
         b.lower()
+
+if __name__ == '__main__':
+    import unittest
+    unittest.main(
+        'idlelib.idle_test.test_searchdialogbase', verbosity=2)