From e7359ac55ad8836e88b0152adfa77f327b08caaa Mon Sep 17 00:00:00 2001
From: Robin Dunn <robin@alldunn.com>
Date: Tue, 12 Jun 2012 20:56:21 +0000
Subject: [PATCH] Add extra flags and info to enable template specialization
 typdefs to be documented like a class. Use it with wxScrolledWindow and
 wxScrolledCanvas.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxPython/Phoenix/trunk@71722 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 etg/scrolwin.py          | 30 ++++++++++++++++++++++++++++--
 etgtools/extractors.py   |  2 ++
 etgtools/pi_generator.py | 33 +++++++++++++++++++++++++++------
 3 files changed, 57 insertions(+), 8 deletions(-)

diff --git a/etg/scrolwin.py b/etg/scrolwin.py
index e769fbfa..c576da43 100644
--- a/etg/scrolwin.py
+++ b/etg/scrolwin.py
@@ -72,8 +72,34 @@ def run():
         scrolled.find('SendAutoScrollEvents').isVirtual = True
         
         # The wxScrolledWindow and wxScrolledCanvas typedefs will be output
-        # normall and SIP will treat them like classes that have a wxScrolled
-        # mix-in as one of their base classes.
+        # normally and SIP will treat them like classes that have a
+        # wxScrolled mix-in as one of their base classes. Let's add some more
+        # info to them for the doc generators.
+        docBase = """\
+        The :ref:`{name}` class is a combination of the :ref:`{base}` and
+        :ref:`Scrolled` class, which manages scrolling for its client area,
+        transforming the coordinates according to the scrollbar positions,
+        and setting the scroll positions, thumb sizes and ranges according to
+        the area in view.
+        """
+        item = module.find('wxScrolledWindow')
+        assert isinstance(item, etgtools.TypedefDef)
+        item.docAsClass = True
+        item.bases = ['wxPanel', 'wxScrolled']
+        item.briefDoc = docBase.format(name='ScrolledWindow', base='Panel')
+        item.briefDoc += """
+        Since this class derives from :ref:`Panel` it shares its behavior
+        with regard to TAB traversal and focus handling. If you do not want
+        this then use :ref:`ScrolledCanvas` instead."""
+        
+        item = module.find('wxScrolledCanvas')
+        item.docAsClass = True
+        item.bases = ['wxWindow', 'wxScrolled']
+        item.briefDoc = docBase.format(name='ScrolledCanvas', base='Window')
+        item.briefDoc += """
+        This scrolled window is not intended to have children so it doesn't
+        have special handling for TAB traversal or focus management."""            
+
         
     else:
         # NOTE: We do a tricky tweak here because wxScrolled requires using
diff --git a/etgtools/extractors.py b/etgtools/extractors.py
index c4f03645..f7c3921c 100644
--- a/etgtools/extractors.py
+++ b/etgtools/extractors.py
@@ -199,6 +199,8 @@ class TypedefDef(VariableDef):
     def __init__(self, element=None, **kw):
         super(TypedefDef, self).__init__()
         self.noTypeName = False
+        self.docAsClass = False
+        self.bases = []
         self.__dict__.update(**kw)
         if element is not None:
             self.extract(element)
diff --git a/etgtools/pi_generator.py b/etgtools/pi_generator.py
index 7809318e..30eef368 100644
--- a/etgtools/pi_generator.py
+++ b/etgtools/pi_generator.py
@@ -174,20 +174,41 @@ class PiWrapperGenerator(generators.WrapperGeneratorBase):
         stream.write('%s = 0\n' % (define.pyName or define.name))
         
     #-----------------------------------------------------------------------
-    def generateTypedef(self, typedef, stream):
+    def generateTypedef(self, typedef, stream, indent=''):
         assert isinstance(typedef, extractors.TypedefDef)
         if typedef.ignored:
             return
-        # If the typedef is for a template instantiation then write a mock
-        # class for it that combines the template and class, otherwise write
-        # nothing.
-        if '<' in typedef.type and '>' in typedef.type:
+
+        # If it's not a template instantiation, or has not been flagged by
+        # the tweaker script that it should be treated as a class, then just
+        # ignore the typedef and return.
+        if not ('<' in typedef.type and '>' in typedef.type) and not typedef.docAsClass:
+            return
+        
+        # Otherwise write a mock class for it that combines the template and class.
+        # First, extract the info we need.
+        if typedef.docAsClass:
+            bases = [removeWxPrefix(b) for b in typedef.bases]
+            name = removeWxPrefix(typedef.name)
+            
+        elif '<' in typedef.type and '>' in typedef.type:
             t = typedef.type.replace('>', '')
             t = t.replace(' ', '')
             bases = t.split('<')
             bases = [removeWxPrefix(b) for b in bases]
             name = removeWxPrefix(typedef.name)
-            stream.write('class %s(%s):\n    pass\n\n' % (name, ', '.join(bases)))
+            
+        # Now write the Python equivallent class for the typedef
+        if not bases:
+            bases = ['object']  # this should not happpen, but just in case...
+        stream.write('%sclass %s(%s):\n' % (indent, name, ', '.join(bases)))
+        indent2 = indent + ' '*4
+        if typedef.briefDoc:
+            stream.write('%s"""\n' % indent2)
+            stream.write(nci(typedef.briefDoc, len(indent2)))
+            stream.write('%s"""\n' % indent2)
+        else:
+            stream.write('%spass\n\n' % indent2)
 
 
     #-----------------------------------------------------------------------