Lerking/Phoenix
1
0
Fork 0
mirror of https://github.com/wxWidgets/Phoenix.git synced 2026-01-04 19:10:09 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

Phoenix docs update: added support for wx.html2 and friends, converted a bunch of snippets and translated the wx.Command/wx.CommandProcessor overviews. Revised some internal links between documentation classes and overviews (again... please wx-devs stop renaming the interlinks between classes and overviews).

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxPython/Phoenix/trunk@73061 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Andrea Gavana
2012-11-29 21:18:30 +00:00
parent 79a234544a
commit cd5581f696
39 changed files with 319 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
build.py
View File

@@ -208,6 +208,9 @@ def setPythonVersion(args):
findPython = runcmd("which %s" % PYTHON, True, False)
msg('Found %s at %s' % (PYTHON, findPython))
PYTHON = findPython
## PYTHON = r"C:\Python32\python.exe"
msg(runcmd('%s -c "import sys; print(sys.version)"' % PYTHON, True, False))
PYTHON_ARCH = runcmd('%s -c "import platform; print(platform.architecture()[0])"'
% PYTHON, True, False)
@@ -915,8 +918,8 @@ def build_wx(options, args):
def build_py(options, args):
cmdTimer = CommandTimer('build_py')
#setup_py(options, args)
waf_py(options, args)
setup_py(options, args)
#waf_py(options, args)

65
docs/sphinx/rest_substitutions/overviews/command_overview.rst Normal file
View File

@@ -0,0 +1,65 @@
.. include:: headings.inc
.. _command overview:
=================================================
|phoenix_title| **Command Overview**
=================================================
:class:`Command` is a base class for modelling an application command, which is an action usually
performed by selecting a menu item, pressing a toolbar button or any other means provided by
the application to change the data or view.
Instead of the application functionality being scattered around if statements and functions in
a way that may be hard to read and maintain, the functionality for a command is explicitly represented
as an object which can be manipulated by a framework or application.
When a user interface event occurs, the application submits a command to a :class:`CommandProcessor`
object to execute and store.
The wxPython document/view framework handles Undo and Redo by use of :class:`Command` and :class:`CommandProcessor`
objects. You might find further uses for :class:`Command`, such as implementing a macro facility that
stores, loads and replays commands.
An application can derive a new class for every command, or, more likely, use one class parameterized
with an integer or string command identifier.
.. _commandprocessor overview:
=================================================
|phoenix_title| **CommandProcessor Overview**
=================================================
:class:`CommandProcessor` is a class that maintains a history of :class:`Command` instances, with
undo/redo functionality built-in. Derive a new class from this if you want different behaviour.
.. _filehistory overview:
=================================================
|phoenix_title| **FileHistory Overview**
=================================================
:class:`FileHistory` encapsulates functionality to record the last few files visited, and to allow
the user to quickly load these files using the list appended to the File menu. Although :class:`FileHistory`
is used by :class:`DocManager`, it can be used independently. You may wish to derive from it to allow
different behaviour, such as popping up a scrolling list of files.
By calling :meth:`FileHistory.UseMenu` you can associate a file menu with the file history. The menu will
then be used for appending filenames that are added to the history.
.. note::
Please notice that currently if the history already contained filenames when UseMenu() is called (e.g. when
initializing a second MDI child frame), the menu is not automatically initialized with the existing filenames
in the history and so you need to call :meth:`FileHistory.AddFilesToMenu` after UseMenu() explicitly in order
to initialize the menu with the existing list of MRU files (otherwise an assertion failure is raised in debug builds).
The filenames are appended using menu identifiers in the range ``ID_FILE1`` to ``ID_FILE9``.

1
docs/sphinx/rest_substitutions/overviews/dialog_overview.rst
View File

@@ -20,6 +20,7 @@ A dialog box is similar to a panel, in that it is a window which can be used for
.. _automatic scrolling dialogs:
.. _automatic scrolled dialogs:
Automatic scrolling dialogs
---------------------------

12
docs/sphinx/rest_substitutions/overviews/html_overview.rst
View File

@@ -127,6 +127,9 @@ image files, for HTML (or helpview) to read; and the ``".zip"`` file can
optionally be renamed to ``".htb"``.
.. _.hhp files:
.. _.hhp file:
Header file (.hhp)
~~~~~~~~~~~~~~~~~~~
@@ -219,6 +222,9 @@ Index files have same format as contents files except that ID params are
ignored and sublists are **not** allowed.
.. _input filter:
.. _input filters:
Input Filters
--------------
@@ -230,6 +236,8 @@ make a file type known to :class:`~html.HtmlWindow` you must create a :class:`~h
filter and register it using :meth:`~html.HtmlWindow.AddFilter`.
.. _cells and containers:
Cells and Containers
---------------------
@@ -257,6 +265,7 @@ containers:
.. image:: _static/images/overviews/overview_html_contbox.png
:alt: overview_html_contbox.png
:align: center
@@ -277,6 +286,7 @@ parent container. See explanation:
.. image:: _static/images/overviews/overview_html_cont.png
:alt: overview_html_cont.png
:align: center
There clearly must be same number of calls to OpenContainer as to CloseContainer.
@@ -323,6 +333,8 @@ body).
directly.
.. _tag handlers:
Tag Handlers
-------------

6
docs/sphinx/rest_substitutions/overviews/index.rst
View File

@@ -142,6 +142,7 @@ The new wxPython API documentation is available `in this page <main.html>`_.
app_overview
bitmap_overview
bookctrl_overview
command_overview
common_dialogs_overview
config_overview
dataobject_overview
@@ -176,6 +177,11 @@ The new wxPython API documentation is available `in this page <main.html>`_.
adv.1classindex
adv.functions
dataview.1classindex
glcanvas.1classindex
html.1classindex
html.functions
html2.1classindex
stc.1classindex
lib
py
tools

1
docs/sphinx/rest_substitutions/overviews/log_classes_overview.rst
View File

@@ -2,6 +2,7 @@
.. _log classes overview:
.. _logging overview:
===============================================
|phoenix_title| **Log Classes Overview**

2
docs/sphinx/rest_substitutions/snippets/python/converted/AppConsole.SetCLocale.1.py Normal file
View File

@@ -0,0 +1,2 @@
setlocale(LC_ALL, "")

2
docs/sphinx/rest_substitutions/snippets/python/converted/Bitmap.NewFromPNGData.2.py Normal file
View File

@@ -0,0 +1,2 @@
wx.Image.AddHandler(wx.PNGHandler)

9
docs/sphinx/rest_substitutions/snippets/python/converted/Control.GetSizeFromTextSize.1.py Normal file
View File

@@ -0,0 +1,9 @@
# Create a control for post code entry.
postcode = wx.TextCtrl(self, -1, "")
# And set its initial and minimal size to be big enough for
# entering 5 digits.
postcode.SetInitialSize(
postcode.GetSizeFromTextSize(
postcode.GetTextExtent("99999")))

9
docs/sphinx/rest_substitutions/snippets/python/converted/Control.GetSizeFromTextSize.2.py Normal file
View File

@@ -0,0 +1,9 @@
# Create a control for post code entry.
postcode = wx.TextCtrl(self, -1, "")
# And set its initial and minimal size to be big enough for
# entering 5 digits.
postcode.SetInitialSize(
postcode.GetSizeFromTextSize(
postcode.GetTextExtent("99999")))

13
docs/sphinx/rest_substitutions/snippets/python/converted/RichMessageDialog.1.py Normal file
View File

@@ -0,0 +1,13 @@
def ShowDialog(self):
if dont_show:
return
dlg = wx.RichMessageDialog(self, "Welcome to my wonderful program!")
dlg.ShowCheckBox("Don't show welcome dialog again")
dlg.ShowModal() # return value ignored as we have "Ok" only anyhow
if dlg.IsCheckBoxChecked():
# ... make sure we won't show it again the next time ...
dont_show = True

6
docs/sphinx/rest_substitutions/snippets/python/converted/dataview.DataViewCustomRenderer.CreateEditorCtrl.1.py Normal file
View File

@@ -0,0 +1,6 @@
# Some integer...
l = value
return wx.SpinCtrl(parent, wx.ID_ANY, "",
labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l)

6
docs/sphinx/rest_substitutions/snippets/python/converted/dataview.DataViewCustomRenderer.GetValueFromEditorCtrl.1.py Normal file
View File

@@ -0,0 +1,6 @@
# sc is a wx.SpinCtrl
l = sc.GetValue()
value = l
return True

11
docs/sphinx/rest_substitutions/snippets/python/converted/dataview.DataViewListCtrl.1.py Normal file
View File

@@ -0,0 +1,11 @@
listctrl = wx.dataview.DataViewListCtrl(parent, wx.ID_ANY)
listctrl.AppendToggleColumn("Toggle")
listctrl.AppendTextColumn("Text")
data = [True, "row 1"]
listctrl.AppendItem(data)
data = [False, "row 3"]
listctrl.AppendItem(data)

4
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlCell.AdjustPagebreak.1.py Normal file
View File

@@ -0,0 +1,4 @@
ret_value, kp = container.AdjustPagebreak(p, kp, ph)
while ret_value:
ret_value, kp = container.AdjustPagebreak(p, kp, ph)

3
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlCell.Draw.1.py Normal file
View File

@@ -0,0 +1,3 @@
dc.DrawText("hello", x + self.PosX, y + self.PosY)

3
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlCell.DrawInvisible.1.py Normal file
View File

@@ -0,0 +1,3 @@
dc.DrawText("hello", x + self.PosX, y + self.PosY)

2
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlContainerCell.SetWidthFloat.1.py Normal file
View File

@@ -0,0 +1,2 @@
SetWidthFloat(-50, wx.html.HTML_UNITS_PIXELS)

2
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlContainerCell.SetWidthFloat.2.py Normal file
View File

@@ -0,0 +1,2 @@
SetWidthFloat(-50, wx.html.HTML_UNITS_PIXELS)

7
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlFilter.CanRead.1.py Normal file
View File

@@ -0,0 +1,7 @@
def CanRead(file):
# file is a wx.FSFile in this case...
return (file.GetMimeType() == "application/x-ugh")

6
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlFilter.ReadFile.1.py Normal file
View File

@@ -0,0 +1,6 @@
def ReadFile(file):
# file is a wx.FSFile in this case...
return "<html><body><img src=\"" + file.GetLocation() + \
"\"></body></html>"

2
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlHelpController.AddBook.1.py Normal file
View File

@@ -0,0 +1,2 @@
AddBook("help.zip")

2
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlHelpController.AddBook.2.py Normal file
View File

@@ -0,0 +1,2 @@
AddBook("help.zip")

11
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlHelpWindow.1.py Normal file
View File

@@ -0,0 +1,11 @@
# self.embeddedHelpWindow is a wx.html.HtmlHelpWindow
# self.embeddedHtmlHelp is a wx.html.HtmlHelpController
# Create embedded HTML Help window
self.embeddedHelpWindow = wx.html.HtmlHelpWindow
self.embeddedHtmlHelp.UseConfig(config, rootPath) # Set your own config object here
self.embeddedHtmlHelp.SetHelpWindow(self.embeddedHelpWindow)
self.embeddedHelpWindow.Create(self, wx.ID_ANY, wx.DefaultPosition, self.GetClientSize(),
wx.TAB_TRAVERSAL|wx.BORDER_NONE, wx.html.HF_DEFAULT_STYLE)
self.embeddedHtmlHelp.AddBook("doc.zip")

4
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlModalHelp.1.py Normal file
View File

@@ -0,0 +1,4 @@
# The help can be browsed during the lifetime of self object when the
# user quits the help, program execution will continue.
help = wx.html.HtmlModalHelp(parent, "help", "My topic")

2
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlParser.GetFS.1.py Normal file
View File

@@ -0,0 +1,2 @@
f = self.Parser.GetFS().OpenFile("image.jpg")

10
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlParser.PushTagHandler.1.py Normal file
View File

@@ -0,0 +1,10 @@
# .. code-block:: xml
<myitems>
<param name="one" value="1">
<param name="two" value="2">
</myitems>
<execute>
<param program="text.exe">
</execute>

3
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetBeginPos.1.py Normal file
View File

@@ -0,0 +1,3 @@
# .. code-block:: text
bla bla bla <MYTAG> bla bla internal text</MYTAG> bla bla

3
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetEndPos1.1.py Normal file
View File

@@ -0,0 +1,3 @@
# .. code-block:: text
bla bla bla <MYTAG> bla bla internal text</MYTAG> bla bla

3
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetEndPos2.1.py Normal file
View File

@@ -0,0 +1,3 @@
# .. code-block:: text
bla bla bla <MYTAG> bla bla internal text</MYTAG> bla bla

11
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetParam.1.py Normal file
View File

@@ -0,0 +1,11 @@
# ... Some code here...
# you have wx.HtmlTag variable tag which is equal to the
# HTML tag <FONT SIZE=+2 COLOR="#0000FF">
dummy = tag.GetParam("SIZE")
# dummy == "+2"
dummy = tag.GetParam("COLOR")
# dummy == "#0000FF"
dummy = tag.GetParam("COLOR", true)
# dummy == "\"#0000FF\"" -- see the difference!!

8
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.HasEnding.1.py Normal file
View File

@@ -0,0 +1,8 @@
# .. code-block:: html
<html><body>
Hello<p>
How are you?
<p align=center>This is centered...</p>
Oops<br>Oooops!
</body></html>

7
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTagHandler.HandleTag.1.py Normal file
View File

@@ -0,0 +1,7 @@
def HandleTag(self, tag):
# change state of parser (e.g. set bold face)
self.ParseInner(tag)
# ...
# restore original state of parser

3
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTagHandler.ParseInner.1.py Normal file
View File

@@ -0,0 +1,3 @@
# .. code-block:: html
<A HREF="x.htm">Hello, world!</A>

2
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlWinParser.GetContainer.1.py Normal file
View File

@@ -0,0 +1,2 @@
self.WParser.GetContainer().InsertCell(html_cell)

2
docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlWindow.SetPage.1.py Normal file
View File

@@ -0,0 +1,2 @@
htmlwin.SetPage("<html><body>Hello, world!</body></html>")

9
docs/sphinx/rest_substitutions/snippets/python/converted/stc.StyledTextCtrl.GetInsertionPoint.1.py Normal file
View File

@@ -0,0 +1,9 @@
def GetCurrentChar(self, text_ctrl):
pos = text_ctrl.GetInsertionPoint()
if pos == text_ctrl.GetLastPosition():
return ''
return text_ctrl.GetRange(pos, pos + 1)

61
etgtools/sphinx_generator.py
View File

@@ -1056,6 +1056,18 @@ class Section(Node):
# Special treatment for deprecated, wxWidgets devs do not put the version number
text = '%s\n%s%s'%(VERSION, sub_spacer, text.lstrip('Deprecated'))
elif section_type == 'par':
# Horrible hack... Why is there a </para> end tag inside the @par tag???
text = Node.Join(self, with_tail=True)
split = text.split('\n')
current = 0
for index, line in enumerate(split):
if '---' in line:
current = index-1
break
return '\n\n' + '\n'.join(split[current:]) + '\n\n'
if section_type in ['note', 'remark', 'remarks', 'return']:
text = '\n\n' + sub_spacer + text
@@ -1396,14 +1408,20 @@ class Snippet(Node):
else:
fid = open(self.converted_py, 'rt')
highlight = None
while 1:
tline = fid.readline()
if not tline: # end of file
code = ""
fid.close()
break
if 'code-block::' in tline:
highlight = tline.replace('#', '').strip()
continue
if not tline.strip():
continue
@@ -1411,6 +1429,9 @@ class Snippet(Node):
fid.close()
break
if highlight:
docstrings += '\n\n%s\n\n'%highlight
docstrings += '::\n\n'
docstrings += code.rstrip() + '\n\n'
@@ -1766,9 +1787,17 @@ class Title(Node):
to avoid wrong ReST output.
"""
text = '|phoenix_title| ' + ConvertToPython(self.element.text)
if isinstance(self.parent, Section) and self.parent.section_type == 'par':
# Sub-title in a @par doxygen tag
text = ConvertToPython(self.element.text)
underline = '-'
else:
# Normal big title
text = '|phoenix_title| ' + ConvertToPython(self.element.text)
underline = '='
lentext = len(text)
text = '\n\n%s\n%s\n\n'%(text.rstrip('.'), '='*lentext)
text = '\n\n%s\n%s\n\n'%(text.rstrip('.'), underline*lentext)
return text
@@ -2041,11 +2070,20 @@ class XMLDocString(object):
if 'ListItem' in parent.GetHierarchy():
rest_class = Section(element, parent, self.kind, self.is_overload, self.share_docstrings)
else:
if element.tail:
dummy, section_type = list(element.items())[0]
section_type = section_type.split("_")[0]
if element.tail and section_type != 'par':
Node(element.tail, parent)
rest_class = Section(element, None, self.kind, self.is_overload, self.share_docstrings)
self.root.AddSection(rest_class)
if section_type == 'par':
# doxygen @par stuff
rest_class = Section(element, parent, self.kind, self.is_overload, self.share_docstrings)
if element.tail:
Node(element.tail, rest_class)
else:
rest_class = Section(element, None, self.kind, self.is_overload, self.share_docstrings)
self.root.AddSection(rest_class)
elif tag == 'image':
rest_class = Image(element, parent)
@@ -2638,7 +2676,7 @@ class XMLDocString(object):
# -----------------------------------------------------------------------
def EventsInStyle(self, line, class_name):
def EventsInStyle(self, line, class_name, added=False):
docstrings = ''
newline = line
@@ -2649,7 +2687,7 @@ class XMLDocString(object):
# constructor!!!
docstrings += templates.TEMPLATE_WINDOW_STYLES % class_name
elif 'The following event handler macros' in line:
elif 'The following event handler macros' in line and not added:
last = line.index(':')
line = line[last+1:].strip()
@@ -2659,14 +2697,16 @@ class XMLDocString(object):
newline = 'Handlers bound for the following event types will receive a %s parameter.'%line
docstrings += templates.TEMPLATE_EVENTS % class_name
added = True
elif 'Event macros for events' in line:
elif 'Event macros for events' in line and not added:
docstrings += templates.TEMPLATE_EVENTS % class_name
added = True
elif 'following extra styles:' in line:
docstrings += templates.TEMPLATE_WINDOW_EXTRASTYLES % class_name
return docstrings, newline
return docstrings, newline, added
# -----------------------------------------------------------------------
@@ -2697,9 +2737,10 @@ class XMLDocString(object):
def Indent(self, class_name, item, spacer, docstrings):
added = False
for line in item.splitlines():
if line.strip():
newdocs, newline = self.EventsInStyle(line, class_name)
newdocs, newline, added = self.EventsInStyle(line, class_name, added)
docstrings += newdocs
docstrings += spacer + newline + '\n'
else:

11
sphinxtools/constants.py
View File

@@ -59,7 +59,8 @@ SECTIONS = [('return' , ':returns:'),
('available' , '.. availability::'),
('note' , '.. note::'),
('see' , '.. seealso::'),
('todo' , '.. todo::')]
('todo' , '.. todo::'),
('par' , '')]
# List of things to remove/ignore (there may be more)
@@ -100,9 +101,11 @@ NO_MODULE = {
# Widgets
# Enums/constants
'DataViewCellMode' : 'dataview.',
'DataViewCellRenderState': 'dataview.',
'DataViewColumnFlags' : 'dataview.',
'DataViewCellMode' : 'dataview.',
'DataViewCellRenderState' : 'dataview.',
'DataViewColumnFlags' : 'dataview.',
'DataViewItemObjectMapper': 'dataview.',
'PyDataViewModel' : 'dataview.',
}