diff --git a/docs/sphinx/rest_substitutions/overviews/DocstringsGuidelines.rst b/docs/sphinx/rest_substitutions/overviews/DocstringsGuidelines.rst
index ae0ab163..8650d8d0 100644
--- a/docs/sphinx/rest_substitutions/overviews/DocstringsGuidelines.rst
+++ b/docs/sphinx/rest_substitutions/overviews/DocstringsGuidelines.rst
@@ -9,21 +9,26 @@
|phoenix_title| **Phoenix Docstrings Guidelines**
==================================================
-This document gives a brief introduction about the current docstrings standards
-in the Phoenix project. Most of the documentation in the Phoenix core is automatically
-generated by parsing the wxWidgets XML docs; however, Phoenix has its own pure-Python
-functions and classes in at least two places:
+This document gives a brief introduction about the current docstrings
+standards in the Phoenix project. Most of the documentation in the
+Phoenix core is automatically generated by parsing the wxWidgets XML
+docs; however, Phoenix has its own pure-Python functions and classes
+in at least two places:
-* **Core Library**: examples include :ref:`CallLater` and :func:`date2pydate`, which require
- manual input of the documentation strings. This is achieved by editing the source Python files
- located in the ``etg`` folder in the Phoenix directory tree;
-* **wx.lib**: the whole of ``wx.lib`` (and its sub-folders) is made up of pure-Python modules,
- often representing owner-drawn widgets which are not available as wrapped modules. Again,
- this requires manual editing of the source Python files.
+* **Core Library**: examples include :ref:`wx.CallLater` and
+ :func:`wx.date2pydate`, which require manual input of the
+ documentation strings. This is achieved by editing the source Python
+ files located in the ``etg`` folder in the Phoenix directory tree;
-This document is a starting point in setting some reasonable standards on how the pure-Python
-docstrings may be edited and improved to make the overall appearance of the Phoenix documentation
-consistent and pleasant.
+* **wx.lib**: the whole of ``wx.lib`` (and its sub-folders) is made up
+ of pure-Python modules, often representing owner-drawn widgets which
+ are not available as wrapped modules. Again, this requires manual
+ editing of the source Python files.
+
+This document is a starting point in setting some reasonable standards
+on how the pure-Python docstrings may be edited and improved to make
+the overall appearance of the Phoenix documentation consistent and
+pleasant.
.. _info field lists:
@@ -31,35 +36,43 @@ consistent and pleasant.
Info Field Lists
----------------
-`Info Field Lists` refer to the various options available while documenting a method or a function,
-and in particular its parameters, keywords, return type and possibly raised Python `Exceptions`.
+`Info Field Lists` refer to the various options available while
+documenting a method or a function, and in particular its parameters,
+keywords, return type and possibly raised Python `Exceptions`.
-Inside Python object description directives, reST field lists with these fields
-are recognized and formatted nicely:
+Inside Python object description directives, reST field lists with
+these fields are recognized and formatted nicely:
-* ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``:
- Description of a parameter.
+* ``param``, ``parameter``, ``arg``, ``argument``, ``key``,
+ ``keyword``: Description of a parameter.
+
* ``type``: Type of a parameter.
-* ``raises``, ``raise``, ``except``, ``exception``: That (and when) a specific
- exception is raised.
+
+* ``raises``, ``raise``, ``except``, ``exception``: That (and when) a
+ specific exception is raised.
+
* ``var``, ``ivar``, ``cvar``: Description of a variable.
+
* ``returns``, ``return``: Description of the return value.
+
* ``rtype``: Return type.
-The field names must consist of one of these keywords and an argument (except
-for ``returns`` and ``rtype``, which do not need an argument). This is best
-explained by an example::
+The field names must consist of one of these keywords and an argument
+(except for ``returns`` and ``rtype``, which do not need an
+argument). This is best explained by an example::
.. method:: Set3StateValue(self, state):
Sets the checkbox item to the given `state`.
- :param `state`: can be one of: ``wx.CHK_UNCHECKED`` (check is off), ``wx.CHK_CHECKED``
- (check is on) or ``wx.CHK_UNDETERMINED`` (check is mixed).
+ :param `state`: can be one of: ``wx.CHK_UNCHECKED`` (check is
+ off), ``wx.CHK_CHECKED`` (check is on) or
+ ``wx.CHK_UNDETERMINED`` (check is mixed).
:type `state`: integer
- :returns: ``True`` if the value was successfully set, ``False`` otherwise.
+ :returns: ``True`` if the value was successfully set, ``False``
+ otherwise.
:rtype: bool
:raise: `Exception` when the item is not a 3-state checkbox item.
@@ -69,15 +82,16 @@ explained by an example::
This will render like this:
.. method:: Set3StateValue(self, state):
- :noindex:
Sets the checkbox item to the given `state`.
- :param `state`: can be one of: ``wx.CHK_UNCHECKED`` (check is off), ``wx.CHK_CHECKED``
- (check is on) or ``wx.CHK_UNDETERMINED`` (check is mixed).
+ :param `state`: can be one of: ``wx.CHK_UNCHECKED`` (check is
+ off), ``wx.CHK_CHECKED`` (check is on) or
+ ``wx.CHK_UNDETERMINED`` (check is mixed).
:type `state`: integer
- :returns: ``True`` if the value was successfully set, ``False`` otherwise.
+ :returns: ``True`` if the value was successfully set, ``False``
+ otherwise.
:rtype: bool
:raise: `Exception` when the item is not a 3-state checkbox item.
@@ -85,18 +99,21 @@ This will render like this:
|
-It is also possible to combine parameter type and description, if the type is a
-single word, like this::
+It is also possible to combine parameter type and description, if the
+type is a single word, like this::
- :param integer `state`: can be one of: ``wx.CHK_UNCHECKED`` (check is off), ``wx.CHK_CHECKED``
- (check is on) or ``wx.CHK_UNDETERMINED`` (check is mixed).
+ :param integer `state`: can be one of: ``wx.CHK_UNCHECKED`` (check
+ is off), ``wx.CHK_CHECKED`` (check is on) or
+ ``wx.CHK_UNDETERMINED`` (check is mixed).
In general, the standards for the ``:param`` field are the following:
-1. Do not use the ``@param`` construct, as I am not sure Sphinx and docutils understand it;
-2. Always try and define the parameter type: if the parameter is another Phoenix class, you can simply
- write this::
+1. Do not use the ``@param`` construct, as I am not sure Sphinx and
+ docutils understand it;
+
+2. Always try and define the parameter type: if the parameter is
+ another Phoenix class, you can simply write this::
:param Point `pt`: the mouse pointer location.
@@ -106,12 +123,15 @@ In general, the standards for the ``:param`` field are the following:
:type `pt`: Point
-Similarly, for the ``:return:`` and ``:rtype:`` field, you may consider doing the following:
+Similarly, for the ``:return:`` and ``:rtype:`` field, you may
+consider doing the following:
-1. Try and put double-backticks on words like ``True``, ``False``, ``None`` and the various
- Phoenix constants (i.e., ``wx.TR_DEFAULT_STYLE``);
-2. If you can't guess what a method function returns, just leave the ``:returns:`` and ``:rtype:``
- fields blank.
+1. Try and put double-backticks on words like ``True``, ``False``,
+ ``None`` and the various Phoenix constants (i.e.,
+ ``wx.TR_DEFAULT_STYLE``);
+
+2. If you can't guess what a method function returns, just leave the
+ ``:returns:`` and ``:rtype:`` fields blank.
.. seealso:: `Sphinx Info Field List `_
@@ -122,9 +142,11 @@ Similarly, for the ``:return:`` and ``:rtype:`` field, you may consider doing th
Admonitions
-----------
-Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can.
-They contain arbitrary body elements. Typically, an admonition is rendered as an offset block
-in a document, sometimes outlined or shaded, with a title matching the admonition type. For example::
+Admonitions are specially marked "topics" that can appear anywhere an
+ordinary body element can. They contain arbitrary body
+elements. Typically, an admonition is rendered as an offset block in a
+document, sometimes outlined or shaded, with a title matching the
+admonition type. For example::
.. warning:: I am a warning.
@@ -135,28 +157,41 @@ Will render as:
|
-Currently, the `sphinx_generator` tool recognizes the following admonitions:
+Currently, the `sphinx_generator` tool recognizes the following
+admonitions:
-1. ``.. note::`` or ``:note:`` : simple annotations to make a particular comment/sentence
- stand out against the rest of the documentation strings for a particular class, method or function;
-2. ``.. warning::`` : this admonition normally indicates a problem or a severe limitation of a method,
- class or function. In the Phoenix world, this may also indicate that a particular widget is not
+1. ``.. note::`` or ``:note:`` : simple annotations to make a
+ particular comment/sentence stand out against the rest of the
+ documentation strings for a particular class, method or function;
+
+2. ``.. warning::`` : this admonition normally indicates a problem or
+ a severe limitation of a method, class or function. In the Phoenix
+ world, this may also indicate that a particular widget is not
supported under one or more platforms;
-3. ``.. deprecated::`` : used to mark deprecated methods, classes or functions;
-4. ``.. availability::`` : normally employed to make the user understand on which platform(s) a particular
- functionality is supported/available;
-5. ``.. seealso::`` or ``:see:`` : added primarily to facilitate the browsing of the docs, this admonition
- should be employed every time you think a user may be interested in seeing a related/similar method
- or a function providing an alternative implementation;
-6. ``.. todo::`` : used to mark incomplete methods/functions, or simply as a remainder for the user and
- the developer that some more functionality needs to be added.
+
+3. ``.. deprecated::`` : used to mark deprecated methods, classes or
+ functions;
-You can put pretty much anything inside an admonition section, as long as it is properly indented. The
-recommendation is to implement it like this::
+4. ``.. availability::`` : normally employed to make the user
+ understand on which platform(s) a particular functionality is
+ supported/available;
+
+5. ``.. seealso::`` or ``:see:`` : added primarily to facilitate the
+ browsing of the docs, this admonition should be employed every time
+ you think a user may be interested in seeing a related/similar
+ method or a function providing an alternative implementation;
+
+6. ``.. todo::`` : used to mark incomplete methods/functions, or
+ simply as a remainder for the user and the developer that some more
+ functionality needs to be added.
+
+You can put pretty much anything inside an admonition section, as long
+as it is properly indented. The recommendation is to implement it like
+this::
.. note::
- The class :ref:`TreeCtrl` can be used to display a tree, with these notes:
+ The class :ref:`wx.TreeCtrl` can be used to display a tree, with these notes:
- The note contains all indented body elements
following.
@@ -169,7 +204,7 @@ Which will render as follows:
.. note::
- The class :ref:`TreeCtrl` can be used to display a tree, with these notes:
+ The class :ref:`wx.TreeCtrl` can be used to display a tree, with these notes:
- The note contains all indented body elements
following.
@@ -177,9 +212,11 @@ Which will render as follows:
-In addition to the aforementioned admonitions, you can also use the default Sphinx directives
-like ``.. versionadded::`` and ``.. versionchanged::``, to highlight the fact that some method,
-function or class has been added/modified starting with a particular Phoenix version.
+In addition to the aforementioned admonitions, you can also use the
+default Sphinx directives like ``.. versionadded::`` and
+``.. versionchanged::``, to highlight the fact that some method,
+function or class has been added/modified starting with a particular
+Phoenix version.
.. seealso:: `Sphinx Paragraph-level markup `_
@@ -192,18 +229,21 @@ Contributing Samples
.. highlight:: python
-If you wish to contribute a (short) sample to be included in the documentation, please follow
-these conventions:
+If you wish to contribute a (short) sample to be included in the
+documentation, please follow these conventions:
-1. Name the snippet of code like ``classname.methodname.INTEGER.py``, i.e. if you wish to contribute 2
- snippets about the :meth:`CheckBox.SetValue` method, please name your snippet files like this:
+1. Name the snippet of code like ``wxmodule.classname.methodname.INTEGER.py``,
+ i.e. if you wish to contribute 2 snippets about the
+ :meth:`wx.CheckBox.SetValue` method, please name your snippet files
+ like this:
- * `CheckBox.SetValue.1.py`
- * `CheckBox.SetValue.2.py`
-
-
-2. At the very top of the snippet file (on the first line), put your name, or your alias, or anything
- you use as internet name preceeded by a double-hash, i.e.:
+ * ``wx.CheckBox.SetValue.1.py``
+ * ``wx.CheckBox.SetValue.2.py``
+
+
+2. At the very top of the snippet file (on the first line), put your
+ name, or your alias, or anything you use as internet name preceeded
+ by a double-hash, i.e.:
``##Andrea Gavana``
@@ -212,33 +252,34 @@ these conventions:
##Chris Barker
#!/usr/bin/env python
-
"""
A simple test of the GridBagSizer
http://wiki.wxpython.org/index.cgi/WriteItYourself
"""
# Whatever code here...
- def SendSizeEvent(self):
-
+ def SendSizeEvent(self):
self.AdjustMySize()
.. highlight:: rst
-This snippet will end up in the snippets `contrib` folder, to differentiate it from the snippets
-automatically generated when parsing the wxWidgets C++ XML documentation.
+This snippet will end up in the snippets `contrib` folder, to
+differentiate it from the snippets automatically generated when
+parsing the wxWidgets C++ XML documentation.
-Please keep the snippets as short as possible: they don't need to be fully-runnable and self contained
-applications, they are simply meant to show a particular/clever/unusual way of using a method, a class
-or a function.
+Please keep the snippets as short as possible: they don't need to be
+fully-runnable and self contained applications, they are simply meant
+to show a particular/clever/unusual way of using a method, a class or
+a function.
-Please do send your sample snippets to me at `this `_ e-mail address or
-you can submit the sample snippets to the `wxWidgets/Phoenix Github repository `_.
-The snippets should be placed in the source tree in this folder:
+Please do submit the sample snippets to the
+`wxWidgets/Phoenix Github repository `_
+as PR (Pull Request). The snippets should be placed in the source
+tree in this folder:
-``Phoenix/docs/sphinx/rest_substitutions/snippets/python/contrib``
+ ``Phoenix/docs/sphinx/rest_substitutions/snippets/python/contrib``
.. _contributing screenshots:
@@ -246,26 +287,30 @@ The snippets should be placed in the source tree in this folder:
Contributing Screenshots
------------------------
-Currently Phoenix is relatively short of widgets screenshots, especially on Linux/Mac platforms.
+Currently Phoenix is relatively short of widgets screenshots,
+especially on Linux/Mac platforms.
-If you wish to contribute a screenshot of a widget to be included in the documentation, please follow
-these conventions:
+If you wish to contribute a screenshot of a widget to be included in
+the documentation, please follow these conventions:
-- If the widget is a class belonging to the main `wx` namespace, just use the
- class name in lower case (i.e., `wx.Frame` ==> `frame.png`);
-- If it belongs to a sub-namespace (i.e., `wx.dataview`, `wx.aui`, `wx.html`
- and so on), it should be named this way (examples):
+- If the widget is a class belonging to the main `wx` namespace,
+ use the full class name in lower case (i.e., `wx.Frame` ==>
+ `wx.frame.png`);
- 1) `wx.dataview.DataViewCtrl` ==> `dataview.dataviewctrl.png`
- 2) `wx.aui.AuiManager` ==> `aui.auimanager.png`
+- If it belongs to a sub-namespace (i.e., `wx.dataview`, `wx.aui`,
+ `wx.html` and so on), it should be named this way (examples):
+
+ 1) `wx.dataview.DataViewCtrl` ==> `wx.dataview.dataviewctrl.png`
+ 2) `wx.aui.AuiManager` ==> `wx.aui.auimanager.png`
-Please do send your screenshots to me at `this `_ e-mail address or
-you can submit the screenshots to the `wxWidgets/Phoenix Github repository `_.
-The screenshots should be placed in the source tree in this folder:
+Please submit the screenshots to the
+`wxWidgets/Phoenix Github repository `_
+as a PR (Pull Request). The screenshots should be placed in the
+source tree in this folder:
-``Phoenix/trunk/docs/sphinx/_static/images/widgets/fullsize``
+ ``Phoenix/trunk/docs/sphinx/_static/images/widgets/fullsize``
-Please make sure to put your images in the appropriate sub-folder, depending on the platform you
-chose to take the screenshots on.
+Please make sure to put your images in the appropriate sub-folder,
+depending on the platform you chose to take the screenshots on.
diff --git a/docs/sphinx/rest_substitutions/overviews/app_overview.rst b/docs/sphinx/rest_substitutions/overviews/app_overview.rst
index ef269b70..8bf5bed9 100644
--- a/docs/sphinx/rest_substitutions/overviews/app_overview.rst
+++ b/docs/sphinx/rest_substitutions/overviews/app_overview.rst
@@ -11,33 +11,38 @@
Introduction
------------
-A wxPython application does not have a main procedure; the equivalent is the :meth:`AppConsole.OnInit` member defined for a class derived from :ref:`App`.
+A wxPython application does not have a main procedure; the equivalent
+is the :meth:`wx.AppConsole.OnInit` member defined for a class derived
+from :ref:`wx.App`.
-`OnInit` will usually create a top window as a bare minimum. Unlike in earlier versions of wxPython, `OnInit` does not return a frame.
-Instead it returns a boolean value which indicates whether processing should continue (``True``) or not (``False``).
+`OnInit` will usually create a top window as a bare minimum. Unlike in
+earlier versions of wxPython, `OnInit` does not return a frame.
+Instead it returns a boolean value which indicates whether processing
+should continue (``True``) or not (``False``).
-An application closes by destroying all windows. Because all frames must be destroyed for the application to exit, it is advisable to use
-parent frames wherever possible when creating new frames, so that deleting the top level frame will automatically delete child frames.
-The alternative is to explicitly delete child frames in the top-level frame's :ref:`CloseEvent` handler.
+An application closes by destroying all windows. Because all frames
+must be destroyed for the application to exit, it is advisable to use
+parent frames wherever possible when creating new frames, so that
+deleting the top level frame will automatically delete child frames.
+The alternative is to explicitly delete child frames in the top-level
+frame's :ref:`wx.CloseEvent` handler.
-In emergencies the :func:`Exit` function can be called to kill the application however normally the application shuts down automatically,
-see :ref:`Application Shutdown `.
+In emergencies the :func:`wx.Exit` function can be called to kill the
+application however, normally the application shuts down automatically
+when the last top-level window closes. See
+:ref:`Application Shutdown `.
An example of defining an application follows::
- class DerivedApp(wx.App):
+ class DerivedApp(wx.App):
- def OnInit(self):
-
- the_frame = wx.Frame(None, -1)
-
- # Other initialization code...
-
- the_frame.Show(True)
-
- return True
+ def OnInit(self):
+ the_frame = wx.Frame(None, -1)
+ # Other initialization code...
+ the_frame.Show(True)
+ return True
.. _application shutdown:
@@ -45,14 +50,20 @@ An example of defining an application follows::
Application Shutdown
--------------------
-The application normally shuts down when the last of its top level windows is closed. This is normally the expected behaviour and means
-that it is enough to call :meth:`Window.Close` () in response to the "Exit" menu command if your program has a single top level window.
-If this behaviour is not desirable :meth:`PyApp.SetExitOnFrameDelete` can be called to change it.
+The application normally shuts down when the last of its top level
+windows is closed. This is normally the expected behaviour and means
+that it is enough to call :meth:`wx.Window.Close`() in response to the
+"Exit" menu command if your program has a single top level window. If
+this behavior is not desirable :meth:`wx.PyApp.SetExitOnFrameDelete` can
+be called to change it.
-.. note:: Note that such logic doesn't apply for the windows shown before the program enters the main loop: in other words, you can
- safely show a dialog from :meth:`AppConsole.OnInit` and not be afraid that your application terminates when this dialog -- which is the last
- top level window for the moment -- is closed.
+.. note:: Note that such logic doesn't apply for the windows shown
+ before the program enters the main loop: in other words, you can
+ safely show a dialog from :meth:`wx.AppConsole.OnInit` and not be
+ afraid that your application terminates when this dialog -- which
+ is the last top level window for the moment -- is closed.
-Another aspect of the application shutdown is :meth:`AppConsole.OnExit` which is called when the application exits but before wxPython cleans up
-its internal structures.
+Another aspect of the application shutdown is
+:meth:`wx.AppConsole.OnExit` which is called when the application
+exits but before wxPython cleans up its internal structures.
diff --git a/docs/sphinx/rest_substitutions/overviews/bitmap_overview.rst b/docs/sphinx/rest_substitutions/overviews/bitmap_overview.rst
index e47a23af..66244f4f 100644
--- a/docs/sphinx/rest_substitutions/overviews/bitmap_overview.rst
+++ b/docs/sphinx/rest_substitutions/overviews/bitmap_overview.rst
@@ -3,19 +3,22 @@
.. _bitmaps and icons:
-===============================================
+======================================
|phoenix_title| **Bitmaps and Icons**
-===============================================
+======================================
-The :ref:`Bitmap` class encapsulates the concept of a platform-dependent bitmap, either monochrome or colour.
-Platform-specific methods for creating a :ref:`Bitmap` object from an existing file are catered for.
+The :ref:`wx.Bitmap` class encapsulates the concept of a
+platform-dependent bitmap, either monochrome or colour.
+Platform-specific methods for creating a :ref:`wx.Bitmap` object from
+an existing file are catered for.
-A bitmap created dynamically or loaded from a file can be selected into a memory device context (instance of
-:ref:`MemoryDC`). This enables the bitmap to be copied to a window or memory device context using :meth:`DC.Blit` (),
-or to be used as a drawing surface.
+A bitmap created dynamically or loaded from a file can be selected
+into a memory device context (an instance of :ref:`wx.MemoryDC`). This
+enables the bitmap to be copied to a window or memory device context
+using :meth:`wx.DC.Blit`(), or to be used as a drawing surface.
-.. seealso:: :ref:`MemoryDC` for an example of drawing onto a bitmap.
+.. seealso:: :ref:`wx.MemoryDC` for an example of drawing onto a bitmap.
All wxPython platforms support XPMs for small bitmaps and icons.
@@ -27,77 +30,70 @@ All wxPython platforms support XPMs for small bitmaps and icons.
Supported Bitmap File Formats
-----------------------------
-The following lists the formats handled on different platforms. Note that missing or partially-implemented
-formats are automatically supplemented by using :ref:`Image` to load the data, and then converting it to :ref:`Bitmap`
-form. Note that using :ref:`Image` is the preferred way to load images in wxPython, with the exception of resources
-(XPM-files or native Windows resources).
+The following lists the formats handled on different platforms. Note
+that missing or partially-implemented formats are automatically
+supplemented by using :ref:`wx.Image` to load the data, and then
+converting it to :ref:`wx.Bitmap` form. Note that using
+:ref:`wx.Image` is the preferred way to load images in wxPython, with
+the exception of resources (XPM-files or native Windows resources).
-Bitmap
-^^^^^^
+wx.Bitmap
+^^^^^^^^^
-Under Windows, :ref:`Bitmap` may load the following formats:
+Under Windows, :ref:`wx.Bitmap` may load the following formats:
-- Windows bitmap resource (``BITMAP_TYPE_BMP_RESOURCE``)
-- Windows bitmap file (``BITMAP_TYPE_BMP``)
-- XPM data and file (``BITMAP_TYPE_XPM``)
-- All formats that are supported by the :ref:`Image` class.
+- Windows bitmap resource (``wx.BITMAP_TYPE_BMP_RESOURCE``)
+- Windows bitmap file (``wx.BITMAP_TYPE_BMP``)
+- XPM data and file (``wx.BITMAP_TYPE_XPM``)
+- All formats that are supported by the :ref:`wx.Image` class.
-Under wxGTK, :ref:`Bitmap` may load the following formats:
+Under wxGTK, :ref:`wx.Bitmap` may load the following formats:
-- XPM data and file (``BITMAP_TYPE_XPM``)
-- All formats that are supported by the :ref:`Image` class.
+- XPM data and file (``wx.BITMAP_TYPE_XPM``)
+- All formats that are supported by the :ref:`wx.Image` class.
-Under wxMotif and wxX11, :ref:`Bitmap` may load the following formats:
+Under wxMotif and wxX11, :ref:`wx.Bitmap` may load the following formats:
-- XBM data and file (``BITMAP_TYPE_XBM``)
-- XPM data and file (``BITMAP_TYPE_XPM``)
-- All formats that are supported by the :ref:`Image` class.
+- XBM data and file (``wx.BITMAP_TYPE_XBM``)
+- XPM data and file (``wx.BITMAP_TYPE_XPM``)
+- All formats that are supported by the :ref:`wx.Image` class.
-Icon
-^^^^
+wx.Icon
+^^^^^^^
-Under Windows, :ref:`Icon` may load the following formats:
+Under Windows, :ref:`wx.Icon` may load the following formats:
-- Windows icon resource (``BITMAP_TYPE_ICO_RESOURCE``)
-- Windows icon file (``BITMAP_TYPE_ICO``)
-- XPM data and file (``BITMAP_TYPE_XPM``)
+- Windows icon resource (``wx.BITMAP_TYPE_ICO_RESOURCE``)
+- Windows icon file (``wx.BITMAP_TYPE_ICO``)
+- XPM data and file (``wx.BITMAP_TYPE_XPM``)
-Under wxGTK, :ref:`Icon` may load the following formats:
+Under wxGTK, :ref:`wx.Icon` may load the following formats:
-- XPM data and file (``BITMAP_TYPE_XPM``)
-- All formats that are supported by the :ref:`Image` class.
+- XPM data and file (``wx.BITMAP_TYPE_XPM``)
+- All formats that are supported by the :ref:`wx.Image` class.
-Under wxMotif and wxX11, :ref:`Icon` may load the following formats:
-- XBM data and file (``BITMAP_TYPE_XBM``)
-- XPM data and file (``BITMAP_TYPE_XPM``)
-- All formats that are supported by the :ref:`Image` class.
+wx.Cursor
+^^^^^^^^^
+
+Under Windows, :ref:`wx.Cursor` may load the following formats:
+
+- Windows cursor resource (``wx.BITMAP_TYPE_CUR_RESOURCE``)
+- Windows cursor file (``wx.BITMAP_TYPE_CUR``)
+- Windows icon file (``wx.BITMAP_TYPE_ICO``)
+- Windows bitmap file (``wx.BITMAP_TYPE_BMP``)
-Cursor
-^^^^^^
-
-Under Windows, :ref:`Cursor` may load the following formats:
-
-- Windows cursor resource (``BITMAP_TYPE_CUR_RESOURCE``)
-- Windows cursor file (``BITMAP_TYPE_CUR``)
-- Windows icon file (``BITMAP_TYPE_ICO``)
-- Windows bitmap file (``BITMAP_TYPE_BMP``)
-
-
-Under wxGTK, :ref:`Cursor` may load the following formats (in addition to stock cursors):
+Under wxGTK, :ref:`wx.Cursor` may load the following formats (in
+addition to stock cursors):
- None (stock cursors only).
-Under wxMotif and wxX11, :ref:`Cursor` may load the following formats:
-
-- XBM data and file (``BITMAP_TYPE_XBM``)
-
diff --git a/docs/sphinx/rest_substitutions/overviews/bookctrl_overview.rst b/docs/sphinx/rest_substitutions/overviews/bookctrl_overview.rst
index 8e0a5438..4ffd11a3 100644
--- a/docs/sphinx/rest_substitutions/overviews/bookctrl_overview.rst
+++ b/docs/sphinx/rest_substitutions/overviews/bookctrl_overview.rst
@@ -3,9 +3,9 @@
.. _bookctrl overview:
-===============================================
+======================================
|phoenix_title| **BookCtrl Overview**
-===============================================
+======================================
Introduction
@@ -14,22 +14,24 @@ Introduction
A book control is a convenient way of displaying multiple pages of information, displayed one page at a time.
wxPython has five variants of this control:
-- :ref:`Choicebook`: controlled by a :ref:`Choice`
-- :ref:`Listbook`: controlled by a :ref:`ListCtrl`
-- :ref:`Notebook`: uses a row of tabs
-- :ref:`Treebook`: controlled by a :ref:`TreeCtrl`
-- :ref:`Toolbook`: controlled by a :ref:`ToolBar`
+- :ref:`wx.Choicebook`: controlled by a :ref:`wx.Choice`
+- :ref:`wx.Listbook`: controlled by a :ref:`wx.ListCtrl`
+- :ref:`wx.Notebook`: uses a row of tabs
+- :ref:`wx.Treebook`: controlled by a :ref:`wx.TreeCtrl`
+- :ref:`wx.Toolbook`: controlled by a :ref:`wx.ToolBar`
Best Book
---------
-:ref:`BookCtrlBase` is mapped to the class best suited for a given platform. Currently it provides :ref:`Choicebook`
-for smartphones equipped with WinCE, and :ref:`Notebook` for all other platforms. The mapping consists of:
+:ref:`wx.BookCtrlBase` is mapped to the class best suited for a given
+platform. Currently it provides :ref:`wx.Choicebook` for smartphones
+equipped with WinCE, and :ref:`wx.Notebook` for all other platforms. The
+mapping consists of:
=============================================== ==================================================
-`BookCtrl` `Choicebook` or `Notebook`
+`wx.BookCtrl` `wx.Choicebook` or `wx.Notebook`
=============================================== ==================================================
``wxEVT_COMMAND_BOOKCTRL_PAGE_CHANGED`` ``wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGED`` or ``wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGED``
``wxEVT_COMMAND_BOOKCTRL_PAGE_CHANGING`` ``wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGING`` or ``wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING``
@@ -40,9 +42,9 @@ EVT_BOOKCTRL_PAGE_CHANGING EVT_CHOICEBOOK_PAGE_CHANGING or
For orientation of the book controller, use following flags in style:
-- ``BK_TOP``: controller above pages
-- ``BK_BOTTOM``: controller below pages
-- ``BK_LEFT``: controller on the left
-- ``BK_RIGHT``: controller on the right
-- ``BK_DEFAULT``: native controller placement
+- ``wx.BK_TOP``: controller above pages
+- ``wx.BK_BOTTOM``: controller below pages
+- ``wx.BK_LEFT``: controller on the left
+- ``wx.BK_RIGHT``: controller on the right
+- ``wx.BK_DEFAULT``: native controller placement
diff --git a/docs/sphinx/rest_substitutions/overviews/command_overview.rst b/docs/sphinx/rest_substitutions/overviews/command_overview.rst
index 51bf2d60..884c4496 100644
--- a/docs/sphinx/rest_substitutions/overviews/command_overview.rst
+++ b/docs/sphinx/rest_substitutions/overviews/command_overview.rst
@@ -3,28 +3,32 @@
.. _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.
+:class:`wx.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.
+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.
+When a user interface event occurs, the application submits a command
+to a :class:`wx.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.
+The wxPython document/view framework handles Undo and Redo by use of
+:class:`wx.Command` and :class:`wx.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.
+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:
@@ -34,8 +38,10 @@ with an integer or string command identifier.
=================================================
-: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.
+:class:`wx.CommandProcessor` is a class that maintains a history of
+:class:`wx.Command` instances, with undo/redo functionality
+built-in. Derive a new class from this if you want different
+behaviour.
.. _filehistory overview:
@@ -44,22 +50,29 @@ undo/redo functionality built-in. Derive a new class from this if you want diffe
|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.
+:class:`wx.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:`wx.FileHistory` is used by :class:`wx.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.
+By calling :meth:`wx.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).
+ 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:`wx.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``.
+The filenames are appended using menu identifiers in the range
+``wx.ID_FILE1`` to ``wx.ID_FILE9``.
diff --git a/docs/sphinx/rest_substitutions/overviews/common_dialogs_overview.rst b/docs/sphinx/rest_substitutions/overviews/common_dialogs_overview.rst
index bacdd2ff..6b0a85de 100644
--- a/docs/sphinx/rest_substitutions/overviews/common_dialogs_overview.rst
+++ b/docs/sphinx/rest_substitutions/overviews/common_dialogs_overview.rst
@@ -3,20 +3,25 @@
.. _common dialogs:
-===============================================
+===================================
|phoenix_title| **Common Dialogs**
-===============================================
+===================================
-Common dialog classes and functions encapsulate commonly-needed dialog box requirements. They are all 'modal',
-grabbing the flow of control until the user dismisses the dialog, to make them easy to use within an application.
+Common dialog classes and functions encapsulate commonly-needed dialog
+box requirements. They are all 'modal', grabbing the flow of control
+until the user dismisses the dialog, to make them easy to use within
+an application.
-Some dialogs have both platform-dependent and platform-independent implementations, so that if underlying windowing
-systems do not provide the required functionality, the generic classes and functions can stand in. For example,
-under MS Windows, :ref:`ColourDialog` uses the standard colour selector. There is also an equivalent called
-`GenericColourDialog` for other platforms, and a macro defines :ref:`ColourDialog` to be the same as
-`GenericColourDialog` on non-MS Windows platforms. However, under MS Windows, the generic dialog can also be used,
-for testing or other purposes.
+Some dialogs have both platform-dependent and platform-independent
+implementations, so that if underlying windowing systems do not
+provide the required functionality, the generic classes and functions
+can stand in. For example, under MS Windows, :ref:`wx.ColourDialog`
+uses the standard colour selector. There is also an equivalent called
+`wx.GenericColourDialog` for other platforms, and a macro defines
+:ref:`wx.ColourDialog` to be the same as `wx.GenericColourDialog` on
+non-MS Windows platforms. However, under MS Windows, the generic
+dialog can also be used, for testing or other purposes.
@@ -25,35 +30,45 @@ for testing or other purposes.
ColourDialog Overview
---------------------
-The :ref:`ColourDialog` presents a colour selector to the user, and returns with colour information.
+The :ref:`wx.ColourDialog` presents a colour selector to the user, and
+returns with colour information.
The MS Windows Colour Selector
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Under Windows, the native colour selector common dialog is used. This presents a dialog box with three main regions:
-at the top left, a palette of 48 commonly-used colours is shown. Under this, there is a palette of 16 'custom colours'
-which can be set by the application if desired. Additionally, the user may open up the dialog box to show a right-hand
-panel containing controls to select a precise colour, and add it to the custom colour palette.
+Under Windows, the native colour selector common dialog is used. This
+presents a dialog box with three main regions: at the top left, a
+palette of 48 commonly-used colours is shown. Under this, there is a
+palette of 16 'custom colours' which can be set by the application if
+desired. Additionally, the user may open up the dialog box to show a
+right-hand panel containing controls to select a precise colour, and
+add it to the custom colour palette.
The Generic Colour Selector
^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Under non-MS Windows platforms, the colour selector is a simulation of most of the features of the MS Windows selector.
-Two palettes of 48 standard and 16 custom colours are presented, with the right-hand area containing three sliders for
-the user to select a colour from red, green and blue components. This colour may be added to the custom colour palette,
-and will replace either the currently selected custom colour, or the first one in the palette if none is selected.
-The RGB colour sliders are not optional in the generic colour selector. The generic colour selector is also available
-under MS Windows; use the name `GenericColourDialog`.
+Under non-MS Windows platforms, the colour selector is a simulation of
+most of the features of the MS Windows selector. Two palettes of 48
+standard and 16 custom colours are presented, with the right-hand area
+containing three sliders for the user to select a colour from red,
+green and blue components. This colour may be added to the custom
+colour palette, and will replace either the currently selected custom
+colour, or the first one in the palette if none is selected. The RGB
+colour sliders are not optional in the generic colour selector. The
+generic colour selector is also available under MS Windows; use the
+name `wx.GenericColourDialog`.
Example
^^^^^^^
-Here is an example of using :ref:`ColourDialog`, which sets various parameters of a :ref:`ColourData` object, including
-a grey scale for the custom colours. If the user did not cancel the dialog, the application retrieves the selected colour
-and uses it to set the background of a window::
+Here is an example of using :ref:`wx.ColourDialog`, which sets various
+parameters of a :ref:`wx.ColourData` object, including a grey scale
+for the custom colours. If the user did not cancel the dialog, the
+application retrieves the selected colour and uses it to set the
+background of a window::
data = wx.ColourData()
data.SetChooseFull(True)
@@ -62,11 +77,8 @@ and uses it to set the background of a window::
colour = wx.Colour(i*16, i*16, i*16)
data.SetCustomColour(i, colour)
-
dialog = wx.ColourDialog(self, data)
-
if dialog.ShowModal() == wx.ID_OK:
-
retData = dialog.GetColourData()
col = retData.GetColour()
brush = wx.Brush(col, wx.SOLID)
@@ -83,39 +95,44 @@ FontDialog Overview
-------------------
-The :ref:`FontDialog` presents a font selector to the user, and returns with font and colour information.
+The :ref:`wx.FontDialog` presents a font selector to the user, and
+returns with font and colour information.
The MS Windows Font Selector
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Under Windows, the native font selector common dialog is used. This presents a dialog box with controls for font name,
-point size, style, weight, underlining, strikeout and text foreground colour. A sample of the font is shown on a white
-area of the dialog box. Note that in the translation from full MS Windows fonts to wxPython font conventions, strikeout
-is ignored and a font family (such as Swiss or Modern) is deduced from the actual font name (such as Arial or Courier).
+Under Windows, the native font selector common dialog is used. This
+presents a dialog box with controls for font name, point size, style,
+weight, underlining, strikeout and text foreground colour. A sample of
+the font is shown on a white area of the dialog box. Note that in the
+translation from full MS Windows fonts to wxPython font conventions,
+strikeout is ignored and a font family (such as Swiss or Modern) is
+deduced from the actual font name (such as Arial or Courier).
The Generic Font Selector
^^^^^^^^^^^^^^^^^^^^^^^^^
-Under non-MS Windows platforms, the font selector is simpler. Controls for font family, point size, style, weight,
-underlining and text foreground colour are provided, and a sample is shown upon a white background. The generic font
-selector is also available under MS Windows; use the name `GenericFontDialog`.
+Under non-MS Windows platforms, the font selector is simpler. Controls
+for font family, point size, style, weight, underlining and text
+foreground colour are provided, and a sample is shown upon a white
+background. The generic font selector is also available under MS
+Windows; use the name `wx.GenericFontDialog`.
Example
^^^^^^^
-Here is an example of using :ref:`FontDialog`. The application uses the returned font and colour for drawing text on a canvas::
+Here is an example of using :ref:`wx.FontDialog`. The application uses
+the returned font and colour for drawing text on a canvas::
data = wx.FontData()
data.SetInitialFont(canvasFont)
data.SetColour(canvasTextColour)
dialog = wx.FontDialog(self, data)
-
if dialog.ShowModal() == wx.ID_OK:
-
retData = dialog.GetFontData()
canvasFont = retData.GetChosenFont()
canvasTextColour = retData.GetColour()
@@ -130,10 +147,12 @@ PrintDialog Overview
--------------------
-This class represents the print and print setup common dialogs. You may obtain a :ref:`PrinterDC` device context from a
-successfully dismissed print dialog.
+This class represents the print and print setup common dialogs. You
+may obtain a :ref:`wx.PrinterDC` device context from a successfully
+dismissed print dialog.
-.. seealso:: :ref:`Printing Framework Overview ` for an example.
+.. seealso:: :ref:`Printing Framework Overview `
+ for an example.
@@ -143,20 +162,28 @@ FileDialog Overview
-------------------
-Pops up a file selector box. On Windows and GTK 2.4+, this is the common file selector dialog. In X, this is a file
-selector box with somewhat less functionality. The path and filename are distinct elements of a full file pathname.
+Pops up a file selector box. On Windows and GTK 2.4+, this is the
+common file selector dialog. In X, this is a file selector box with
+somewhat less functionality. The path and filename are distinct
+elements of a full file pathname.
-If path is "", the current directory will be used. If filename is "", no default filename will be supplied.
-The wildcard determines what files are displayed in the file selector, and file extension supplies a type extension
-for the required filename. Flags may be a combination of ``FD_OPEN``, ``FD_SAVE``, ``FD_OVERWRITE_PROMPT``,
-``FD_HIDE_READONLY``, ``FD_FILE_MUST_EXIST``, ``FD_MULTIPLE``, ``FD_CHANGE_DIR`` or 0.
+If path is "", the current directory will be used. If filename is "",
+no default filename will be supplied. The wildcard determines what
+files are displayed in the file selector, and file extension supplies
+a type extension for the required filename. Flags may be a combination
+of ``wx.FD_OPEN``, ``wx.FD_SAVE``, ``wx.FD_OVERWRITE_PROMPT``,
+``wx.FD_HIDE_READONLY``, ``wx.FD_FILE_MUST_EXIST``, ``wx.FD_MULTIPLE``,
+``wx.FD_CHANGE_DIR`` or 0.
-Both the X and Windows versions implement a wildcard filter. Typing a filename containing wildcards ``(*, ?)`` in the
-filename text item, and clicking on Ok, will result in only those files matching the pattern being displayed. In the
-X version, supplying no default name will result in the wildcard filter being inserted in the filename text item;
-the filter is ignored if a default name is supplied.
+Both the X and Windows versions implement a wildcard filter. Typing a
+filename containing wildcards ``(\*, ?)`` in the filename text item,
+and clicking on Ok, will result in only those files matching the
+pattern being displayed. In the X version, supplying no default name
+will result in the wildcard filter being inserted in the filename text
+item; the filter is ignored if a default name is supplied.
-The wildcard may be a specification for multiple types of file with a description for each, such as::
+The wildcard may be a specification for multiple types of file with a
+description for each, such as::
wildcard = "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
@@ -168,7 +195,8 @@ DirDialog Overview
-------------------
-This dialog shows a directory selector dialog, allowing the user to select a single directory.
+This dialog shows a directory selector dialog, allowing the user to
+select a single directory.
@@ -177,8 +205,8 @@ This dialog shows a directory selector dialog, allowing the user to select a sin
TextEntryDialog Overview
------------------------
-
-This is a dialog with a text entry field. The value that the user entered is obtained using :meth:`TextEntryDialog.GetValue` ().
+This is a dialog with a text entry field. The value that the user
+entered is obtained using :meth:`wx.TextEntryDialog.GetValue` ().
@@ -187,8 +215,8 @@ This is a dialog with a text entry field. The value that the user entered is obt
PasswordEntryDialog Overview
----------------------------
-
-This is a dialog with a password entry field. The value that the user entered is obtained using :meth:`TextEntryDialog.GetValue` ().
+This is a dialog with a password entry field. The value that the user
+entered is obtained using :meth:`wx.TextEntryDialog.GetValue` ().
@@ -197,11 +225,12 @@ This is a dialog with a password entry field. The value that the user entered is
MessageDialog Overview
----------------------
+This dialog shows a message, plus buttons that can be chosen from
+``OK``, ``Cancel``, ``Yes``, and ``No``. Under Windows, an optional
+icon can be shown, such as an exclamation mark or question mark.
-This dialog shows a message, plus buttons that can be chosen from ``OK``, ``Cancel``, ``Yes``, and ``No``. Under Windows, an
-optional icon can be shown, such as an exclamation mark or question mark.
-
-The return value of :meth:`MessageDialog.ShowModal` () indicates which button the user pressed.
+The return value of :meth:`wx.MessageDialog.ShowModal` () indicates
+which button the user pressed.
@@ -210,9 +239,9 @@ The return value of :meth:`MessageDialog.ShowModal` () indicates which button th
SingleChoiceDialog Overview
---------------------------
-
-This dialog shows a list of choices, plus ``OK`` and (optionally) ``Cancel``. The user can select one of them. The selection
-can be obtained from the dialog as an index, a string or client data.
+This dialog shows a list of choices, plus ``OK`` and (optionally)
+``Cancel``. The user can select one of them. The selection can be
+obtained from the dialog as an index, a string or client data.
@@ -221,6 +250,6 @@ can be obtained from the dialog as an index, a string or client data.
MultiChoiceDialog Overview
---------------------------
-
-This dialog shows a list of choices, plus ``OK`` and (optionally) ``Cancel``. The user can select one or more of them.
+This dialog shows a list of choices, plus ``OK`` and (optionally)
+``Cancel``. The user can select one or more of them.
diff --git a/docs/sphinx/rest_substitutions/overviews/config_overview.rst b/docs/sphinx/rest_substitutions/overviews/config_overview.rst
index 0833b4eb..1527ec3b 100644
--- a/docs/sphinx/rest_substitutions/overviews/config_overview.rst
+++ b/docs/sphinx/rest_substitutions/overviews/config_overview.rst
@@ -3,42 +3,61 @@
.. _config overview:
-=================================================
+====================================
|phoenix_title| **Config Overview**
-=================================================
+====================================
-This overview briefly describes what the config classes are and what they are for. All the details about
-how to use them may be found in the description of the :ref:`ConfigBase` class and the documentation of
-the file, registry and INI file based implementations mentions all the features/limitations specific to
-each one of these versions.
+This overview briefly describes what the config classes are and what
+they are for. All the details about how to use them may be found in
+the description of the :ref:`wx.ConfigBase` class and the
+documentation of the file, registry and INI file based implementations
+mentions all the features/limitations specific to each one of these
+versions.
-The config classes provide a way to store some application configuration information. They were especially
-designed for this usage and, although may probably be used for many other things as well, should be limited
-to it. It means that this information should be:
+The config classes provide a way to store some application
+configuration information. They were especially designed for this
+usage and, although may probably be used for many other things as
+well, should be limited to it. It means that this information should
+be:
-- Typed, i.e. strings or numbers for the moment. You cannot store binary data, for example.
-- Small. For instance, it is not recommended to use the Windows registry for amounts of data more than a couple of kilobytes.
-- Not performance critical, neither from speed nor from a memory consumption point of view.
+- Typed, i.e. strings or numbers for the moment. You cannot store
+ binary data, for example.
+- Small. For instance, it is not recommended to use the Windows
+ registry for amounts of data more than a couple of kilobytes.
+- Not performance critical, neither from speed nor from a memory
+ consumption point of view.
-On the other hand, the features provided make them very useful for storing all kinds of small to medium volumes
-of hierarchically-organized, heterogeneous data. In short, this is a place where you can conveniently stuff
-all your data (numbers and strings) organizing it in a tree where you use the filesystem-like paths to
-specify the location of a piece of data. In particular, these classes were designed to be as easy to use as possible.
+On the other hand, the features provided make them very useful for
+storing all kinds of small to medium volumes of
+hierarchically-organized, heterogeneous data. In short, this is a
+place where you can conveniently stuff all your data (numbers and
+strings) organizing it in a tree where you use the filesystem-like
+paths to specify the location of a piece of data. In particular, these
+classes were designed to be as easy to use as possible.
-From another point of view, they provide an interface which hides the differences between the Windows registry
-and the standard Unix text format configuration files. Other (future) implementations of :ref:`ConfigBase` might
-also understand GTK resource files or their analogues on the KDE side.
+From another point of view, they provide an interface which hides the
+differences between the Windows registry and the standard Unix text
+format configuration files. Other (future) implementations
+of :ref:`wx.ConfigBase` might also understand GTK resource files or
+their analogues on the KDE side.
-In any case, each implementation of :ref:`ConfigBase` does its best to make the data look the same way everywhere.
-Due to limitations of the underlying physical storage, it may not implement 100% of the base class functionality.
+In any case, each implementation of :ref:`wx.ConfigBase` does its best
+to make the data look the same way everywhere. Due to limitations of
+the underlying physical storage, it may not implement 100% of the base
+class functionality.
-There are groups of entries and the entries themselves. Each entry contains either a string or a number (or a
-boolean value; support for other types of data such as dates or timestamps is planned) and is identified by
-the full path to it: something like ``/MyApp/UserPreferences/Colors/Foreground``.
+There are groups of entries and the entries themselves. Each entry
+contains either a string or a number (or a boolean value; support for
+other types of data such as dates or timestamps is planned) and is
+identified by the full path to it: something like
+``/MyApp/UserPreferences/Colors/Foreground``.
-The previous elements in the path are the group names, and each name may contain an arbitrary number of entries and subgroups.
+The previous elements in the path are the group names, and each name
+may contain an arbitrary number of entries and subgroups.
-The path components are always separated with a slash, even though some implementations use the backslash internally.
-Further details (including how to read/write these entries) may be found in the documentation for :ref:`ConfigBase`.
+The path components are always separated with a slash, even though
+some implementations use the backslash internally. Further details
+(including how to read/write these entries) may be found in the
+documentation for :ref:`wx.ConfigBase`.
diff --git a/docs/sphinx/rest_substitutions/overviews/dataobject_overview.rst b/docs/sphinx/rest_substitutions/overviews/dataobject_overview.rst
index 6c60dedd..6dcfcc22 100644
--- a/docs/sphinx/rest_substitutions/overviews/dataobject_overview.rst
+++ b/docs/sphinx/rest_substitutions/overviews/dataobject_overview.rst
@@ -3,47 +3,63 @@
.. _dataobject overview:
-=================================================
+========================================
|phoenix_title| **DataObject Overview**
-=================================================
+========================================
-This overview discusses data transfer through clipboard or drag and drop. In wxPython, these two ways to transfer
-data (either between different applications or inside one and the same) are very similar which allows to implement
-both of them using almost the same code - or, in other words, if you implement drag and drop support for your
+This overview discusses data transfer through clipboard or drag and
+drop. In wxPython, these two ways to transfer data (either between
+different applications or inside one and the same) are very similar
+which allows to implement both of them using almost the same code -
+or, in other words, if you implement drag and drop support for your
application, you get clipboard support for free and vice versa.
-At the heart of both clipboard and drag and drop operations lies the :class:`DataObject` class. The objects of this
-class (or, to be precise, classes derived from it) represent the data which is being carried by the mouse during
-drag and drop operation or copied to or pasted from the clipboard. :class:`DataObject` is a "smart" piece of data
-because it knows which formats it supports (see `GetFormatCount` and `GetAllFormats`) and knows how to render itself
-in any of them (see `GetDataHere`). It can also receive its value from the outside in a format it supports if it
-implements the `SetData` method. Please see the documentation of this class for more details.
+At the heart of both clipboard and drag and drop operations lies the
+:class:`wx.DataObject` class. The objects of this class (or, to be
+precise, classes derived from it) represent the data which is being
+carried by the mouse during drag and drop operation or copied to or
+pasted from the clipboard. :class:`wx.DataObject` is a "smart" piece of
+data because it knows which formats it supports (see `GetFormatCount`
+and `GetAllFormats`) and knows how to render itself in any of them
+(see `GetDataHere`). It can also receive its value from the outside in
+a format it supports if it implements the `SetData` method. Please see
+the documentation of this class for more details.
-Both clipboard and drag and drop operations have two sides: the source and target, the data provider and the data
-receiver. These which may be in the same application and even the same window when, for example, you drag some text
-from one position to another in a word processor. Let us describe what each of them should do.
+Both clipboard and drag and drop operations have two sides: the source
+and target, the data provider and the data receiver. These which may
+be in the same application and even the same window when, for example,
+you drag some text from one position to another in a word
+processor. Let us describe what each of them should do.
The data provider (source) duties
---------------------------------
-The data provider is responsible for creating a :class:`DataObject` containing the data to be transferred. Then it
-should either pass it to the clipboard using :meth:`Clipboard.SetData` function or to :class:`DropSource` and call
-:meth:`DropSource.DoDragDrop` function.
+The data provider is responsible for creating a :class:`wx.DataObject`
+containing the data to be transferred. Then it should either pass it
+to the clipboard using :meth:`wx.Clipboard.SetData` function or to
+:class:`wx.DropSource` and call :meth:`wx.DropSource.DoDragDrop` function.
-A small difference is that in the case of clipboard operation, the application usually knows in advance whether it
-copies or cuts (i.e. copies and deletes) data - in fact, this usually depends on which menu item the user chose.
-But for drag and drop it can only know it after :meth:`DropSource.DoDragDrop` returns (from its return value).
+A small difference is that in the case of clipboard operation, the
+application usually knows in advance whether it copies or cuts
+(i.e. copies and deletes) data - in fact, this usually depends on
+which menu item the user chose. But for drag and drop it can only
+know it after :meth:`wx.DropSource.DoDragDrop` returns (from its return
+value).
The data receiver (target) duties
---------------------------------
-To receive (paste in usual terminology) data from the clipboard, you should create a :class:`DataObject` derived
-class which supports the data formats you need and pass it as argument to :meth:`Clipboard.GetData`. If it returns
-``False``, no data in (any of) the supported format(s) is available. If it returns ``True``, the data has been
-successfully transferred to :class:`DataObject`.
+To receive (paste in usual terminology) data from the clipboard, you
+should create a :class:`wx.DataObject` derived class which supports the
+data formats you need and pass it as argument to
+:meth:`wx.Clipboard.GetData`. If it returns ``False``, no data in (any
+of) the supported format(s) is available. If it returns ``True``, the
+data has been successfully transferred to :class:`wx.DataObject`.
-For drag and drop case, the :meth:`DropTarget.OnData` virtual function will be called when a data object is dropped,
-from which the data itself may be requested by calling :meth:`DropTarget.GetData` method which fills the data object.
+For drag and drop case, the :meth:`wx.DropTarget.OnData` virtual function
+will be called when a data object is dropped, from which the data
+itself may be requested by calling :meth:`wx.DropTarget.GetData` method
+which fills the data object.
diff --git a/docs/sphinx/rest_substitutions/overviews/datetime_overview.rst b/docs/sphinx/rest_substitutions/overviews/datetime_overview.rst
index 13675878..bdb56655 100644
--- a/docs/sphinx/rest_substitutions/overviews/datetime_overview.rst
+++ b/docs/sphinx/rest_substitutions/overviews/datetime_overview.rst
@@ -10,65 +10,99 @@
Introduction
------------
-wxPython provides a set of powerful classes to work with dates and times. Some of the supported features of :ref:`DateTime` class are:
+wxPython provides a set of powerful classes to work with dates and
+times. Some of the supported features of :ref:`wx.DateTime` class are:
-* Wide range: the range of supported dates goes from about 4714 B.C. to some 480 million years in the future.
-* Precision: not using floating point calculations anywhere ensures that the date calculations don't suffer from rounding errors.
-* Many features: not only all usual calculations with dates are supported, but also more exotic week and year day calculations,
- work day testing, standard astronomical functions, conversion to and from strings in either strict or free format.
-* Efficiency: objects of :ref:`DateTime` are small (8 bytes) and working with them is fast.
+* Wide range: the range of supported dates goes from about 4714
+ B.C. to some 480 million years in the future.
+
+* Precision: not using floating point calculations anywhere ensures
+ that the date calculations don't suffer from rounding errors.
+
+* Many features: not only all usual calculations with dates are
+ supported, but also more exotic week and year day calculations, work
+ day testing, standard astronomical functions, conversion to and from
+ strings in either strict or free format.
+
+* Efficiency: objects of :ref:`wx.DateTime` are small (8 bytes) and
+ working with them is fast.
All date/time classes at a glance
---------------------------------
-There are 3 main classes related to date and time: except :ref:`DateTime` itself which represents an absolute moment in time,
-there are also two classes - :ref:`TimeSpan` and :ref:`DateSpan` - which represent the intervals of time.
+There are 3 main classes related to date and time: except
+:ref:`wx.DateTime` itself which represents an absolute moment in time,
+there are also two classes - :ref:`wx.TimeSpan` and :ref:`wx.DateSpan` -
+which represent the intervals of time.
DateTime characteristics
------------------------
-:ref:`DateTime` stores the time as a signed number of milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 - however
-this is not visible to the class users (in particular, dates prior to the Epoch are handled just as well (or as bad) as the dates after it).
-But it does mean that the best resolution which can be achieved with this class is 1 millisecond.
+:ref:`wx.DateTime` stores the time as a signed number of milliseconds
+since the Epoch which is fixed, by convention, to Jan 1, 1970 -
+however this is not visible to the class users (in particular, dates
+prior to the Epoch are handled just as well (or as bad) as the dates
+after it). But it does mean that the best resolution which can be
+achieved with this class is 1 millisecond.
-The size of :ref:`DateTime` object is 8 bytes because it is represented as a 64 bit integer. The resulting range of supported dates is
-thus approximatively 580 million years, but due to the current limitations in the Gregorian calendar support, only dates from Nov 24, 4714BC
-are supported (this is subject to change if there is sufficient interest in doing it).
+The size of :ref:`wx.DateTime` object is 8 bytes because it is
+represented as a 64 bit integer. The resulting range of supported
+dates is thus approximatively 580 million years, but due to the
+current limitations in the Gregorian calendar support, only dates from
+Nov 24, 4714BC are supported (this is subject to change if there is
+sufficient interest in doing it).
-Finally, the internal representation is time zone independent (always in GMT) and the time zones only come into play when a date is broken
-into year/month/day components. See more about timezones below (see :ref:`Time zone considerations