mirror of
https://github.com/wxWidgets/Phoenix.git
synced 2026-01-07 12:30:07 +01:00
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
This commit is contained in:
Andrea Gavana
@@ -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
|
||||
|
||||
166
docs/sphinx/rest_substitutions/overviews/datetime_overview.rst
Normal file
166
docs/sphinx/rest_substitutions/overviews/datetime_overview.rst
Normal file
@@ -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.
|
||||
|
||||
@@ -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())
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
@@ -0,0 +1,3 @@
|
||||
|
||||
now = wx.DateTime.Now()
|
||||
print "Current time in Paris:\t%s\n"%(now.Format("%c", wx.DateTime.CET))
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
|
||||
def GetCurrentChar(textCtrl):
|
||||
|
||||
pos = textCtrl.GetInsertionPoint()
|
||||
|
||||
if pos == textCtrl.GetLastPosition():
|
||||
return ''
|
||||
|
||||
return textCtrl.GetValue()[pos]
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
|
||||
wx.SystemOptions.SetOption("msw.remap", 0)
|
||||
@@ -0,0 +1,2 @@
|
||||
|
||||
wx.SystemOptions.SetOption("msw.remap", 2)
|
||||
@@ -0,0 +1,4 @@
|
||||
|
||||
if wx.GetApp().GetComCtl32Version() >= 600 and wx.DisplayDepth() >= 32:
|
||||
# Use the 32-bit images
|
||||
wx.SystemOptions.SetOption("msw.remap", 2)
|
||||
Reference in New Issue
Block a user