From eeec9c5a419dc294f869a5af74bed66301ada5bb Mon Sep 17 00:00:00 2001 From: Robin Dunn Date: Thu, 26 May 2016 00:01:50 -0700 Subject: [PATCH] first batch of overview file updates, reformatting and name fixes --- docs/sphinx/_templates/main.html | 2 + .../overviews/DocstringsGuidelines.rst | 251 +++++++++++------- .../overviews/app_overview.rst | 63 +++-- .../overviews/bitmap_overview.rst | 106 ++++---- .../overviews/bookctrl_overview.rst | 32 +-- .../overviews/command_overview.rst | 69 +++-- .../overviews/common_dialogs_overview.rst | 161 ++++++----- .../overviews/config_overview.rst | 73 +++-- .../overviews/dataobject_overview.rst | 68 +++-- .../overviews/datetime_overview.rst | 206 +++++++++----- .../overviews/dc_overview.rst | 47 ++-- .../overviews/dialog_overview.rst | 167 ++++++++---- .../overviews/dnd_overview.rst | 75 ++++-- .../rest_substitutions/overviews/index.rst | 6 +- 14 files changed, 813 insertions(+), 513 deletions(-) diff --git a/docs/sphinx/_templates/main.html b/docs/sphinx/_templates/main.html index b4495608..6c6d8842 100644 --- a/docs/sphinx/_templates/main.html +++ b/docs/sphinx/_templates/main.html @@ -18,6 +18,8 @@
+

API Modules

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