From f97b2e4e6bc8272433fc5091065cda920d73a3de Mon Sep 17 00:00:00 2001
From: Andrea Gavana <andrea.gavana@gmail.com>
Date: Mon, 12 Mar 2012 21:03:35 +0000
Subject: [PATCH] Phoenix documentation:

* Added overviews for wx.FileSystem, wx.ToolBar and wx.DateTime (thanks to the wxWidgets docs);
* Converted many snippets from C++ to Python for wx.ToolBar, wx.DateTime and wx.TextEntry;
* Updated the conf.py file.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxPython/Phoenix/trunk@70889 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/sphinx/conf.py                           |   4 +-
 .../overviews/datetime_overview.rst           | 166 ++++++++++++++++++
 .../overviews/filesystem_overview.rst         |  84 +++++++++
 .../overviews/toolbar_overview.rst            |  34 ++++
 .../converted/DateTime.ConvertYearToBC.1.py   |   5 +
 .../python/converted/DateTime.Now.1.py        |   3 +
 .../converted/DateTime.ParseFormat.1.py       |  12 ++
 .../converted/DateTime.ParseFormat.2.py       |  12 ++
 .../TextEntry.GetInsertionPoint.1.py          |  10 ++
 .../snippets/python/converted/ToolBar.1.py    |   2 +
 .../snippets/python/converted/ToolBar.2.py    |   2 +
 .../snippets/python/converted/ToolBar.3.py    |   4 +
 12 files changed, 336 insertions(+), 2 deletions(-)
 create mode 100644 docs/sphinx/rest_substitutions/overviews/datetime_overview.rst
 create mode 100644 docs/sphinx/rest_substitutions/overviews/filesystem_overview.rst
 create mode 100644 docs/sphinx/rest_substitutions/overviews/toolbar_overview.rst
 create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.ConvertYearToBC.1.py
 create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.Now.1.py
 create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.ParseFormat.1.py
 create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.ParseFormat.2.py
 create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/TextEntry.GetInsertionPoint.1.py
 create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/ToolBar.1.py
 create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/ToolBar.2.py
 create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/ToolBar.3.py

diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py
index 3c79ffdc..d3309f1b 100644
--- a/docs/sphinx/conf.py
+++ b/docs/sphinx/conf.py
@@ -25,7 +25,7 @@ sys.path.append('..')
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.todo', 'sphinx.ext.autodoc',
               'sphinx.ext.autosummary', 'sphinx.ext.coverage',
-              'availability'] #, 'rst2pdf.pdfbuilder']
+              'availability']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -47,7 +47,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'wxPython (Phoenix)'
-copyright = u'2011, Andrea Gavana'
+copyright = u'2012, Andrea Gavana'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
diff --git a/docs/sphinx/rest_substitutions/overviews/datetime_overview.rst b/docs/sphinx/rest_substitutions/overviews/datetime_overview.rst
new file mode 100644
index 00000000..2c3d3908
--- /dev/null
+++ b/docs/sphinx/rest_substitutions/overviews/datetime_overview.rst
@@ -0,0 +1,166 @@
+.. include:: headings.inc
+
+
+.. _date and time:
+
+===========================================
+|phoenix_title|  **Date and Time Overview**
+===========================================
+
+Introduction
+------------
+
+wxPython provides a set of powerful classes to work with dates and times. Some of the supported features of :ref:`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.
+
+
+
+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.
+
+
+
+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.
+
+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).
+
+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.
+
+
+
+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 
+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.
+
+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).
+
+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!
+
+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 
+understand what 'in a month' means - of course, it is just::
+
+    wx.DateTime.Now() + wx.DateSpan.Month()
+
+
+
+
+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.
+
+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.
+  
+* **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`.
+  
+* **Multiplication**: a :ref:`TimeSpan` or :ref:`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.
+
+
+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.
+
+
+
+.. _time zone considerations:
+
+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::
+
+    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.
+
+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.
+
+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.
+
+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)
+
+
+
+.. _dst overview:
+
+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
+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.
+
+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.
+
+
+
+DateTime and Holidays
+---------------------
+
+.. todo:: WRITE THIS DOC PARAGRAPH.
+
diff --git a/docs/sphinx/rest_substitutions/overviews/filesystem_overview.rst b/docs/sphinx/rest_substitutions/overviews/filesystem_overview.rst
new file mode 100644
index 00000000..fb5d3e76
--- /dev/null
+++ b/docs/sphinx/rest_substitutions/overviews/filesystem_overview.rst
@@ -0,0 +1,84 @@
+.. include:: headings.inc
+
+
+.. _filesystem overview:
+
+========================================
+|phoenix_title|  **FileSystem Overview**
+========================================
+
+The wxHTML library uses a **virtual** file systems mechanism similar to the one used in Midnight Commander, Dos Navigator, FAR or almost any modern file manager.
+
+It allows the user to access data stored in archives as if they were ordinary files. On-the-fly generated files that exist only in memory are also supported.
+
+
+
+Classes
+-------
+
+Three classes are used in order to provide virtual file systems mechanism:
+
+* The :ref:`FSFile` class provides information about opened file (name, input stream, mime type and anchor).
+* The :ref:`FileSystem` class is the interface. Its main methods are :meth:`FileSystem.ChangePathTo` and :meth:`FileSystem.OpenFile`. This class is most often used by the end user.
+* The :ref:`FileSystemHandler` is the core of virtual file systems mechanism. You can derive your own handler and pass it to the VFS mechanism. You can derive your 
+  own handler and pass it to the :meth:`FileSystem.AddHandler` method. In the new handler you only need to override the :meth:`FileSystemHandler.OpenFile` and 
+  :meth:`FileSystemHandler.CanOpen` methods.
+
+
+
+Locations
+---------
+
+Locations (aka filenames aka addresses) are constructed from four parts:
+
+* **protocol** - handler can recognize if it is able to open a file by checking its protocol. Examples are "http", "file" or "ftp".
+* **right location** - is the name of file within the protocol. In "http://www.wxwidgets.org/index.html" the right location is "//www.wxwidgets.org/index.html".
+* **anchor** - an anchor is optional and is usually not present. In "index.htm#chapter2" the anchor is "chapter2".
+* **left location** - this is usually an empty string. It is used by 'local' protocols such as ZIP. See the :ref:`Combined Protocols <combined protocols>` paragraph for details.
+
+
+.. _combined protocols:
+
+Combined Protocols
+------------------
+
+The left location precedes the protocol in the URL string.
+
+It is not used by global protocols like HTTP but it becomes handy when nesting protocols - for example you may want to access files in a ZIP archive: 
+
+file:archives/cpp_doc.zip#zip:reference/fopen.htm#syntax 
+
+In this example, the protocol is "zip", right location is "reference/fopen.htm", anchor is "syntax" and left location is "file:archives/cpp_doc.zip".
+
+There are two protocols used in this example: "zip" and "file".
+
+
+.. _list of available handlers:
+
+File Systems Included in wxHTML
+-------------------------------
+
+The following virtual file system handlers are part of wxPython so far:
+
+* :ref:`ArchiveFSHandler`: A handler for archives such as zip and tar. URLs examples: "archive.zip#zip:filename", "archive.tar.gz#gzip:#tar:filename".
+* :ref:`FilterFSHandler`: A handler for compression schemes such as gzip. URLs are in the form, e.g.: "document.ps.gz#gzip:".
+* :ref:`InternetFSHandler`: A handler for accessing documents via HTTP or FTP protocols.
+* :ref:`MemoryFSHandler`: This handler allows you to access data stored in memory (such as bitmaps) as if they were regular files. See :ref:`MemoryFSHandler` for details. 
+  URL is prefixed with memory:, e.g. "memory:myfile.htm".
+  
+
+In addition, :ref:`FileSystem` itself can access local files.
+
+
+
+Initializing file system handlers
+---------------------------------
+
+Use :meth:`FileSystem.AddHandler` to initialize a handler, for example::
+
+
+	def OnInit(self):
+
+	    wx.FileSystem.AddHandler(wx.MemoryFSHandler())
+
+
diff --git a/docs/sphinx/rest_substitutions/overviews/toolbar_overview.rst b/docs/sphinx/rest_substitutions/overviews/toolbar_overview.rst
new file mode 100644
index 00000000..39561e2d
--- /dev/null
+++ b/docs/sphinx/rest_substitutions/overviews/toolbar_overview.rst
@@ -0,0 +1,34 @@
+.. include:: headings.inc
+
+
+.. _toolbar overview:
+
+===========================================
+|phoenix_title|  **ToolBar Overview**
+===========================================
+
+Introduction
+------------
+
+The toolbar family of classes allows an application to use toolbars in a variety of configurations and styles.
+
+The toolbar is a popular user interface component and contains a set of bitmap buttons or toggles. 
+A toolbar gives faster access to an application's facilities than menus, which have to be popped up and 
+selected rather laboriously.
+
+Instead of supplying one toolbar class with a number of different implementations depending on platform, wxPython
+separates out the classes. This is because there are a number of different toolbar styles that you may wish to use 
+simultaneously, and also, future toolbar implementations will emerge which cannot all be shoe-horned into the one class.
+
+A toolbar might appear as a single row of images under the menubar, or it might be in a separate frame layout 
+in several rows and columns. The class handles the layout of the images, unless explicit positioning is requested.
+
+A tool is a bitmap which can either be a button (there is no 'state', it just generates an event when clicked) or it 
+can be a toggle. If a toggle, a second bitmap can be provided to depict the 'on' state; if the second bitmap is omitted, 
+either the inverse of the first bitmap will be used (for monochrome displays) or a thick border is drawn around the 
+bitmap (for colour displays where inverting will not have the desired result).
+
+The Windows-specific toolbar classes expect 16-colour bitmaps that are 16 pixels wide and 15 pixels high. If you want 
+to use a different size, call :meth:`ToolBar.SetToolBitmapSize` as the demo shows, before adding tools to the button bar. 
+Don't supply more than one bitmap for each tool, because the toolbar generates all three images (normal, depressed, 
+and checked) from the single bitmap you give it.
\ No newline at end of file
diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.ConvertYearToBC.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.ConvertYearToBC.1.py
new file mode 100644
index 00000000..88403cb1
--- /dev/null
+++ b/docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.ConvertYearToBC.1.py
@@ -0,0 +1,5 @@
+    
+            dt = wx.DateTimeFromDMY(8, 5, 1977)
+            y = dt.GetYear()
+            epoch = (y > 0 and ["AD"] or ["BC"])[0]
+            print "The year is %d%s"%(wx.DateTime.ConvertYearToBC(y), epoch)
diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.Now.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.Now.1.py
new file mode 100644
index 00000000..36bf8806
--- /dev/null
+++ b/docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.Now.1.py
@@ -0,0 +1,3 @@
+    
+            now = wx.DateTime.Now()
+            print "Current time in Paris:\t%s\n"%(now.Format("%c", wx.DateTime.CET))
diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.ParseFormat.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.ParseFormat.1.py
new file mode 100644
index 00000000..18f06416
--- /dev/null
+++ b/docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.ParseFormat.1.py
@@ -0,0 +1,12 @@
+
+            dt = wx.DateTime() # Uninitialized datetime
+            bDate = "25/12/2012"
+
+            if not dt.ParseFormat(bDate, "%d-%m-%Y"):
+                # This datetime format is wrong on purpose
+                print "Wrong format"
+
+            elif dt.ParseFormat(bDate, "%d/%m/%Y"):
+                # This is correct
+                print "Format OK!", dt
+
diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.ParseFormat.2.py b/docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.ParseFormat.2.py
new file mode 100644
index 00000000..18f06416
--- /dev/null
+++ b/docs/sphinx/rest_substitutions/snippets/python/converted/DateTime.ParseFormat.2.py
@@ -0,0 +1,12 @@
+
+            dt = wx.DateTime() # Uninitialized datetime
+            bDate = "25/12/2012"
+
+            if not dt.ParseFormat(bDate, "%d-%m-%Y"):
+                # This datetime format is wrong on purpose
+                print "Wrong format"
+
+            elif dt.ParseFormat(bDate, "%d/%m/%Y"):
+                # This is correct
+                print "Format OK!", dt
+
diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/TextEntry.GetInsertionPoint.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/TextEntry.GetInsertionPoint.1.py
new file mode 100644
index 00000000..67cd269f
--- /dev/null
+++ b/docs/sphinx/rest_substitutions/snippets/python/converted/TextEntry.GetInsertionPoint.1.py
@@ -0,0 +1,10 @@
+    
+            def GetCurrentChar(textCtrl):
+
+                pos = textCtrl.GetInsertionPoint()
+                
+                if pos == textCtrl.GetLastPosition():
+                    return ''
+                
+                return textCtrl.GetValue()[pos]
+            
diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/ToolBar.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/ToolBar.1.py
new file mode 100644
index 00000000..161cd719
--- /dev/null
+++ b/docs/sphinx/rest_substitutions/snippets/python/converted/ToolBar.1.py
@@ -0,0 +1,2 @@
+    
+        wx.SystemOptions.SetOption("msw.remap", 0)
diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/ToolBar.2.py b/docs/sphinx/rest_substitutions/snippets/python/converted/ToolBar.2.py
new file mode 100644
index 00000000..4469402e
--- /dev/null
+++ b/docs/sphinx/rest_substitutions/snippets/python/converted/ToolBar.2.py
@@ -0,0 +1,2 @@
+    
+        wx.SystemOptions.SetOption("msw.remap", 2)
diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/ToolBar.3.py b/docs/sphinx/rest_substitutions/snippets/python/converted/ToolBar.3.py
new file mode 100644
index 00000000..72897b37
--- /dev/null
+++ b/docs/sphinx/rest_substitutions/snippets/python/converted/ToolBar.3.py
@@ -0,0 +1,4 @@
+
+        if wx.GetApp().GetComCtl32Version() >= 600 and wx.DisplayDepth() >= 32:
+            # Use the 32-bit images
+            wx.SystemOptions.SetOption("msw.remap", 2)