Lerking/Phoenix
1
0
Fork 0
mirror of https://github.com/wxWidgets/Phoenix.git synced 2026-01-07 20:40:11 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

first batch of overview file updates, reformatting and name fixes

Browse Source
This commit is contained in:
Robin Dunn
2016-05-26 00:01:50 -07:00
parent 62609f66da
commit eeec9c5a41
14 changed files with 813 additions and 513 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/sphinx/_templates/main.html
View File

@@ -18,6 +18,8 @@
<br>
<h2>API Modules</h2>
<table class="contentstable" align="center" style="margin-left: 25px">
<tr>
<td width="50%" valign="top">

251
docs/sphinx/rest_substitutions/overviews/DocstringsGuidelines.rst
View File

@@ -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 <http://sphinx.pocoo.org/domains.html#info-field-lists>`_
@@ -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 <http://sphinx.pocoo.org/markup/para.html>`_
@@ -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 <andrea.gavana@gmail.com>`_ e-mail address or
you can submit the sample snippets to the `wxWidgets/Phoenix Github repository <https://github.com/wxWidgets/Phoenix>`_.
The snippets should be placed in the source tree in this folder:
Please do submit the sample snippets to the
`wxWidgets/Phoenix Github repository <https://github.com/wxWidgets/Phoenix>`_
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 <andrea.gavana@gmail.com>`_ e-mail address or
you can submit the screenshots to the `wxWidgets/Phoenix Github repository <https://github.com/wxWidgets/Phoenix>`_.
The screenshots should be placed in the source tree in this folder:
Please submit the screenshots to the
`wxWidgets/Phoenix Github repository <https://github.com/wxWidgets/Phoenix>`_
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.

63
docs/sphinx/rest_substitutions/overviews/app_overview.rst
View File

@@ -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 <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 <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.

106
docs/sphinx/rest_substitutions/overviews/bitmap_overview.rst
View File

@@ -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``)

32
docs/sphinx/rest_substitutions/overviews/bookctrl_overview.rst
View File

@@ -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

69
docs/sphinx/rest_substitutions/overviews/command_overview.rst
View File

@@ -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``.

161
docs/sphinx/rest_substitutions/overviews/common_dialogs_overview.rst
View File

@@ -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 <printing framework overview>` for an example.
.. seealso:: :ref:`Printing Framework Overview <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.

73
docs/sphinx/rest_substitutions/overviews/config_overview.rst
View File

@@ -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`.

68
docs/sphinx/rest_substitutions/overviews/dataobject_overview.rst
View File

@@ -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.

206
docs/sphinx/rest_substitutions/overviews/datetime_overview.rst
View File

@@ -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 <time zone considerations>`).
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 <time zone considerations>`).
Currently, the only supported calendar is Gregorian one (which is used even for the dates prior to the historic introduction of this calendar
which was first done on Oct 15, 1582 but is, generally speaking, country, and even region, dependent). Future versions will probably have
Julian calendar support as well and support for other calendars (Maya, Hebrew, Chinese...) is not ruled out.
Currently, the only supported calendar is Gregorian one (which is used
even for the dates prior to the historic introduction of this calendar
which was first done on Oct 15, 1582 but is, generally speaking,
country, and even region, dependent). Future versions will probably
have Julian calendar support as well and support for other calendars
(Maya, Hebrew, Chinese...) is not ruled out.
Difference between DateSpan and TimeSpan
----------------------------------------
While there is only one logical way to represent an absolute moment in the time (and hence only one :ref:`DateTime` class), there are at
While there is only one logical way to represent an absolute moment in
the time (and hence only one :ref:`wx.DateTime` class), there are at
least two methods to describe a time interval.
First, there is the direct and self-explaining way implemented by :ref:`TimeSpan`: it is just a difference in milliseconds between two
moments in time. Adding or subtracting such an interval to :ref:`DateTime` is always well-defined and is a fast operation.
First, there is the direct and self-explaining way implemented by
:ref:`wx.TimeSpan`: it is just a difference in milliseconds between two
moments in time. Adding or subtracting such an interval to
:ref:`wx.DateTime` is always well-defined and is a fast operation.
But in the daily life other, calendar-dependent time interval specifications are used. For example, 'one month later' is commonly used.
However, it is clear that this is not the same as :ref:`TimeSpan` of 60*60*24*31 seconds because 'one month later' Feb 15 is Mar 15 and
not Mar 17 or Mar 16 (depending on whether the year is leap or not).
But in the daily life other, calendar-dependent time interval
specifications are used. For example, 'one month later' is commonly
used. However, it is clear that this is not the same as
:ref:`wx.TimeSpan` of 60\*60\*24\*31 seconds because 'one month later'
Feb 15 is Mar 15 and not Mar 17 or Mar 16 (depending on whether the
year is leap or not).
This is why there is another class for representing such intervals called :ref:`DateSpan`. It handles these sort of operations in the
most natural way possible, but note that manipulating with intervals of this kind is not always well-defined. Consider, for example,
Jan 31 + '1 month': this will give Feb 28 (or 29), i.e. the last day of February and not the non-existent Feb 31. Of course, this is
what is usually wanted, but you still might be surprised to notice that now subtracting back the same interval from Feb 28 will result
in Jan 28 and **not** Jan 31 we started with!
This is why there is another class for representing such intervals
called :ref:`wx.DateSpan`. It handles these sort of operations in the
most natural way possible, but note that manipulating with intervals
of this kind is not always well-defined. Consider, for example, Jan 31
+ '1 month': this will give Feb 28 (or 29), i.e. the last day of
February and not the non-existent Feb 31. Of course, this is what is
usually wanted, but you still might be surprised to notice that now
subtracting back the same interval from Feb 28 will result in Jan 28
and **not** Jan 31 we started with!
So, unless you plan to implement some kind of natural language parsing in the program, you should probably use :ref:`TimeSpan` instead
of :ref:`DateSpan` (which is also more efficient). However, :ref:`DateSpan` may be very useful in situations when you do need to
So, unless you plan to implement some kind of natural language parsing
in the program, you should probably use :ref:`wx.TimeSpan` instead of
:ref:`wx.DateSpan` (which is also more efficient). However,
:ref:`wx.DateSpan` may be very useful in situations when you do need to
understand what 'in a month' means - of course, it is just::
wx.DateTime.Now() + wx.DateSpan.Month()
@@ -79,26 +113,36 @@ understand what 'in a month' means - of course, it is just::
Date arithmetics
----------------
Many different operations may be performed with the dates, however not all of them make sense. For example, multiplying a date by a number
is an invalid operation, even though multiplying either of the time span classes by a number is perfectly valid.
Many different operations may be performed with the dates, however not
all of them make sense. For example, multiplying a date by a number is
an invalid operation, even though multiplying either of the time span
classes by a number is perfectly valid.
Here is what can be done:
* **Addition**: a :ref:`TimeSpan` or :ref:`DateSpan` can be added to :ref:`DateTime` resulting in a new :ref:`DateTime` object and also
2 objects of the same span class can be added together giving another object of the same class.
* **Addition**: a :ref:`wx.TimeSpan` or :ref:`wx.DateSpan` can be added to
:ref:`wx.DateTime` resulting in a new :ref:`wx.DateTime` object and also 2
objects of the same span class can be added together giving another
object of the same class.
* **Subtraction**: the same types of operations as above are allowed and, additionally, a difference between two :ref:`DateTime` objects
can be taken and this will yield :ref:`TimeSpan`.
* **Subtraction**: the same types of operations as above are allowed
and, additionally, a difference between two :ref:`wx.DateTime` objects
can be taken and this will yield :ref:`wx.TimeSpan`.
* **Multiplication**: a :ref:`TimeSpan` or :ref:`DateSpan` object can be multiplied by an integer number resulting in an object of the same type.
* **Multiplication**: a :ref:`wx.TimeSpan` or :ref:`wx.DateSpan` object can
be multiplied by an integer number resulting in an object of the
same type.
* **Unary minus**: a :ref:`TimeSpan` or :ref:`DateSpan` object may finally be negated giving an interval of the same magnitude but of opposite time direction.
* **Unary minus**: a :ref:`wx.TimeSpan` or :ref:`wx.DateSpan` object may
finally be negated giving an interval of the same magnitude but of
opposite time direction.
For all these operations there are corresponding global (overloaded) operators and also member functions which are synonyms for them:
`Add()`, `Subtract()` and `Multiply()`. Unary minus as well as composite assignment operations (like +=) are only implemented as members and
`Neg()` is the synonym for unary minus.
For all these operations there are corresponding global (overloaded)
operators and also member functions which are synonyms for them:
`Add()`, `Subtract()` and `Multiply()`. Unary minus as well as
composite assignment operations (like +=) are only implemented as
members and `Neg()` is the synonym for unary minus.
@@ -107,37 +151,54 @@ For all these operations there are corresponding global (overloaded) operators a
Time zone considerations
------------------------
Although the time is always stored internally in GMT, you will usually work in the local time zone. Because of this, all :ref:`DateTime`
constructors and setters which take the broken down date assume that these values are for the local time zone. Thus::
Although the time is always stored internally in GMT, you will usually
work in the local time zone. Because of this, all :ref:`wx.DateTime`
constructors and setters which take the broken down date assume that
these values are for the local time zone. Thus::
wx.DateTimeFromDMY(1, wx.DateTime.Jan, 1970)
will not correspond to the :ref:`DateTime` Epoch unless you happen to live in the UK. All methods returning the date components (year,
month, day, hour, minute, second...) will also return the correct values for the local time zone by default, so, generally, doing the natural
things will lead to natural and correct results.
will not correspond to the :ref:`wx.DateTime` Epoch unless you happen
to live in the UK. All methods returning the date components (year,
month, day, hour, minute, second...) will also return the correct
values for the local time zone by default, so, generally, doing the
natural things will lead to natural and correct results.
If you only want to do this, you may safely skip the rest of this section. However, if you want to work with different time zones, you
If you only want to do this, you may safely skip the rest of this
section. However, if you want to work with different time zones, you
should read it to the end.
In this (rare) case, you are still limited to the local time zone when constructing :ref:`DateTime` objects, i.e. there is no way to construct
a :ref:`DateTime` corresponding to the given date in, say, Pacific Standard Time. To do it, you will need to call :meth:`DateTime.ToTimezone`
or :meth:`DateTime.MakeTimezone` methods to adjust the date for the target time zone. There are also special versions of these functions
:meth:`DateTime.ToUTC` and :meth:`DateTime.MakeUTC` for the most common case - when the date should be constructed in UTC.
In this (rare) case, you are still limited to the local time zone when
constructing :ref:`wx.DateTime` objects, i.e. there is no way to
construct a :ref:`wx.DateTime` corresponding to the given date in,
say, Pacific Standard Time. To do it, you will need to call
:meth:`wx.DateTime.ToTimezone` or :meth:`wx.DateTime.MakeTimezone`
methods to adjust the date for the target time zone. There are also
special versions of these functions :meth:`wx.DateTime.ToUTC` and
:meth:`wx.DateTime.MakeUTC` for the most common case - when the date
should be constructed in UTC.
You also can just retrieve the value for some time zone without converting the object to it first. For this you may pass TimeZone argument to
any of the methods which are affected by the time zone (all methods getting date components and the date formatting ones, for example).
In particular, the `Format()` family of methods accepts a TimeZone parameter and this allows to simply print time in any time zone.
You also can just retrieve the value for some time zone without
converting the object to it first. For this you may pass TimeZone
argument to any of the methods which are affected by the time zone
(all methods getting date components and the date formatting ones, for
example). In particular, the `Format()` family of methods accepts a
TimeZone parameter and this allows to simply print time in any time
zone.
To see how to do it, the last issue to address is how to construct a TimeZone object which must be passed to all these methods. First of all,
you may construct it manually by specifying the time zone offset in seconds from GMT, but usually you will just use one of the
:ref:`Date and Time <date and time>` and let the conversion constructor do the job.
To see how to do it, the last issue to address is how to construct a
TimeZone object which must be passed to all these methods. First of
all, you may construct it manually by specifying the time zone offset
in seconds from GMT, but usually you will just use one of the
:ref:`Date and Time <date and time>` and let the conversion
constructor do the job.
I.e. you would just write::
dt = wx.DateTimeFromDMY(8, wx.DateTime.May, 1977)
print "The time is %s in local time zone" % dt.FormatTime()
print "The time is %s in GMT" % dt.FormatTime(wx.DateTime.GMT)
print("The time is %s in local time zone" % dt.FormatTime())
print("The time is %s in GMT" % dt.FormatTime(wx.DateTime.GMT))
@@ -146,16 +207,23 @@ I.e. you would just write::
Daylight saving time (DST)
--------------------------
DST (a.k.a. 'summer time') handling is always a delicate task which is better left to the operating system which is supposed to be configured
by the administrator to behave correctly. Unfortunately, when doing calculations with date outside of the range supported by the standard
DST (a.k.a. 'summer time') handling is always a delicate task which is
better left to the operating system which is supposed to be configured
by the administrator to behave correctly. Unfortunately, when doing
calculations with date outside of the range supported by the standard
library, we are forced to deal with these issues ourselves.
Several functions are provided to calculate the beginning and end of DST in the given year and to determine whether it is in effect at the
given moment or not, but they should not be considered as absolutely correct because, first of all, they only work more or less correctly
for only a handful of countries (any information about other ones appreciated!) and even for them the rules may perfectly well change in the future.
Several functions are provided to calculate the beginning and end of
DST in the given year and to determine whether it is in effect at the
given moment or not, but they should not be considered as absolutely
correct because, first of all, they only work more or less correctly
for only a handful of countries (any information about other ones
appreciated!) and even for them the rules may perfectly well change in
the future.
The time zone handling methods (see :ref:`Time zone considerations <time zone considerations>`) use these functions too, so they are subject
to the same limitations.
The time zone handling methods (see :ref:`Time zone considerations
<time zone considerations>`) use these functions too, so they are
subject to the same limitations.

47
docs/sphinx/rest_substitutions/overviews/dc_overview.rst
View File

@@ -3,36 +3,49 @@
.. _device contexts:
===============================================
====================================
|phoenix_title| **Device Contexts**
===============================================
====================================
A :ref:`DC` is a device context onto which graphics and text can be drawn. The device context is intended to represent
a number of output devices in a generic way, with the same API being used throughout.
A :ref:`wx.DC` is a device context onto which graphics and text can be
drawn. The device context is intended to represent a number of output
devices in a generic way, with the same API being used throughout.
Some device contexts are created temporarily in order to draw on a window. This is true of :ref:`ScreenDC`, :ref:`ClientDC`,
:ref:`PaintDC`, and :ref:`WindowDC`. The following describes the differences between these device contexts and when you should use them.
Some device contexts are created temporarily in order to draw on a
window. This is true of :ref:`wx.ScreenDC`, :ref:`wx.ClientDC`,
:ref:`wx.PaintDC`, and :ref:`wx.WindowDC`. The following describes the
differences between these device contexts and when you should use
them.
- :ref:`ScreenDC`. Use this to paint on the screen, as opposed to an individual window.
- :ref:`ClientDC`. Use this to paint on the client area of window (the part without borders and other decorations), but do not use
it from within an :ref:`PaintEvent`.
- :ref:`PaintDC`. Use this to paint on the client area of a window, but only from within a :ref:`PaintEvent`.
- :ref:`WindowDC`. Use this to paint on the whole area of a window, including decorations. This may not be available on non-Windows platforms.
- :ref:`wx.ScreenDC`. Use this to paint on the screen, as opposed to an
individual window.
- :ref:`wx.ClientDC`. Use this to paint on the client area of window (the
part without borders and other decorations), but do not use it from
within an :ref:`wx.PaintEvent`.
- :ref:`wx.PaintDC`. Use this to paint on the client area of a window,
but only from within a :ref:`wx.PaintEvent`.
- :ref:`wx.WindowDC`. Use this to paint on the whole area of a window,
including decorations. This may not be available on non-Windows
platforms.
To use a client, paint or window device context, create an object on the stack with the window as argument, for example::
To use a client, paint or window device context, create an object on
the stack with the window as argument, for example::
def OnMyCmd(self, event):
dc = wx.ClientDC(window)
DrawMyPicture(dc)
Try to write code so it is parameterised by :ref:`DC` - if you do this, the same piece of code may write to a number of different devices,
by passing a different device context. This doesn't work for everything (for example not all device contexts support bitmap drawing)
but will work most of the time.
Try to write code so it is parameterised by :ref:`wx.DC` - if you do
this, the same piece of code may write to a number of different
devices, by passing a different device context. This doesn't work for
everything (for example not all device contexts support bitmap
drawing) but will work most of the time.

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

@@ -8,15 +8,21 @@
====================================
A dialog box is similar to a panel, in that it is a window which can be used for placing controls, with the following exceptions:
A dialog box is similar to a panel, in that it is a window which can
be used for placing controls, with the following exceptions:
- A surrounding frame is implicitly created.
- Extra functionality is automatically given to the dialog box, such as tabbing between items (currently Windows only).
- If the dialog box is `modal`, the calling program is blocked until the dialog box is dismissed.
- Extra functionality is automatically given to the dialog box, such
as tabbing between items (currently Windows only).
- If the dialog box is `modal`, the calling program is blocked until
the dialog box is dismissed.
.. seealso:: :ref:`TopLevelWindow` and :ref:`Window` for inherited member functions. Validation of data in controls is covered in
:ref:`Validator Overview <validator overview>`.
.. seealso:: :ref:`wx.TopLevelWindow` and :ref:`wx.Window` for inherited
member functions. Validation of data in controls is covered in
:ref:`Validator Overview <validator overview>`.
.. _automatic scrolling dialogs:
@@ -25,29 +31,55 @@ A dialog box is similar to a panel, in that it is a window which can be used for
Automatic scrolling dialogs
---------------------------
As an ever greater variety of mobile hardware comes to market, it becomes more imperative for wxPython applications to adapt to
these platforms without putting too much burden on the programmer. One area where wxPython can help is in adapting dialogs for
the lower resolution screens that inevitably accompany a smaller form factor. :ref:`Dialog` therefore supplies a global
:ref:`DialogLayoutAdapter` class that implements automatic scrolling adaptation for most sizer-based custom dialogs.
As an ever greater variety of mobile hardware comes to market, it
becomes more imperative for wxPython applications to adapt to these
platforms without putting too much burden on the programmer. One area
where wxPython can help is in adapting dialogs for the lower
resolution screens that inevitably accompany a smaller form
factor. :ref:`wx.Dialog` therefore supplies a global
:ref:`wx.DialogLayoutAdapter` class that implements automatic scrolling
adaptation for most sizer-based custom dialogs.
Many applications should therefore be able to adapt to small displays with little or no work, as far as dialogs are concerned.
By default this adaptation is off. To switch scrolling adaptation on globally in your application, call the static function
:meth:`Dialog.EnableLayoutAdaptation` passing ``True``. You can also adjust adaptation on a per-dialog basis by calling
:meth:`Dialog.SetLayoutAdaptationMode` with one of ``DIALOG_ADAPTATION_MODE_DEFAULT`` (use the global setting), ``DIALOG_ADAPTATION_MODE_ENABLED``
or ``DIALOG_ADAPTATION_MODE_DISABLED``.
Many applications should therefore be able to adapt to small displays
with little or no work, as far as dialogs are concerned. By default
this adaptation is off. To switch scrolling adaptation on globally in
your application, call the static function
:meth:`wx.Dialog.EnableLayoutAdaptation` passing ``True``. You can also
adjust adaptation on a per-dialog basis by calling
:meth:`wx.Dialog.SetLayoutAdaptationMode` with one of
``wx.DIALOG_ADAPTATION_MODE_DEFAULT`` (use the global setting),
``wx.DIALOG_ADAPTATION_MODE_ENABLED`` or
``wx.DIALOG_ADAPTATION_MODE_DISABLED``.
The last two modes override the global adaptation setting. With adaptation enabled, if the display size is too small for the dialog,
wxPython (or rather the standard adapter class :ref:`StandardDialogLayoutAdapter`) will make part of the dialog scrolling, leaving
standard buttons in a non-scrolling part at the bottom of the dialog. This is done as follows, in :meth:`DialogLayoutAdapter.DoLayoutAdaptation`
called from within :meth:`Dialog.Show` or :meth:`Dialog.ShowModal`:
The last two modes override the global adaptation setting. With
adaptation enabled, if the display size is too small for the dialog,
wxPython (or rather the standard adapter class
:ref:`wx.StandardDialogLayoutAdapter`) will make part of the dialog
scrolling, leaving standard buttons in a non-scrolling part at the
bottom of the dialog. This is done as follows, in
:meth:`wx.DialogLayoutAdapter.DoLayoutAdaptation` called from within
:meth:`wx.Dialog.Show` or :meth:`wx.Dialog.ShowModal`:
- If :meth:`Dialog.GetContentWindow` returns a window derived from :ref:`BookCtrlBase`, the pages are made scrollable and no other adaptation is done.
- wxPython looks for a :ref:`StdDialogButtonSizer` and uses it for the non-scrolling part.
- If that search failed, wxPython looks for a horizontal :ref:`BoxSizer` with one or more standard buttons, with identifiers such as ``ID_OK`` and ``ID_CANCEL``.
- If that search failed too, wxPython finds 'loose' standard buttons (in any kind of sizer) and adds them to a :ref:`StdDialogButtonSizer`.
If no standard buttons were found, the whole dialog content will scroll.
- All the children apart from standard buttons are reparented onto a new :ref:`ScrolledWindow` object, using the old top-level sizer
for the scrolled window and creating a new top-level sizer to lay out the scrolled window and standard button sizer.
- If :meth:`wx.Dialog.GetContentWindow` returns a window derived from
:ref:`wx.BookCtrlBase`, the pages are made scrollable and no other
adaptation is done.
- wxPython looks for a :ref:`wx.StdDialogButtonSizer` and uses it for the
non-scrolling part.
- If that search failed, wxPython looks for a horizontal
:ref:`wx.BoxSizer` with one or more standard buttons, with identifiers
such as ``wx.ID_OK`` and ``wx.ID_CANCEL``.
- If that search failed too, wxPython finds 'loose' standard buttons
(in any kind of sizer) and adds them to a
:ref:`wx.StdDialogButtonSizer`. If no standard buttons were found, the
whole dialog content will scroll.
- All the children apart from standard buttons are reparented onto a
new :ref:`wx.ScrolledWindow` object, using the old top-level sizer for
the scrolled window and creating a new top-level sizer to lay out
the scrolled window and standard button sizer.
.. _layout adaptation code:
@@ -55,48 +87,83 @@ called from within :meth:`Dialog.Show` or :meth:`Dialog.ShowModal`:
Customising scrolling adaptation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In addition to switching adaptation on and off globally and per dialog, you can choose how aggressively wxPython will search
for standard buttons by setting :meth:`Dialog.SetLayoutAdaptationLevel`. By default, all the steps described above will be
performed but by setting the level to 1, for example, you can choose to only look for :ref:`StdDialogButtonSizer`.
In addition to switching adaptation on and off globally and per
dialog, you can choose how aggressively wxPython will search for
standard buttons by setting
:meth:`wx.Dialog.SetLayoutAdaptationLevel`. By default, all the steps
described above will be performed but by setting the level to 1, for
example, you can choose to only look for :ref:`wx.StdDialogButtonSizer`.
You can use :meth:`Dialog.AddMainButtonId` to add identifiers for buttons that should also be treated as standard buttons for the non-scrolling area.
You can use :meth:`wx.Dialog.AddMainButtonId` to add identifiers for
buttons that should also be treated as standard buttons for the
non-scrolling area.
You can derive your own class from :ref:`DialogLayoutAdapter` or :ref:`StandardDialogLayoutAdapter` and call :meth:`Dialog.SetLayoutAdapter`,
deleting the old object that this function returns. Override the functions `CanDoLayoutAdaptation` and `DoLayoutAdaptation` to test
for adaptation applicability and perform the adaptation.
You can derive your own class from :ref:`wx.DialogLayoutAdapter` or
:ref:`wx.StandardDialogLayoutAdapter` and call
:meth:`wx.Dialog.SetLayoutAdapter`, deleting the old object that this
function returns. Override the functions `CanDoLayoutAdaptation` and
`DoLayoutAdaptation` to test for adaptation applicability and perform
the adaptation.
You can also override :meth:`Dialog.CanDoLayoutAdaptation` and :meth:`Dialog.DoLayoutAdaptation` in a class derived from :ref:`Dialog`.
You can also override :meth:`wx.Dialog.CanDoLayoutAdaptation` and
:meth:`wx.Dialog.DoLayoutAdaptation` in a class derived from
:ref:`wx.Dialog`.
Situations where automatic scrolling adaptation may fail
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof, and may fail in the following situations:
Because adaptation rearranges your sizer and window hierarchy, it is
not fool-proof, and may fail in the following situations:
- The dialog doesn't use sizers.
- The dialog implementation makes assumptions about the window hierarchy, for example getting the parent of a control and casting to the dialog class.
- The dialog does custom painting and/or event handling not handled by the scrolled window. If this problem can be solved globally,
you can derive a new adapter class from :ref:`StandardDialogLayoutAdapter` and override its `CreateScrolledWindow` function
to return an instance of your own class.
- The dialog has unusual layout, for example a vertical sizer containing a mixture of standard buttons and other controls.
- The dialog makes assumptions about the sizer hierarchy, for example to show or hide children of the top-level sizer. However,
the original sizer hierarchy will still hold until `Show` or `ShowModal` is called.
- The dialog implementation makes assumptions about the window
hierarchy, for example getting the parent of a control and casting
to the dialog class.
- The dialog does custom painting and/or event handling not handled by
the scrolled window. If this problem can be solved globally, you can
derive a new adapter class from :ref:`wx.StandardDialogLayoutAdapter`
and override its `CreateScrolledWindow` function to return an
instance of your own class.
- The dialog has unusual layout, for example a vertical sizer
containing a mixture of standard buttons and other controls.
- The dialog makes assumptions about the sizer hierarchy, for example
to show or hide children of the top-level sizer. However, the
original sizer hierarchy will still hold until `Show` or `ShowModal`
is called.
You can help make sure that your dialogs will continue to function after adaptation by:
You can help make sure that your dialogs will continue to function
after adaptation by:
- Avoiding the above situations and assumptions;
- Using :ref:`StdDialogButtonSizer`;
- Only making assumptions about hierarchy immediately after the dialog is created;
- Using an intermediate sizer under the main sizer, a false top-level sizer that can be relied on to exist for the purposes of manipulating child sizers and windows;
- Overriding :meth:`Dialog.GetContentWindow` to return a book control if your dialog implements pages: wxPython will then only make the pages scrollable.
- Using :ref:`wx.StdDialogButtonSizer`;
- Only making assumptions about hierarchy immediately after the dialog
is created;
- Using an intermediate sizer under the main sizer, a false top-level
sizer that can be relied on to exist for the purposes of
manipulating child sizers and windows;
- Overriding :meth:`wx.Dialog.GetContentWindow` to return a book control
if your dialog implements pages: wxPython will then only make the
pages scrollable.
PropertySheetDialog and Wizard
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Adaptation for :ref:`PropertySheetDialog` is always done by simply making the pages scrollable, since :meth:`Dialog.GetContentWindow` returns the dialog's
book control and this is handled by the standard layout adapter.
Adaptation for :ref:`wx.PropertySheetDialog` is always done by simply
making the pages scrollable, since :meth:`wx.Dialog.GetContentWindow`
returns the dialog's book control and this is handled by the standard
layout adapter.
:class:`~adv.Wizard` uses its own `CanDoLayoutAdaptation` and `DoLayoutAdaptation` functions rather than the global adapter: again, only the wizard pages are made scrollable.
:class:`wx.adv.Wizard` uses its own `CanDoLayoutAdaptation` and
`DoLayoutAdaptation` functions rather than the global adapter: again,
only the wizard pages are made scrollable.

75
docs/sphinx/rest_substitutions/overviews/dnd_overview.rst
View File

@@ -3,27 +3,30 @@
.. _drag and drop overview:
=================================================
===========================================
|phoenix_title| **Drag and Drop Overview**
=================================================
===========================================
It may be noted that data transfer to and from the clipboard is quite similar to data transfer
with drag and drop and the code to implement these two types is almost the same. In particular,
both data transfer mechanisms store data in some kind of :ref:`DataObject` and identify its format(s) using
the :ref:`DataFormat` class.
It may be noted that data transfer to and from the clipboard is quite
similar to data transfer with drag and drop and the code to implement
these two types is almost the same. In particular, both data transfer
mechanisms store data in some kind of :ref:`wx.DataObject` and identify
its format(s) using the :ref:`wx.DataFormat` class.
To be a `drag` source, i.e. to provide the data which may be dragged by the user elsewhere, you
should implement the following steps:
To be a `drag` source, i.e. to provide the data which may be dragged
by the user elsewhere, you should implement the following steps:
- **Preparation**: First of all, a data object must be created and initialized with the data you wish to drag. For example::
- **Preparation**: First of all, a data object must be created and
initialized with the data you wish to drag. For example::
my_data = wx.TextDataObject("This text will be dragged.")
- **Drag start**: To start the dragging process (typically in response to a mouse click) you must call
:meth:`DropSource.DoDragDrop` like this::
- **Drag start**: To start the dragging process (typically in response
to a mouse click) you must call :meth:`wx.DropSource.DoDragDrop` like
this::
dragSource = wx.DropSource(self)
dragSource.SetData(my_data)
@@ -31,12 +34,17 @@ should implement the following steps:
- **Dragging**: The call to `DoDragDrop()` blocks the program until the user releases the mouse button (unless
you override the :meth:`DropSource.GiveFeedback` function to do something special). When the mouse moves in
a window of a program which understands the same drag-and-drop protocol (any program under Windows or any
program supporting the XDnD protocol under X Windows), the corresponding :ref:`DropTarget` methods are called - see below.
- **Dragging**: The call to `DoDragDrop()` blocks the program until
the user releases the mouse button (unless you override the
:meth:`wx.DropSource.GiveFeedback` function to do something
special). When the mouse moves in a window of a program which
understands the same drag-and-drop protocol (any program under
Windows or any program supporting the XDnD protocol under X
Windows), the corresponding :ref:`wx.DropTarget` methods are called -
see below.
- **Processing the result**: `DoDragDrop()` returns an effect code which is one of the values of :ref:`DragResult`::
- **Processing the result**: `DoDragDrop()` returns an effect code
which is one of the values of :ref:`wx.DragResult`::
if result == wx.DragCopy:
# Copy the data
@@ -51,20 +59,31 @@ should implement the following steps:
pass
To be a `drop` target, i.e. to receive the data dropped by the user you should follow the instructions below:
To be a `drop` target, i.e. to receive the data dropped by the user
you should follow the instructions below:
- **Initialization**: For a window to be a drop target, it needs to have an associated :ref:`DropTarget` object. Normally,
you will call :meth:`Window.SetDropTarget` during window creation associating your drop target with it. You must
derive a class from :ref:`DropTarget` and override its pure virtual methods. Alternatively, you may derive
from :ref:`TextDropTarget` or :ref:`FileDropTarget` and override their `OnDropText()` or `OnDropFiles()` method.
- **Initialization**: For a window to be a drop target, it needs to
have an associated :ref:`wx.DropTarget` object. Normally, you will
call :meth:`wx.Window.SetDropTarget` during window creation
associating your drop target with it. You must derive a class from
:ref:`wx.DropTarget` and override its pure virtual
methods. Alternatively, you may derive from :ref:`wx.TextDropTarget`
or :ref:`wx.FileDropTarget` and override their `OnDropText()` or
`OnDropFiles()` method.
- **Drop**: When the user releases the mouse over a window, wxPython asks the associated :ref:`DropTarget` object if
it accepts the data. For this, a :ref:`DataObject` must be associated with the drop target and this data object
will be responsible for the format negotiation between the drag source and the drop target. If all goes well,
then :meth:`DropTarget.OnData` will get called and the :ref:`DataObject` belonging to the drop target can get filled with data.
- **Drop**: When the user releases the mouse over a window, wxPython
asks the associated :ref:`wx.DropTarget` object if it accepts the
data. For this, a :ref:`wx.DataObject` must be associated with the
drop target and this data object will be responsible for the format
negotiation between the drag source and the drop target. If all goes
well, then :meth:`wx.DropTarget.OnData` will get called and the
:ref:`wx.DataObject` belonging to the drop target can get filled
with data.
- **The end**: After processing the data, `DoDragDrop()` returns either ``DragCopy`` or ``DragMove`` depending on the
state of the keys ``Ctrl``, ``Shift`` and ``Alt`` at the moment of the drop. There is currently no way for
the drop target to change this return code.
- **The end**: After processing the data, `DoDragDrop()` returns
either ``wx.DragCopy`` or ``wx.DragMove`` depending on the state of
the keys ``Ctrl``, ``Shift`` and ``Alt`` at the moment of the
drop. There is currently no way for the drop target to change this
return code.

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

@@ -101,9 +101,9 @@ Meanwhile, here are some important links:
out.
* Source code and issue tracking are available at the
`wxWidgets/Phoenix <https://github.com/wxWidgets/Phoenix>`_ GitHub
repository. Be sure to read the README.rst there to learn how to build
wxWidgets and Phoenix for yourself.
`Phoenix GitHub <https://github.com/wxWidgets/Phoenix>`_ repository. Be
sure to read the README.rst file there to learn how to build wxWidgets and
Phoenix for yourself.