Docstrings and other fixes from David Hughes

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@40225 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

wxPython/demo/ActiveX_PDFWindow.py

@@ -10,55 +10,150 @@ if wx.Platform == '__WXMSW__':
 class TestPanel(wx.Panel):
     def __init__(self, parent, log):
         wx.Panel.__init__(self, parent, -1)
-        self.pdf = None
-
-        sizer = wx.BoxSizer(wx.VERTICAL)
-        btnSizer = wx.BoxSizer(wx.HORIZONTAL)
 
+        mainsizer = wx.BoxSizer(wx.HORIZONTAL)
+        leftsizer = wx.BoxSizer(wx.VERTICAL)
         self.pdf = PDFWindow(self, style=wx.SUNKEN_BORDER)
+        leftsizer.Add(self.pdf, proportion=1, flag=wx.EXPAND)
 
-        sizer.Add(self.pdf, proportion=1, flag=wx.EXPAND)
+        box = wx.StaticBox(self, wx.NewId(), "" )
+        buttonsizer = wx.StaticBoxSizer(box, wx.HORIZONTAL )
+    
+        b1 = wx.Button(self, wx.NewId(), "First")
+        buttonsizer.Add(b1, proportion=0, flag=wx.ALIGN_CENTER|wx.ALL, border=5)
+        self.Bind(wx.EVT_BUTTON, self.OnFirstPageButton, b1)
 
-        btn = wx.Button(self, wx.NewId(), "Open PDF File")
+        b2 = wx.Button(self,  wx.NewId(), "Previous")
-        self.Bind(wx.EVT_BUTTON, self.OnOpenButton, btn)
+        buttonsizer.Add(b2, proportion=0, flag=wx.ALIGN_CENTER|wx.ALL, border=5)
-        btnSizer.Add(btn, proportion=1, flag=wx.EXPAND|wx.ALL, border=5)
+        self.Bind(wx.EVT_BUTTON, self.OnPreviousPageButton, b2)
+        
+        tx1 = wx.StaticText(self, wx.NewId(), "   Go to page" )
+        buttonsizer.Add(tx1, proportion=0, flag=wx.ALIGN_CENTER|wx.ALL, border=5)
+        tc1 = wx.TextCtrl(self, wx.NewId(), "0", size=[30,-1])
+        buttonsizer.Add( tc1, proportion=0, flag=wx.ALIGN_CENTER|wx.ALL, border=5)
+        self.Bind(wx.EVT_TEXT, self.OnGotoPage, tc1)
+    
+        b3 = wx.Button(self, wx.NewId(), "Next")
+        buttonsizer.Add(b3, proportion=0, flag=wx.ALIGN_CENTER|wx.ALL, border=5)
+        self.Bind(wx.EVT_BUTTON, self.OnNextPageButton, b3)
 
-        btn = wx.Button(self, wx.NewId(), "<-- Previous Page")
+        b4 = wx.Button(self, wx.NewId(), "Last")
-        self.Bind(wx.EVT_BUTTON, self.OnPrevPageButton, btn)
+        buttonsizer.Add(b4, proportion=0, flag=wx.ALIGN_CENTER|wx.ALL, border=5)
-        btnSizer.Add(btn, proportion=1, flag=wx.EXPAND|wx.ALL, border=5)
+        self.Bind(wx.EVT_BUTTON, self.OnLastPageButton, b4)
 
-        btn = wx.Button(self, wx.NewId(), "Next Page -->")
+        tx2 = wx.StaticText(self, wx.NewId(), "     Zoom")
-        self.Bind(wx.EVT_BUTTON, self.OnNextPageButton, btn)
+        buttonsizer.Add(tx2, proportion=0, flag=wx.ALIGN_CENTER|wx.ALL, border=5)
-        btnSizer.Add(btn, proportion=1, flag=wx.EXPAND|wx.ALL, border=5)
+ 
+        ch1 = wx.Choice(self, wx.NewId(),
+                        choices=["Default", "Fit", "FitH", "FitV",
+                                 "25%", "50%", "75%", "100%", "125%", "200%", "400%"])
+        ch1.SetSelection(0)
+        buttonsizer.Add(ch1, proportion=0, flag=wx.ALIGN_CENTER|wx.ALL, border=5)
+        self.Bind(wx.EVT_CHOICE, self.OnZoom, ch1)
 
+        leftsizer.Add(buttonsizer, proportion=0)
+        mainsizer.Add(leftsizer, proportion=1, flag=wx.GROW|wx.ALIGN_CENTER_HORIZONTAL|wx.ALL, border=5)
 
-        btnSizer.Add((50,-1), proportion=2, flag=wx.EXPAND)
+        box = wx.StaticBox(self, wx.NewId(), "" )
-        sizer.Add(btnSizer, proportion=0, flag=wx.EXPAND)
+        rightsizer = wx.StaticBoxSizer(box, wx.VERTICAL)
+    
+        b5 = wx.Button(self, wx.NewId(), "Load PDF")
+        rightsizer.Add(b5, proportion=0, flag=wx.ALIGN_CENTER_VERTICAL|wx.ALL, border=5)
+        self.Bind(wx.EVT_BUTTON, self.OnLoadButton, b5)
 
-        self.SetSizer(sizer)
+        b6 = wx.Button(self, wx.NewId(), "Print")
+        rightsizer.Add(b6, proportion=0, flag=wx.ALIGN_CENTER_VERTICAL|wx.ALL, border=5)
+        self.Bind(wx.EVT_BUTTON, self.OnPrintButton, b6)
+
+        tx3 = wx.StaticText(self, wx.NewId(), "Page mode:")
+        rightsizer.Add(tx3, proportion=0, flag=wx.ALIGN_CENTER_VERTICAL|wx.ALL, border=5)
+
+        ch2 = wx.Choice(self, wx.NewId(),size=[100,-1],
+                        choices=["None", "Bookmarks", "Thumbs"])
+        ch2.SetSelection(0)
+        rightsizer.Add(ch2, proportion=0, flag=wx.ALIGN_CENTER_VERTICAL|wx.ALL, border=5)
+        self.Bind(wx.EVT_CHOICE, self.OnPageMode, ch2)
+
+        tx4 = wx.StaticText(self, wx.NewId(), "Layout mode:")
+        rightsizer.Add(tx4, proportion=0, flag=wx.ALIGN_CENTER_VERTICAL|wx.ALL, border=5)
+
+        ch3 = wx.Choice(self, wx.NewId(),size=[100,-1],
+                        choices=["DontCare", "SinglePage",
+                                 "OneColumn", "TwoColumnLeft", "TwoColumnRight" ])
+        ch3.SetSelection(0)
+        rightsizer.Add(ch3, proportion=0, flag=wx.ALIGN_CENTER_VERTICAL|wx.ALL, border=5)
+        self.Bind(wx.EVT_CHOICE, self.OnLayoutMode, ch3)
+
+        cx1 = wx.CheckBox(self, wx.NewId(), "Toolbar")
+        cx1.SetValue( True )
+        rightsizer.Add( cx1,proportion=0, flag=wx.ALIGN_CENTER_VERTICAL|wx.ALL, border=5)
+        self.Bind(wx.EVT_CHECKBOX, self.OnToolbar, cx1)
+
+        cx2 = wx.CheckBox(self, wx.NewId(), "Scrollbars")
+        cx2.SetValue( True )
+        rightsizer.Add( cx2,proportion=0, flag=wx.ALIGN_CENTER_VERTICAL|wx.ALL, border=5)
+        self.Bind(wx.EVT_CHECKBOX, self.OnScrollbars, cx2)
+
+        mainsizer.Add( rightsizer, proportion=0, flag=wx.ALL, border=15)
+        self.SetSizer(mainsizer)
         self.SetAutoLayout(True)
 
+    def OnFirstPageButton(self, event):
+        self.pdf.gotoFirstPage()
 
-
+    def OnPreviousPageButton(self, event):
-    def OnOpenButton(self, event):
-        dlg = wx.FileDialog(self, wildcard="*.pdf")
-
-        if dlg.ShowModal() == wx.ID_OK:
-            wx.BeginBusyCursor()
-            self.pdf.LoadFile(dlg.GetPath())
-            wx.EndBusyCursor()
-
-        dlg.Destroy()
-
-
-    def OnPrevPageButton(self, event):
         self.pdf.gotoPreviousPage()
 
-
     def OnNextPageButton(self, event):
         self.pdf.gotoNextPage()
 
+    def OnLastPageButton(self, event):
+        self.pdf.gotoLastPage()
 
+    def OnGotoPage(self, event):
+        npage = event.GetEventObject().GetValue()
+        try:
+            self.pdf.setCurrentPage(int(npage))
+        except ValueError:
+            pass
+
+    def OnZoom(self, event):
+        astring = event.GetEventObject().GetStringSelection()
+        if astring.startswith('Fit'):
+            self.pdf.setView(astring)
+        else:
+            try:
+                percent = float(astring.replace('%',''))
+                self.pdf.setZoom(percent)
+            except ValueError:
+                pass
+        
+    def OnLoadButton(self, event):
+        dlg = wx.FileDialog(self, wildcard="*.pdf")
+        if dlg.ShowModal() == wx.ID_OK:
+            wx.BeginBusyCursor()
+            self.pdf.LoadFile(dlg.GetPath())
+            wx.EndBusyCursor()
+        dlg.Destroy()
+
+    def OnPrintButton(self, event):
+        self.pdf.Print()
+
+    def OnPageMode(self, event):
+        astring = event.GetEventObject().GetStringSelection()
+        self.pdf.setPageMode(astring.lower())
+
+    def OnLayoutMode(self, event):
+        astring = event.GetEventObject().GetStringSelection()
+        self.pdf.setLayoutMode(astring)
+
+    def OnToolbar(self, event):
+        on = event.GetEventObject().GetValue()
+        self.pdf.setShowToolbar(on)
+
+    def OnScrollbars(self, event):
+        on = event.GetEventObject().GetValue()
+        self.pdf.setShowScrollbars(on)
 
 #----------------------------------------------------------------------
 

wxPython/wx/lib/pdfwin.py

@@ -1,6 +1,6 @@
 #----------------------------------------------------------------------
 # Name:        wx.lib.pdfwin
-# Purpose:     A class that allows the use of the Acrobat PSF reader
+# Purpose:     A class that allows the use of the Acrobat PDF reader
 #              ActiveX control
 #
 # Author:      Robin Dunn
@@ -44,8 +44,15 @@ def get_acroversion():
 # So instead we will use Internet Explorer (via the win32com modules
 # so we can use better dynamic dispatch) and embed the Acrobat control
 # within that.  Acrobat provides the IAcroAXDocShim COM class that is
-# accessible via the IE window's Docuemnt property after a PDF file
+# accessible via the IE window's Document property after a PDF file
 # has been loaded.
+#
+# Details of the Acrobat reader methods can be found in
+# http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/iac/IACOverview.pdf
+# http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/iac/IACReference.pdf
+#
+# Co-ordinates passed as parameters are in points (1/72 inch).
+
 
 if get_acroversion() >= '7.0':
 
@@ -75,6 +82,9 @@ if get_acroversion() >= '7.0':
 
             
         def LoadFile(self, fileName):
+            """
+            Opens and displays the specified document within the browser.
+            """
             if self.ie.Document:
                 return self.ie.Document.LoadFile(fileName)
             else:
@@ -82,78 +92,129 @@ if get_acroversion() >= '7.0':
                 return True  # can we sense failure at this point?
             
         def GetVersions(self):
+            """
+            Deprecated: No longer available - do not use.
+            """
             if self.ie.Document:
                 return self.ie.Document.GetVersions()
             else:
                 raise PDFWindowError()
             
         def Print(self):
+            """
+            Prints the document according to the specified options in a user dialog box.
+            """
             if self.ie.Document:
                 return self.ie.Document.Print()
             else:
                 raise PDFWindowError()
             
         def goBackwardStack(self):
+            """
+            Goes to the previous view on the view stack, if it exists.
+            """
             if self.ie.Document:
                 return self.ie.Document.goBackwardStack()
             else:
                 raise PDFWindowError()
 
         def goForwardStack(self):
+            """
+            Goes to the next view on the view stack, if it exists.
+            """
             if self.ie.Document:
                 return self.ie.Document.goForwardStack()
             else:
                 raise PDFWindowError()
 
         def gotoFirstPage(self):
+            """
+            Goes to the first page in the document.
+            """
             if self.ie.Document:
                 return self.ie.Document.gotoFirstPage()
             else:
                 raise PDFWindowError()
 
         def gotoLastPage(self):
+            """
+            Goes to the last page in the document.
+            """
             if self.ie.Document:
                 return self.ie.Document.gotoLastPage()
             else:
                 raise PDFWindowError()
 
         def gotoNextPage(self):
+            """
+            Goes to the next page in the document, if it exists
+            """
             if self.ie.Document:
                 return self.ie.Document.gotoNextPage()
             else:
                 raise PDFWindowError()
 
         def gotoPreviousPage(self):
+            """
+            Goes to the previous page in the document, if it exists.
+            """
             if self.ie.Document:
                 return self.ie.Document.gotoPreviousPage()
             else:
                 raise PDFWindowError()
 
         def printAll(self):
+            """
+            Prints the entire document without displaying a user
+            dialog box.  The current printer, page settings, and job
+            settings are used.  This method returns immediately, even
+            if the printing has not completed.
+            """
             if self.ie.Document:
                 return self.ie.Document.printAll()
             else:
                 raise PDFWindowError()
 
         def printAllFit(self, shrinkToFit):
+            """
+            Prints the entire document without a user dialog box, and
+            (if shrinkToFit) shrinks pages as needed to fit the
+            imageable area of a page in the printer.
+            """
             if self.ie.Document:
-                return self.ie.Document.printAllFit()
+                return self.ie.Document.printAllFit(shrinkToFit)
             else:
                 raise PDFWindowError()
 
         def printPages(self, from_, to):
+            """
+            Prints the specified pages without displaying a user dialog box.
+            """
             if self.ie.Document:
-                return self.ie.Document.printPages()
+                return self.ie.Document.printPages(from_, to)
             else:
                 raise PDFWindowError()
 
         def printPagesFit(self, from_, to, shrinkToFit):
+            """
+            Prints the specified pages without displaying a user
+            dialog box, and (if shrinkToFit) shrinks pages as needed
+            to fit the imageable area of a page in the printer.
+            """
             if self.ie.Document:
-                return self.ie.Document.printPagesFit()
+                return self.ie.Document.printPagesFit( from_, to, shrinkToFit)
             else:
                 raise PDFWindowError()
 
         def printWithDialog(self):
+            """
+            Prints the document according to the specified options in
+            a user dialog box. These options may include embedded
+            printing and specifying which printer is to be used.
+            
+            NB. The page range in the dialog defaults to
+            'From Page 1 to 1' - Use Print() above instead. (dfh) 
+            """
             if self.ie.Document:
                 return self.ie.Document.printWithDialog()
             else:
@@ -161,79 +222,157 @@ if get_acroversion() >= '7.0':
 
         def setCurrentHighlight(self, a, b, c, d):
             if self.ie.Document:
-                return self.ie.Document.setCurrentHighlight()
+                return self.ie.Document.setCurrentHighlight(a, b, c, d)
             else:
                 raise PDFWindowError()
 
-        def setCurrentHightlight(self, a, b, c, d):
+        def setCurrentPage(self, npage):
+            """
+            Goes to the specified page in the document.  Maintains the
+            current location within the page and zoom level.  npage is
+            the page number of the destination page.  The first page
+            in a document is page 0.
+            
+            ## Oh no it isn't! The first page is 1 (dfh)
+            """
             if self.ie.Document:
-                return self.ie.Document.setCurrentHightlight()
+                return self.ie.Document.setCurrentPage(npage)
-            else:
-                raise PDFWindowError()
-
-        def setCurrentPage(self, n):
-            if self.ie.Document:
-                return self.ie.Document.setCurrentPage()
             else:
                 raise PDFWindowError()
 
         def setLayoutMode(self, layoutMode):
+            """
+            LayoutMode possible values:
+            
+                =================  ====================================
+                'DontCare'         use the current user preference
+                'SinglePage'       use single page mode (as in pre-Acrobat
+                                   3.0 viewers)
+                'OneColumn'        use one-column continuous mode
+                'TwoColumnLeft'    use two-column continuous mode, first
+                                   page on the left
+                'TwoColumnRight'   use two-column continuous mode, first
+                                   page on the right
+                =================  ====================================
+            """
             if self.ie.Document:
-                return self.ie.Document.setLayoutMode()
+                return self.ie.Document.setLayoutMode(layoutMode)
             else:
                 raise PDFWindowError()
 
         def setNamedDest(self, namedDest):
+            """
+            Changes the page view to the named destination in the specified string.
+            """
             if self.ie.Document:
-                return self.ie.Document.setNamedDest()
+                return self.ie.Document.setNamedDest(namedDest)
             else:
                 raise PDFWindowError()
 
         def setPageMode(self, pageMode):
+            """
+            Sets the page mode to display the document only, or to
+            additionally display bookmarks or thumbnails.  pageMode =
+            'none' or 'bookmarks' or 'thumbs'.
+            
+            ## NB.'thumbs' is case-sensitive, the other are not (dfh)
+            """   
             if self.ie.Document:
-                return self.ie.Document.setPageMode()
+                return self.ie.Document.setPageMode(pageMode)
             else:
                 raise PDFWindowError()
 
         def setShowScrollbars(self, On):
+            """
+            Determines whether scrollbars will appear in the document
+            view.
+
+            ## NB. If scrollbars are off, the navigation tools disappear as well (dfh)
+            """
             if self.ie.Document:
-                return self.ie.Document.setShowScrollbars()
+                return self.ie.Document.setShowScrollbars(On)
             else:
                 raise PDFWindowError()
 
         def setShowToolbar(self, On):
+            """
+            Determines whether a toolbar will appear in the application.
+            """
             if self.ie.Document:
-                return self.ie.Document.setShowToolbar()
+                return self.ie.Document.setShowToolbar(On)
             else:
                 raise PDFWindowError()
 
         def setView(self, viewMode):
+            """
+            Determines how the page will fit in the current view.
+            viewMode possible values:
+
+                ========  ==============================================
+                'Fit'     fits whole page within the window both vertically
+                          and horizontally.
+                'FitH'    fits the width of the page within the window.
+                'FitV'    fits the height of the page within the window.
+                'FitB'    fits bounding box within the window both vertically
+                          and horizontally.
+                'FitBH'   fits the width of the bounding box within the window.
+                'FitBV'   fits the height of the bounding box within the window.
+                ========  ==============================================
+            """
             if self.ie.Document:
-                return self.ie.Document.setView()
+                return self.ie.Document.setView(viewMode)
             else:
                 raise PDFWindowError()
 
         def setViewRect(self, left, top, width, height):
+            """
+            Sets the view rectangle according to the specified coordinates.
+
+            :param left:   The upper left horizontal coordinate.
+            :param top:    The vertical coordinate in the upper left corner.
+            :param width:  The horizontal width of the rectangle.
+            :param height: The vertical height of the rectangle.
+            """
             if self.ie.Document:
-                return self.ie.Document.setViewRect()
+                return self.ie.Document.setViewRect(left, top, width, height)
             else:
                 raise PDFWindowError()
 
         def setViewScroll(self, viewMode, offset):
+            """
+            Sets the view of a page according to the specified string.
+            Depending on the view mode, the page is either scrolled to
+            the right or scrolled down by the amount specified in
+            offset. Possible values of viewMode are as in setView
+            above. offset is the horizontal or vertical coordinate
+            positioned either at the left or top edge.
+            """    
             if self.ie.Document:
-                return self.ie.Document.setViewScroll()
+                return self.ie.Document.setViewScroll(viewMode, offset)
             else:
                 raise PDFWindowError()
 
         def setZoom(self, percent):
+            """
+            Sets the magnification according to the specified value
+            expressed as a percentage (float)
+            """
             if self.ie.Document:
-                return self.ie.Document.setZoom()
+                return self.ie.Document.setZoom(percent)
             else:
                 raise PDFWindowError()
 
         def setZoomScroll(self, percent, left, top):
+            """
+            Sets the magnification according to the specified value,
+            and scrolls the page view both horizontally and vertically
+            according to the specified amounts.
+            
+            :param left:  the horizontal coordinate positioned at the left edge.
+            :param top:   the vertical coordinate positioned at the top edge.
+            """
             if self.ie.Document:
-                return self.ie.Document.setZoomScroll()
+                return self.ie.Document.setZoomScroll(percent, left, top)
             else:
                 raise PDFWindowError()
 
@@ -359,9 +498,6 @@ else:
         def GetVersions(self):
             return self.CallAXMethod('GetVersions')
 
-        def setCurrentHightlight(self, a, b, c, d):
-            return self.CallAXMethod('setCurrentHightlight', a, b, c, d)
-
         def setCurrentHighlight(self, a, b, c, d):
             return self.CallAXMethod('setCurrentHighlight', a, b, c, d)