]> git.saurik.com Git - wxWidgets.git/blame - wxPython/docs/wxPythonManual.txt
Moved config.py to the root because if wxPython hasn't been built yet
[wxWidgets.git] / wxPython / docs / wxPythonManual.txt
CommitLineData
1fded56b
RD
1=====================
2 The wxPython Manual
3=====================
4
5--------------------------------------------
6 A guide to wxPython for Python programmers
7--------------------------------------------
8
9:Author: Patrick K. O'Brien
10:Contact: pobrien@orbtech.com
11:Organization: Orbtech_
12:Date: $Date$
13:Revision: $Revision$
14:License: wxWindows Free Documentation Licence, Version 3
15
16.. _Orbtech: http://www.orbtech.com/
17
18.. contents::
19
20
21Introduction
22============
23
24This is a guide to the wxPython GUI toolkit, written **by** a Python
25programmer **for** his fellow Python programmers. It began as a
26simple translation of the wxWindows documentation (which is written
27for C++ programmers), and evolved from there. And while there's
28nothing wrong with C++...
29
30Okay, you got me there. I hate C++. That's why I use Python. If you
31like C++, go read the wxWindows documentation. If you'd rather read a
32guide that's written with Python programmers in mind, keep reading
33this one. If you like it, feel free to send me freshly roasted coffee
34beans, dark chocolate, and large denomination currency. Better yet,
35buy huge quantities of my wxPython book (written with Robin Dunn) and
36send one to each of your friends, relatives, and coworkers.
37
38
39What is wxPython?
40=================
41
42wxPython is a GUI toolkit for the Python programming language. It
43allows Python programmers to create programs with a robust, highly
44functional graphical user interface, simply and easily. It is
45implemented as a Python extension module (native code) that wraps the
46popular wxWindows cross platform GUI library, which is written in C++.
47
48Like Python and wxWindows, wxPython is Open Source, which means that
49it is free for anyone to use and the source code is available for
50anyone to look at and modify. And anyone can contribute fixes or
51enhnacments to the project.
52
53wxPython is a cross-platform toolkit. This means that the same
54program will run on multiple platforms without modification.
55Currently supported platforms are 32-bit Microsoft Windows, most Unix
56or unix-like systems, and Macintosh OS X.
57
58Since the language is Python, wxPython programs are simple, easy to
59write and easy to understand.
60
61
62wxPython requirements
63=====================
64
65To make use of wxPython, you currently need one of the following
66setups.
67
68MS-Windows
69----------
70
71* A 486 or higher PC running MS Windows.
72* At least ?? MB of disk space.
73
74Linux or Unix
75-------------
76
77* Almost any C++ compiler, including GNU C++ (EGCS 1.1.1 or above).
78* Almost any Unix workstation, and one of: GTK+ 1.2, GTK+ 2.0, Motif
79 1.2 or higher, Lesstif.
80* At least ?? MB of disk space.
81
82Mac OS X
83--------
84
85* A PowerPC Mac running Mac OS X 10.x.
86* At least ?? MB of disk space.
87
88
89What is wxWindows?
90==================
91
92wxWindows is a C++ framework providing GUI (Graphical User Interface)
93and other facilities on more than one platform. Version 2 currently
94supports all desktop versions of MS Windows, Unix with GTK+, Unix with
95Motif, and MacOS. An OS/2 port is in progress.
96
97wxWindows was originally developed at the Artificial Intelligence
98Applications Institute, University of Edinburgh, for internal use, and
99was first made publicly available in 1992. Version 2 is a vastly
100improved version written and maintained by Julian Smart, Robert
101Roebling, Vadim Zeitlin, Vaclav Slavik and many others.
102
103Please note that in the following, "MS Windows" often refers to all
104platforms related to Microsoft Windows, including 16-bit and 32-bit
105variants, unless otherwise stated. All trademarks are acknowledged.
106
107
108Why another cross-platform development tool?
109============================================
110
111wxWindows was developed to provide a cheap and flexible way to
112maximize investment in GUI application development. While a number of
113commercial class libraries already existed for cross-platform
114development, none met all of the following criteria:
115
116* low price
117* source availability
118* simplicity of programming
119* support for a wide range of compilers
120
121Since wxWindows was started, several other free or almost-free GUI
122frameworks have emerged. However, none has the range of features,
123flexibility, documentation and the well-established development team
124that wxWindows has.
125
126As open source software, wxWindows has benefited from comments, ideas,
127bug fixes, enhancements and the sheer enthusiasm of users. This gives
128wxWindows a certain advantage over its commercial competitors (and
129over free libraries without an independent development team), plus a
130robustness against the transience of one individual or company. This
131openness and availability of source code is especially important when
132the future of thousands of lines of application code may depend upon
133the longevity of the underlying class library.
134
135Version 2 goes much further than previous versions in terms of
136generality and features, allowing applications to be produced that are
137often indistinguishable from those produced using single-platform
138toolkits such as Motif, GTK+ and MFC.
139
140The importance of using a platform-independent class library cannot be
141overstated, since GUI application development is very time-consuming,
142and sustained popularity of particular GUIs cannot be guaranteed.
143Code can very quickly become obsolete if it addresses the wrong
144platform or audience. wxWindows helps to insulate the programmer from
145these winds of change. Although wxWindows may not be suitable for
146every application (such as an OLE-intensive program), it provides
147access to most of the functionality a GUI program normally requires,
148plus many extras such as network programming, PostScript output, and
149HTML rendering; and it can of course be extended as needs dictate. As
150a bonus, it provides a far cleaner and easier programming interface
151than the native APIs. Programmers may find it worthwhile to use
152wxWindows even if they are developing on only one platform.
153
154It is impossible to sum up the functionality of wxWindows in a few
155paragraphs, but here are some of the benefits:
156
157* Low cost (free, in fact!)
158* You get the source.
159* Available on a variety of popular platforms.
160* Works with almost all popular C++ compilers and Python.
161* Over 50 example programs.
162* Over 1000 pages of printable and on-line documentation.
163* Includes Tex2RTF, to allow you to produce your own documentation in
164 Windows Help, HTML and Word RTF formats.
165* Simple-to-use, object-oriented API.
166* Flexible event system.
167* Graphics calls include lines, rounded rectangles, splines,
168 polylines, etc.
169* Constraint-based and sizer-based layouts.
170* Print/preview and document/view architectures.
171* Toolbar, notebook, tree control, advanced list control classes.
172* PostScript generation under Unix, normal MS Windows printing on the
173 PC.
174* MDI (Multiple Document Interface) support.
175* Can be used to create DLLs under Windows, dynamic libraries on Unix.
176* Common dialogs for file browsing, printing, colour selection, etc.
177* Under MS Windows, support for creating metafiles and copying them to
178 the clipboard.
179* An API for invoking help from applications.
180* Ready-to-use HTML window (supporting a subset of HTML).
181* Dialog Editor for building dialogs.
182* Network support via a family of socket and protocol classes.
183* Support for platform independent image processing.
184* Built-in support for many file formats (BMP, PNG, JPEG, GIF, XPM,
185 PNM, PCX).
186
187
188wxPython Overview
189=================
190
191To set a wxPython application going, you will need to derive an App
192class and override App.OnInit.
193
194An application must have a top-level Frame or Dialog window. Each
195frame may contain one or more instances of classes such as Panel,
196SplitterWindow or other windows and controls.
197
198A frame can have a MenuBar, a ToolBar, a status line, and an Icon for
199when the frame is iconized.
200
201A Panel is used to place controls (classes derived from Control) which
202are used for user interaction. Examples of controls are Button,
203CheckBox, Choice, ListBox, RadioBox, Slider.
204
205Instances of Dialog can also be used for controls, and they have the
206advantage of not requiring a separate frame.
207
208Instead of creating a dialog box and populating it with items, it is
209possible to choose one of the convenient common dialog classes, such
210as MessageDialog and FileDialog.
211
212You never draw directly onto a window. Instead, you use a device
213context (DC). DC is the base for ClientDC, PaintDC, MemoryDC,
214PostScriptDC, MemoryDC, MetafileDC and PrinterDC. If your drawing
215functions have DC as a parameter, you can pass any of these DCs to the
216function, and thus use the same code to draw to several different
217devices. You can draw using the member functions of DC, such as
218DC.DrawLine and DC.DrawText. Control colour on a window (Colour) with
219brushes (Brush) and pens (Pen).
220
221.. To intercept events, you add a DECLARE_EVENT_TABLE macro to the
222 window class declaration, and put a BEGIN_EVENT_TABLE
223 ... END_EVENT_TABLE block in the implementation file. Between these
224 macros, you add event macros which map the event (such as a mouse
225 click) to a member function. These might override predefined event
226 handlers such as for KeyEvent and MouseEvent.
227
228Most modern applications will have an on-line, hypertext help system;
229for this, you need Help and the HelpController class to control
230Help.
231
232GUI applications aren't all graphical wizardry. You'll also need
233lists and hash tables. But since you're working with Python, you
234should use the ones Python provides (list, tuple, dict), rather than
235the wxWindows versions. Same goes for the database related classes.
236The basic rule of thumb is this: If you can do it directly in Python,
237you probably should. If there is a reason not to use a Python data
238type, wxPython will provide a wrapper for the wxWindows class.
239
240You will undoubtedly need some platform-independent file functions,
241and you may find it handy to maintain and search a list of paths using
242PathList. There's a miscellany of operating system and other
243functions.
244
245See also Classes by Category for a list of classes.
246
247
248Utilities and libraries supplied with wxPython
249==============================================
250
251In addition to the core wxWindows library, a number of further
252libraries and utilities are supplied with each distribution.
253
254[Need to list these.]
255
256
257Creating and deleting wxPython objects
258======================================
259
260[This section needs to be reviewed.]
261
262.. In general, classes derived from wxWindow must dynamically
263 allocated with new and deleted with delete. If you delete a window,
264 all of its children and descendants will be automatically deleted,
265 so you don't need to delete these descendants explicitly.
266
267.. When deleting a frame or dialog, use Destroy rather than delete so
268 that the wxWindows delayed deletion can take effect. This waits
269 until idle time (when all messages have been processed) to actually
270 delete the window, to avoid problems associated with the GUI
271 sending events to deleted windows.
272
273.. If you decide to allocate a C++ array of objects (such as wxBitmap)
274 that may be cleaned up by wxWindows, make sure you delete the array
275 explicitly before wxWindows has a chance to do so on exit, since
276 calling delete on array members will cause memory problems.
277
278.. wxColour can be created statically: it is not automatically cleaned
279 up and is unlikely to be shared between other objects; it is
280 lightweight enough for copies to be made.
281
282.. Beware of deleting objects such as a wxPen or wxBitmap if they are
283 still in use. Windows is particularly sensitive to this: so make
284 sure you make calls like wxDC::SetPen(wxNullPen) or
285 wxDC::SelectObject(wxNullBitmap) before deleting a drawing object
286 that may be in use. Code that doesn't do this will probably work
287 fine on some platforms, and then fail under Windows.
288
289
290App overview
291============
292
293Classes: wx.App
294
295Application initialization
296--------------------------
297
298The OnInit method defined for a class derived from wx.App will usually
299create a top window as a bare minimum.
300
301OnInit must return a boolean value to indicate whether processing
302should continue (True) or not (False). You call App.SetTopWindow to
303let wxPython know about the top window.
304
305An application closes by destroying all windows. Because all frames
306must be destroyed for the application to exit, it is advisable to use
307parent frames wherever possible when creating new frames, so that
308deleting the top level frame will automatically delete child frames.
309The alternative is to explicitly delete child frames in the top-level
310frame's CloseEvent handler.
311
312In emergencies the wx.Exit() function can be called to kill the
313application, however, normally the application shuts down
314automatically, see below.
315
316An example of defining an application follows::
317
318 import wx
319
320 from frame import Frame
321
322 class App(wx.App):
323 """Application class."""
324
325 def OnInit(self):
326 self.frame = Frame()
327 self.frame.Show()
328 self.SetTopWindow(self.frame)
329 return True
330
331 def main():
332 app = App()
333 app.MainLoop()
334
335 if __name__ == '__main__':
336 main()
337
338
339Application shutdown
340--------------------
341
342The application normally shuts down when the last of its top level
343windows is closed. This is normally the expected behaviour and means
344that it is enough to call Close() in response to the "Exit" menu
345command if your program has a single top level window. If this
346behaviour is not desirable, App.SetExitOnFrameDelete can be called to
347change it. Note that such logic doesn't apply for the windows shown
348before the program enters the main loop: in other words, you can
349safely show a dialog from App.OnInit and not be afraid that your
350application terminates when this dialog -- which is the last top level
351window for the moment -- is closed.
352
353Another aspect of the application shutdown is the OnExit which is
354called when the application exits but before wxPython cleans up its
355internal structures. You should delete all wxPython objects that you
356created by the time OnExit finishes.
357
358For example, this code may crash:
359
360[Need examples of objects needing cleanup to keep app from crashing.]
361
362
363Sizer overview
364==============
365
366Classes: wx.Sizer, wx.GridSizer, wx.FlexGridSizer, wx.BoxSizer,
367wx.StaticBoxSizer, wx.NotebookSizer, wx.CreateButtonSizer
368
369============== ======================================================
370
371Sizer Abstract base class.
372
373GridSizer A sizer for laying out windows in a grid with all
374 fields having the same size.
375
376FlexGridSizer A sizer for laying out windows in a flexible grid.
377
378BoxSizer A sizer for laying out windows in a row or column.
379
380StaticBoxSizer Same as BoxSizer, but with a surrounding static box.
381
382NotebookSizer Sizer to use with the Notebook control.
383
384============== ======================================================
385
386Sizers, as represented by the wx.Sizer class and its descendants in
387the wxPython class hierarchy, have become the method of choice to
388define the layout of controls in dialogs in wxPython because of their
389ability to create visually appealing dialogs independent of the
390platform, taking into account the differences in size and style of the
391individual controls. Editors such as wxDesigner, wxrcedit, XRCed and
392wxWorkshop create dialogs based exclusively on sizers, practically
393forcing the user to create platform independent layouts without
394compromises.
395
396
397The idea behind sizers
398----------------------
399
400The layout algorithm used by sizers in wxPython is closely related to
401layout systems in other GUI toolkits, such as Java's AWT, the GTK
402toolkit or the Qt toolkit. It is based upon the idea of individual
403subwindows reporting their minimal required size and their ability to
404get stretched if the size of the parent window has changed. This will
405most often mean that the programmer does not set the start-up size of
406a dialog, the dialog will rather be assigned a sizer and this sizer
407will be queried about the recommended size. This sizer in turn will
408query its children (which can be normal windows, empty space or other
409sizers) so that a hierarchy of sizers can be constructed. Note that
410wx.Sizer does not derive from wx.Window and thus does not interfere
411with tab ordering and requires very few resources compared to a real
412window on screen.
413
414What makes sizers so well fitted for use in wxPython is the fact that
415every control reports its own minimal size and the algorithm can
416handle differences in font sizes or different window (dialog item)
417sizes on different platforms without problems. For example, if the
418standard font as well as the overall design of Linux/GTK widgets
419requires more space than on Windows, the initial dialog size will
420automatically be bigger on Linux/GTK than on Windows.
421
422There are currently five different kinds of sizers available in
423wxPython. Each represents either a certain way to lay out dialog items
424in a dialog or it fulfils a special task such as wrapping a static box
425around a dialog item (or another sizer). These sizers will be
426discussed one by one in the text below.
427
428
429Common features
430---------------
431
432All sizers are containers, that is, they are used to lay out one
433dialog item (or several dialog items), which they contain. Such items
434are sometimes referred to as the children of the sizer. Independent
435of how the individual sizers lay out their children, all children have
436certain features in common:
437
438
439A minimal size
440~~~~~~~~~~~~~~
441
442This minimal size is usually identical to the initial size of the
443controls and may either be set explicitly in the size field of the
444control constructor or may be calculated by wxPython, typically by
445setting the height and/or the width of the item to -1. Note that only
446some controls can calculate their size (such as a checkbox) whereas
447others (such as a listbox) don't have any natural width or height and
448thus require an explicit size. Some controls can calculate their
449height, but not their width (e.g. a single line text control):
450
451[Need graphics]
452
453
454A border
455~~~~~~~~
456
457The border is just empty space and is used to separate dialog items in
458a dialog. This border can either be all around, or at any combination
459of sides such as only above and below the control. The thickness of
460this border must be set explicitly, typically 5 points. The following
461samples show dialogs with only one dialog item (a button) and a border
462of 0, 5, and 10 pixels around the button:
463
464[Need graphics]
465
466
467An alignment
468~~~~~~~~~~~~
469
470Often, a dialog item is given more space than its minimal size plus
471its border. Depending on what flags are used for the respective dialog
472item, the dialog item can be made to fill out the available space
473entirely, i.e. it will grow to a size larger than the minimal size, or
474it will be moved to either the centre of the available space or to
475either side of the space. The following sample shows a listbox and
476three buttons in a horizontal box sizer; one button is centred, one is
477aligned at the top, one is aligned at the bottom:
478
479[Need graphics]
480
481
482A stretch factor
483~~~~~~~~~~~~~~~~
484
485If a sizer contains more than one child and it is offered more space
486than its children and their borders need, the question arises how to
487distribute the surplus space among the children. For this purpose, a
488stretch factor may be assigned to each child, where the default value
489of 0 indicates that the child will not get more space than its
490requested minimum size. A value of more than zero is interpreted in
491relation to the sum of all stretch factors in the children of the
492respective sizer, i.e. if two children get a stretch factor of 1, they
493will get half the extra space each independent of whether one control
494has a minimal sizer inferior to the other or not. The following
495sample shows a dialog with three buttons, the first one has a stretch
496factor of 1 and thus gets stretched, whereas the other two buttons
497have a stretch factor of zero and keep their initial width:
498
499[Need graphics]
500
501Within wxDesigner, this stretch factor gets set from the Option menu.
502
503
504BoxSizer
505--------
506
507BoxSizer can lay out its children either vertically or horizontally,
508depending on what flag is being used in its constructor. When using a
509vertical sizer, each child can be centered, aligned to the right or
510aligned to the left. Correspondingly, when using a horizontal sizer,
511each child can be centered, aligned at the bottom or aligned at the
512top. The stretch factor described in the last paragraph is used for
513the main orientation, i.e. when using a horizontal box sizer, the
514stretch factor determines how much the child can be stretched
515horizontally. The following sample shows the same dialog as in the
516last sample, only the box sizer is a vertical box sizer now:
517
518[Need graphics]
519
520
521StaticBoxSizer
522--------------
523
524StaticBoxSixer is the same as a BoxSizer, but surrounded by a static
525box. Here is a sample:
526
527[Need graphics]
528
529
530GridSizer
531---------
532
533GridSizer is a two-dimensional sizer. All children are given the same
534size, which is the minimal size required by the biggest child, in this
535case the text control in the left bottom border. Either the number of
536columns or the number or rows is fixed and the grid sizer will grow in
537the respectively other orientation if new children are added:
538
539[Need graphics]
540
541
542FlexGridSizer
543-------------
544
545Another two-dimensional sizer derived from GridSizer. The width of
546each column and the height of each row are calculated individually
547according the minimal requirements from the respectively biggest
548child. Additionally, columns and rows can be declared to be
549stretchable if the sizer is assigned a size different from that which
550it requested. The following sample shows the same dialog as the one
551above, but using a flex grid sizer:
552
553[Need graphics]
554
555
556NotebookSizer
557-------------
558
559NotebookSizer can be used with notebooks. It calculates the size of
560each notebook page and sets the size of the notebook to the size of
561the biggest page plus some extra space required for the notebook tabs
562and decorations.
563
564[Need graphics]
565
566
567Programming with BoxSizer
568-------------------------
569
570The basic idea behind a BoxSizer is that windows will most often be
571laid out in rather simple basic geometry, typically in a row or a
572column or several hierarchies of either.
573
574As an example, we will construct a dialog that will contain a text
575field at the top and two buttons at the bottom. This can be seen as a
576top-hierarchy column with the text at the top and buttons at the
577bottom and a low-hierarchy row with an OK button to the left and a
578Cancel button to the right. In many cases (particularly dialogs under
579Unix and normal frames) the main window will be resizable by the user
580and this change of size will have to get propagated to its children.
581In our case, we want the text area to grow with the dialog, whereas
582the button shall have a fixed size. In addition, there will be a thin
583border around all controls to make the dialog look nice and - to make
584matter worse - the buttons shall be centred as the width of the dialog
585changes.
586
587It is the unique feature of a box sizer, that it can grow in both
588directions (height and width) but can distribute its growth in the
589main direction (horizontal for a row) unevenly among its children. In
590our example case, the vertical sizer is supposed to propagate all its
591height changes to only the text area, not to the button area. This is
592determined by the proportion parameter when adding a window (or
593another sizer) to a sizer. It is interpreted as a weight factor,
594i.e. it can be zero, indicating that the window may not be resized at
595all, or above zero. If several windows have a value above zero, the
596value is interpreted relative to the sum of all weight factors of the
597sizer, so when adding two windows with a value of 1, they will both
598get resized equally much and each half as much as the sizer owning
599them.
600
601Then what do we do when a column sizer changes its width? This
602behaviour is controlled by flags (the second parameter of the Add()
603function): zero or no flag indicates that the window will preserve it
604is original size, wx.GROW flag (same as wx.EXPAND) forces the window
605to grow with the sizer, and wx.SHAPED flag tells the window to change
606it is size proportionally, preserving original aspect ratio. When
607wx.GROW flag is not used, the item can be aligned within available
608space. wx.ALIGN_LEFT, wx.ALIGN_TOP, wx.ALIGN_RIGHT, wx.ALIGN_BOTTOM,
609wx.ALIGN_CENTER_HORIZONTAL and wx.ALIGN_CENTER_VERTICAL do what they
610say. wx.ALIGN_CENTRE (same as wx.ALIGN_CENTER) is defined as
611(``wx.ALIGN_CENTER_HORIZONTAL | wx.ALIGN_CENTER_VERTICAL``). Default
612alignment is ``wx.ALIGN_LEFT | wx.ALIGN_TOP``.
613
614As mentioned above, any window belonging to a sizer may have border,
615and it can be specified which of the four sides may have this border,
616using the wx.TOP, wx.LEFT, wx.RIGHT and wx.BOTTOM constants or wx.ALL
617for all directions (and you may also use wx.NORTH, wx.WEST etc
618instead). These flags can be used in combination with the alignment
619flags above as the second parameter of the Add() method using the
620binary or operator (``|``). The sizer of the border also must be made
621known, and it is the third parameter in the Add() method. This means,
622that the entire behaviour of a sizer and its children can be
623controlled by the three parameters of the Add() method.
624
625[Show code and graphic here.]
626
627
628Programming with GridSizer
629--------------------------
630
631GridSizer is a sizer which lays out its children in a two-dimensional
632table with all table fields having the same size, i.e. the width of
633each field is the width of the widest child, the height of each field
634is the height of the tallest child.
635
636[Show code and graphic here.]
637
638
639Programming with FlexGridSizer
640------------------------------
641
642FlexGridSizer is a sizer which lays out its children in a
643two-dimensional table with all table fields in one row having the same
644height and all fields in one column having the same width, but all
645rows or all columns are not necessarily the same height or width as in
646the GridSizer.
647
648[Show code and graphic here.]
649
650
651Programming with NotebookSizer
652------------------------------
653
654NotebookSizer is a specialized sizer to make sizers work in connection
655with using notebooks. This sizer is different from any other sizer as
656you must not add any children to it - instead, it queries the notebook
657class itself. The only thing this sizer does is to determine the size
658of the biggest page of the notebook and report an adjusted minimal
659size to a more toplevel sizer.
660
661In order to query the size of notebook page, this page needs to have
662its own sizer, otherwise the NotebookSizer will ignore it. Notebook
663pages get their sizer by assigning one to them using SetSizer() and
664setting the auto-layout option to True using SetAutoLayout(). Here is
665one example showing how to add a notebook page that the notebook sizer
666is aware of:
667
668[Show code and graphic here.]
669
670
671Programming with StaticBoxSizer
672-------------------------------
673
674StaticBoxSizer is a sizer derived from BoxSizer but adds a static box
675around the sizer. Note that this static box has to be created
676separately.
677
678[Show code and graphic here.]
679
680
681Dialog.CreateButtonSizer
682------------------------
683
684As a convenience, the Dialog class has a CreateButtonSizer(flags)
685method that can be used to create a standard button sizer in which
686standard buttons are displayed. The following flags can be passed to
687this method:
688
689============= =======================================================
690wx.YES_NO add Yes/No subpanel
691wx.YES return wx.ID_YES
692wx.NO return wx.ID_NO
693wx.NO_DEFAULT make the wx.NO button the default, otherwise wx.YES or
694 wx.OK button will be default
695wx.OK return wx.ID_OK
696wx.CANCEL return wx.ID_CANCEL
697wx.HELP return wx.ID_HELP
698wx.FORWARD return wx.ID_FORWARD
699wx.BACKWARD return wx.ID_BACKWARD
700wx.SETUP return wx.ID_SETUP
701wx.MORE return wx.ID_MORE
702============= =======================================================
703
704
705Date and time classes overview
706==============================
707
708wxPython provides a set of powerful classes to work with dates and
709times. Some of the supported features of the DateTime class are:
710
711============= =======================================================
712
713Wide range The range of supported dates goes from about 4714 B.C. to
714 some 480 million years in the future.
715
716Precision Not using floating point calculations anywhere ensures that
717 the date calculations don't suffer from rounding
718 errors.
719
720Many features Not only all usual calculations with dates are
721 supported, but also more exotic week and year day
722 calculations, work day testing, standard astronomical
723 functions, conversion to and from strings in either
724 strict or free format.
725
726
727Efficiency Objects of DateTime are small (8 bytes) and working
728 with them is fast
729
730============= =======================================================
731
732
733All date/time classes at a glance
734---------------------------------
735
736There are 3 main classes: except DateTime itself which represents an
737absolute moment in time, there are also two classes - TimeSpan and
738DateSpan which represent the intervals of time.
739
740There are also helper classes which are used together with DateTime:
741DateTimeHolidayAuthority which is used to determine whether a given
742date is a holiday or not and DateTimeWorkDays which is a derivation of
743this class for which (only) Saturdays and Sundays are the holidays.
744See more about these classes in the discussion of the holidays.
745
746
747DateTime characteristics
748------------------------
749
750DateTime stores the time as a signed number of milliseconds since the
751Epoch which is fixed, by convention, to Jan 1, 1970 - however this is
752not visible to the class users (in particular, dates prior to the
753Epoch are handled just as well (or as bad) as the dates after it).
754But it does mean that the best resolution which can be achieved with
755this class is 1 millisecond.
756
757The size of DateTime object is 8 bytes because it is represented as a
75864 bit integer. The resulting range of supported dates is thus
759approximatively 580 million years, but due to the current limitations
760in the Gregorian calendar support, only dates from Nov 24, 4714BC are
761supported (this is subject to change if there is sufficient interest
762in doing it).
763
764Finally, the internal representation is time zone independent (always
765in GMT) and the time zones only come into play when a date is broken
766into year/month/day components. See more about timezones below.
767
768Currently, the only supported calendar is Gregorian one (which is used
769even for the dates prior to the historic introduction of this calendar
770which was first done on Oct 15, 1582 but is, generally speaking,
771country, and even region, dependent). Future versions will probably
772have Julian calendar support as well and support for other calendars
773(Maya, Hebrew, Chinese...) is not ruled out.
774
775
776Difference between DateSpan and TimeSpan
777----------------------------------------
778
779While there is only one logical way to represent an absolute moment in
780the time (and hence only one DateTime class), there are at least two
781methods to describe a time interval.
782
783First, there is the direct and self-explaining way implemented by
784TimeSpan: it is just a difference in milliseconds between two moments
785in time. Adding or subtracting such an interval to DateTime is always
786well-defined and is a fast operation.
787
788But in daily life other, calendar-dependent time interval
789specifications are used. For example, 'one month later' is commonly
790used. However, it is clear that this is not the same as TimeSpan of
79160*60*24*31 seconds because 'one month later' Feb 15 is Mar 15 and not
792Mar 17 or Mar 16 (depending on whether the year is leap or not).
793
794This is why there is another class for representing such intervals
795called DateSpan. It handles these sort of operations in the most
796natural way possible, but note that manipulating with intervals of
797this kind is not always well-defined. Consider, for example, Jan 31 +
798'1 month': this will give Feb 28 (or 29), i.e. the last day of
799February and not the non-existent Feb 31. Of course, this is what is
800usually wanted, but you still might be surprised to notice that now
801subtracting back the same interval from Feb 28 will result in Jan 28
802and not Jan 31 we started with!
803
804So, unless you plan to implement some kind of natural language parsing
805in the program, you should probably use TimeSpan instead of DateSpan
806(which is also more efficient). However, DateSpan may be very useful
807in situations when you do need to understand what 'in a month' means
808(of course, it is just DateTime.Now() + DateSpan.Month()).
809
810
811Date arithmetics
812----------------
813
814Many different operations may be performed with the dates, however not
815all of them make sense. For example, multiplying a date by a number
816is an invalid operation, even though multiplying either of the time
817span classes by a number is perfectly valid.
818
819Here is what can be done:
820
821============== ======================================================
822
823Addition a TimeSpan or DateSpan can be added to DateTime resulting in
824 a new DateTime object and also 2 objects of the same
825 span class can be added together giving another object
826 of the same class.
827
828
829Subtraction the same types of operations as above are allowed and,
830 additionally, a difference between two DateTime
831 objects can be taken and this will yield TimeSpan.
832
833Multiplication a TimeSpan or DateSpan object can be multiplied by an
834 integer number resulting in an object of the same
835 type.
836
837
838Unary minus a TimeSpan or DateSpan object may finally be negated
839 giving an interval of the same magnitude but of
840 opposite time direction.
841
842============== ======================================================
843
844
845Time zone considerations
846------------------------
847
848Although the time is always stored internally in GMT, you will usually
849work in the local time zone. Because of this, all DateTime
850constructors and setters which take the broken down date assume that
851these values are for the local time zone. Thus, DateTime(1,
852DateTime.Jan, 1970) will not correspond to the DateTime Epoch unless
853you happen to live in the UK.
854
855All methods returning the date components (year, month, day, hour,
856minute, second...) will also return the correct values for the local
857time zone by default. So, generally, doing the natural things will
858lead to natural and correct results.
859
860If you only want to do this, you may safely skip the rest of this
861section. However, if you want to work with different time zones, you
862should read it to the end.
863
864In this (rare) case, you are still limited to the local time zone when
865constructing DateTime objects, i.e. there is no way to construct a
866DateTime corresponding to the given date in, say, Pacific Standard
867Time. To do it, you will need to call ToTimezone or MakeTimezone
868methods to adjust the date for the target time zone. There are also
869special versions of these functions ToGMT and MakeGMT for the most
870common case - when the date should be constructed in GMT.
871
872You also can just retrieve the value for some time zone without
873converting the object to it first. For this you may pass TimeZone
874argument to any of the methods which are affected by the time zone
875(all methods getting date components and the date formatting ones, for
876example). In particular, the Format() family of methods accepts a
877TimeZone parameter and this allows to simply print time in any time
878zone.
879
880To see how to do it, the last issue to address is how to construct a
881TimeZone object which must be passed to all these methods. First of
882all, you may construct it manually by specifying the time zone offset
883in seconds from GMT, but usually you will just use one of the symbolic
884time zone names and let the conversion constructor do the
885job. I.e. you would just write
886
887wxDateTime dt(...whatever...);
888printf("The time is %s in local time zone", dt.FormatTime().c_str());
889printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str());
890
891
892Daylight saving time (DST)
893--------------------------
894
895DST (a.k.a. 'summer time') handling is always a delicate task which is
896better left to the operating system which is supposed to be configured
897by the administrator to behave correctly. Unfortunately, when doing
898calculations with date outside of the range supported by the standard
899library, we are forced to deal with these issues ourselves.
900
901Several functions are provided to calculate the beginning and end of
902DST in the given year and to determine whether it is in effect at the
903given moment or not, but they should not be considered as absolutely
904correct because, first of all, they only work more or less correctly
905for only a handful of countries (any information about other ones
906appreciated!) and even for them the rules may perfectly well change in
907the future.
908
909The time zone handling methods use these functions too, so they are
910subject to the same limitations.
911
912
913DateTime and Holidays
914---------------------
915
916[TODO]
917
918
919Classes by category
920===================
921
922Not done yet.
923
924
925ID constants
926============
927
928wxPython provides the following predefined ID constants:
929
930ID_ABORT
931ID_ABOUT
932ID_ANY
933ID_APPLY
934ID_BACKWARD
935ID_CANCEL
936ID_CLEAR
937ID_CLOSE
938ID_CLOSE_ALL
939ID_CONTEXT_HELP
940ID_COPY
941ID_CUT
942ID_DEFAULT
943ID_DUPLICATE
944ID_EXIT
945ID_FILE1
946ID_FILE2
947ID_FILE3
948ID_FILE4
949ID_FILE5
950ID_FILE6
951ID_FILE7
952ID_FILE8
953ID_FILE9
954ID_FILTERLISTCTRL
955ID_FIND
956ID_FORWARD
957ID_HELP
958ID_HELP_COMMANDS
959ID_HELP_CONTENTS
960ID_HELP_CONTEXT
961ID_HELP_PROCEDURES
962ID_IGNORE
963ID_MORE
964ID_NEW
965ID_NO
966ID_NOTOALL
967ID_OK
968ID_OPEN
969ID_PASTE
970ID_PREVIEW
971ID_PRINT
972ID_PRINT_SETUP
973ID_REDO
974ID_RESET
975ID_RETRY
976ID_REVERT
977ID_SAVE
978ID_SAVEAS
979ID_SELECTALL
980ID_SEPARATOR
981ID_SETUP
982ID_STATIC
983ID_TREECTRL
984ID_UNDO
985ID_YES
986ID_YESTOALL
987
988
989Source document
990===============
991
992The source document is named wxPythonManual.txt and can be found by
993clicking the link at the bottom of this page (assuming you are viewing
994the html file). It is written using a fantastic formatting convention
995called reStructuredText. The wxPythonManual.html file is created
996using the Docutils utilities, which can turn reStructuredText
997documents into html, xml, pdf, and even OpenOffice files.
998
999
1000Submitting changes to the source document
1001=========================================
1002
1003Some items in the source text file look like this::
1004
1005 .. This is text from the wxWindows documentation that needs to be
1006 translated into something appropriate for the wxPython version.
1007 The two dots followed by uniformly indented text turns this
1008 paragraph into a reStructuredText comment, so it doesn't appear
1009 in any output file, such as the html file.
1010
1011They have been commented out and are awaiting editorial review and a
1012rewrite so that they make sense in the context of wxPython. Feel free
1013to send me suggestions for rewording these, or any other parts of this
1014document that you think need improving. I will be eternally grateful
1015to you and will show my gratitude by adding your name to the list of
1016contributors. (Contributors who also send me gifts of coffee,
1017chocolate, or currency will have their names listed in bold.)
1018
1019
1020Contributors
1021============
1022
1023Individuals who contributed to this documentation (in order by last
1024name):
1025
1026* Robin Dunn
1027* Patrick K. O'Brien
1028* Robert Roebling
1029* Julian Smart
1030* Vadim Zeitlin
1031
1032
1033License
1034=======
1035
1036This document began as a translation of the wxWindows documentation.
1037As such, it adheres to the same license, which is provided here:
1038
1039.. include:: ../licence/licendoc.txt
1040 :literal: