More doxygen topic overview cleanup.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52237 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/docs/doxygen/overviews/printing.h b/docs/doxygen/overviews/printing.h
index d0b045b58b28d3e7ee005774ca1957394a111b68..de21b4b77b6965c9f553c47a93454a8e510c795e 100644 (file)
--- a/docs/doxygen/overviews/printing.h
+++ b/docs/doxygen/overviews/printing.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        printing
+// Name:        printing.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,197 +8,207 @@
 
 /*!
 
 
 /*!
 

- @page overview_printing Printing overview
-
- Classes: #wxPrintout,
- #wxPrinter,
- #wxPrintPreview,
- #wxPrinterDC,
- #wxPostScriptDC,
- #wxPrintDialog,
- #wxPrintData,
- #wxPrintDialogData,
- #wxPageSetupDialog,
- #wxPageSetupDialogData
- The printing framework relies on the application to provide classes whose member
- functions can respond to particular requests, such as 'print this page' or 'does
- this page exist in the document?'. This method allows wxWidgets to take over the
- housekeeping duties of turning preview pages, calling the print dialog box,
- creating the printer device context, and so on: the application can concentrate
- on the rendering of the information onto a device context.
- In most cases, the only class you will need to derive from is
- #wxPrintout; all others will be used as-is.
- A brief description of each class's role and how they work together follows.
- For the special case of printing under Unix, where various different
- printing backends have to be offered, please have a look at the
- @ref unixprinting_overview.
- @ref topic9_overview
- @ref topic10_overview
- @ref topic11_overview
- @ref topic12_overview
- @ref topic13_overview
- @ref topic14_overview
- @ref topic15_overview
- @ref topic16_overview
- @ref topic17_overview
- @ref topic18_overview
-
-
- @section topic9 #wxPrintout
-
- A document's printing ability is represented in an application by a derived
- wxPrintout class. This class prints a page on request, and can be passed to the
- Print function of a wxPrinter object to actually print the document, or can be
- passed to a wxPrintPreview object to initiate previewing. The following code
- (from the printing sample) shows how easy it is to initiate printing, previewing
- and the print setup dialog, once the wxPrintout functionality has been defined.
- Notice the use of MyPrintout for both printing and previewing. All the preview
- user interface functionality is taken care of by wxWidgets. For more details on how
- MyPrintout is defined, please look at the printout sample code.
-
- @code
- case WXPRINT_PRINT:
-     {
-       wxPrinter printer;
-       MyPrintout printout("My printout");
-       printer.Print(this, , @true);
-       break;
-     }
-     case WXPRINT_PREVIEW:
-     {
-       // Pass two printout objects: for preview, and possible printing.
-       wxPrintPreview *preview = new wxPrintPreview(new MyPrintout, new MyPrintout);
-       wxPreviewFrame *frame = new wxPreviewFrame(preview, this, "Demo Print Preview", wxPoint(100, 100), wxSize(600, 650));
-       frame-Centre(wxBOTH);
-       frame-Initialize();
-       frame-Show(@true);
-       break;
-     }
- @endcode
-
- Class #wxPrintout assembles the printed page and (using
- your subclass's overrides) writes requested pages to a #wxDC that
- is passed to it. This wxDC could be a #wxMemoryDC (for
- displaying the preview image on-screen), a #wxPrinterDC
- (for printing under MSW and Mac), or a #wxPostScriptDC
- (for printing under GTK or generating PostScript output).
- The @ref docview_overview creates a default
- wxPrintout object for every view, calling wxView::OnDraw to achieve a
- prepackaged print/preview facility.
- If your window classes have a Draw(wxDC *dc) routine to do screen rendering,
- your wxPrintout subclass will typically call those routines to create portions
- of the image on your printout. Your wxPrintout subclass can also make its own
- calls to its wxDC to draw headers, footers, page numbers, etc.
- The scaling of the drawn image typically differs from the screen to the preview
- and printed images. This class provides a set of routines named
- FitThisSizeToXXX(), MapScreenSizeToXXX(), and GetLogicalXXXRect, which can be
- used to set the user scale and origin of the wxPrintout's DC so that your class
- can easily map your image to the printout withough getting into the details of
- screen and printer PPI and scaling. See the printing sample for examples of how
- these routines are used.
-
- @section topic10 #wxPrinter
-
- Class wxPrinter encapsulates the platform-dependent print function with a common
- interface. In most cases, you will not need to derive a class from wxPrinter;
- simply create a wxPrinter object in your Print function as in the example above.
-
- @section topic11 #wxPrintPreview
-
- Class wxPrintPreview manages the print preview process. Among other things, it
- constructs the wxDCs that get passed to your wxPrintout subclass for printing
- and manages the display of multiple pages, a zoomable preview image, and so
- forth. In most cases you will use this class as-is, but you can create your own
- subclass, for example, to change the layout or contents of the preview window.
-
-
- @section topic12 #wxPrinterDC
-
- Class wxPrinterDC is the wxDC that represents the actual printed page under MSW
- and Mac. During printing, an object of this class will be passed to your derived
- wxPrintout object to draw upon. The size of the wxPrinterDC will depend on the
- paper orientation and the resolution of the printer.
- There are two important rectangles in printing: the page rectangle defines
- the printable area seen by the application, and under MSW and Mac, it is the
- printable area specified by the printer. (For PostScript printing, the page
- rectangle is the entire page.) The inherited function
- wxDC::GetSize returns the page size in device pixels. The
- point (0,0) on the wxPrinterDC represents the top left corner of the page
- rectangle; that is, the page rect is given by wxRect(0, 0, w, h), where (w,h)
- are the values returned by GetSize.
- The paper rectangle, on the other hand, represents the entire paper area
- including the non-printable border. Thus, the coordinates of the top left corner
- of the paper rectangle will have small negative values, while the width and
- height will be somewhat larger than that of the page rectangle. The
- wxPrinterDC-specific function
- wxPrinterDC::GetPaperRect returns the paper
- rectangle of the given wxPrinterDC.
-
- @section topic13 #wxPostScriptDC
-
- Class wxPostScriptDC is the wxDC that represents the actual printed page under
- GTK and other PostScript printing. During printing, an object of this class will
- be passed to your derived wxPrintout object to draw upon. The size of the
- wxPostScriptDC will depend upon the #wxPrintData used to
- construct it.
- Unlike a wxPrinterDC, there is no distinction between the page rectangle and the
- paper rectangle in a wxPostScriptDC; both rectangles are taken to represent the
- entire sheet of paper.
-
- @section topic14 #wxPrintDialog
-
- Class wxPrintDialog puts up the standard print dialog, which allows you to
- select the page range for printing (as well as many other print settings, which
- may vary from platform to platform). You provide an object of type
- #wxPrintDialogData to the wxPrintDialog at
- construction, which is used to populate the dialog.
-
- @section topic15 #wxPrintData
-
- Class wxPrintData is a subset of wxPrintDialogData that is used (internally) to
- initialize a wxPrinterDC or wxPostScriptDC. (In fact, a wxPrintData is a data
- member of a wxPrintDialogData and a wxPageSetupDialogData). Essentially,
- wxPrintData contains those bits of information from the two dialogs necessary to
- configure the wxPrinterDC or wxPostScriptDC (e.g., size, orientation, etc.). You
- might wish to create a global instance of this object to provide call-to-call
- persistence to your application's print settings.
-
- @section topic16 #wxPrintDialogData
-
- Class wxPrintDialogData contains the settings entered by the user in the print
- dialog. It contains such things as page range, number of copies, and so forth.
- In most cases, you won't need to access this information; the framework takes
- care of asking your wxPrintout derived object for the pages requested by the
- user.
-
- @section topic17 #wxPageSetupDialog
-
- Class wxPageSetupDialog puts up the standard page setup dialog, which allows you
- to specify the orientation, paper size, and related settings. You provide it
- with a wxPageSetupDialogData object at intialization, which is used to populate
- the dialog; when the dialog is dismissed, this object contains the settings
- chosen by the user, including orientation and/or page margins.
- Note that on Macintosh, the native page setup dialog does not contain entries
- that allow you to change the page margins. You can use the Mac-specific class
- wxMacPageMarginsDialog (which, like wxPageSetupDialog, takes a
- wxPageSetupDialogData object in its constructor) to provide this capability; see
- the printing sample for an example.
-
- @section topic18 #wxPageSetupDialogData
-
- Class wxPageSetupDialogData contains settings affecting the page size (paper
- size), orientation, margins, and so forth. Note that not all platforms populate
- all fields; for example, the MSW page setup dialog lets you set the page margins
- while the Mac setup dialog does not.
- You will typically create a global instance of each of a wxPrintData and
- wxPageSetupDialogData at program initiation, which will contain the default
- settings provided by the system. Each time the user calls up either the
- wxPrintDialog or the wxPageSetupDialog, you pass these data structures to
- initialize the dialog values and to be updated by the dialog. The framework then
- queries these data structures to get information like the printed page range
- (from the wxPrintDialogData) or the paper size and/or page orientation (from the
- wxPageSetupDialogData).
-
- */
+@page overview_printing Printing Overview
+
+Classes:
+@li wxPrintout
+@li wxPrinter
+@li wxPrintPreview
+@li wxPrinterDC
+@li wxPostScriptDC
+@li wxPrintDialog
+@li wxPrintData
+@li wxPrintDialogData
+@li wxPageSetupDialog
+@li wxPageSetupDialogData
+
+The printing framework relies on the application to provide classes whose
+member functions can respond to particular requests, such as 'print this page'
+or 'does this page exist in the document?'. This method allows wxWidgets to
+take over the housekeeping duties of turning preview pages, calling the print
+dialog box, creating the printer device context, and so on: the application can
+concentrate on the rendering of the information onto a device context.
+
+In most cases, the only class you will need to derive from is wxPrintout; all
+others will be used as-is.
+
+A brief description of each class's role and how they work together follows.
+
+For the special case of printing under Unix, where various different printing
+backends have to be offered, please have a look at @ref overview_unixprinting.
+
+
+@section overview_printing_printout wxPrintout
+
+A document's printing ability is represented in an application by a derived
+wxPrintout class. This class prints a page on request, and can be passed to the
+Print function of a wxPrinter object to actually print the document, or can be
+passed to a wxPrintPreview object to initiate previewing. The following code
+(from the printing sample) shows how easy it is to initiate printing,
+previewing and the print setup dialog, once the wxPrintout functionality has
+been defined. Notice the use of MyPrintout for both printing and previewing.
+All the preview user interface functionality is taken care of by wxWidgets. For
+more details on how MyPrintout is defined, please look at the printout sample
+code.
+
+@code
+case WXPRINT_PRINT:
+{
+    wxPrinter printer;
+    MyPrintout printout("My printout");
+    printer.Print(this, &printout, true);
+    break;
+}
+case WXPRINT_PREVIEW:
+{
+    // Pass two printout objects: for preview, and possible printing.
+    wxPrintPreview *preview = new wxPrintPreview(new MyPrintout, new MyPrintout);
+    wxPreviewFrame *frame = new wxPreviewFrame(preview, this,
+                                               "Demo Print Preview",
+                                               wxPoint(100, 100),
+                                               wxSize(600, 650));
+    frame->Centre(wxBOTH);
+    frame->Initialize();
+    frame->Show(true);
+    break;
+}
+@endcode
+
+wxPrintout assembles the printed page and (using your subclass's overrides)
+writes requested pages to a wxDC that is passed to it. This wxDC could be a
+wxMemoryDC (for displaying the preview image on-screen), a wxPrinterDC (for
+printing under MSW and Mac), or a wxPostScriptDC (for printing under GTK or
+generating PostScript output).
+
+The @ref overview_docview "document/view framework" creates a default
+wxPrintout object for every view, calling wxView::OnDraw to achieve a
+prepackaged print/preview facility.
+
+If your window classes have a Draw(wxDC *dc) routine to do screen rendering,
+your wxPrintout subclass will typically call those routines to create portions
+of the image on your printout. Your wxPrintout subclass can also make its own
+calls to its wxDC to draw headers, footers, page numbers, etc.
+
+The scaling of the drawn image typically differs from the screen to the preview
+and printed images. This class provides a set of routines named
+FitThisSizeToXXX(), MapScreenSizeToXXX(), and GetLogicalXXXRect, which can be
+used to set the user scale and origin of the wxPrintout's DC so that your class
+can easily map your image to the printout withough getting into the details of
+screen and printer PPI and scaling. See the printing sample for examples of how
+these routines are used.
+
+
+@section overview_printing_printer wxPrinter
+
+Class wxPrinter encapsulates the platform-dependent print function with a common
+interface. In most cases, you will not need to derive a class from wxPrinter;
+simply create a wxPrinter object in your Print function as in the example above.
+
+
+@section overview_printing_printpreview wxPrintPreview
+
+Class wxPrintPreview manages the print preview process. Among other things, it
+constructs the wxDCs that get passed to your wxPrintout subclass for printing
+and manages the display of multiple pages, a zoomable preview image, and so
+forth. In most cases you will use this class as-is, but you can create your own
+subclass, for example, to change the layout or contents of the preview window.
+
+
+@section overview_printing_printerdc wxPrinterDC
+
+Class wxPrinterDC is the wxDC that represents the actual printed page under MSW
+and Mac. During printing, an object of this class will be passed to your derived
+wxPrintout object to draw upon. The size of the wxPrinterDC will depend on the
+paper orientation and the resolution of the printer.
+
+There are two important rectangles in printing: the <em>page rectangle</em>
+defines the printable area seen by the application, and under MSW and Mac, it
+is the printable area specified by the printer. (For PostScript printing, the
+page rectangle is the entire page.) The inherited function
+wxDC::GetSize returns the page size in device pixels. The
+point (0,0) on the wxPrinterDC represents the top left corner of the page
+rectangle; that is, the page rect is given by wxRect(0, 0, w, h), where (w,h)
+are the values returned by GetSize.
+
+The <em>paper rectangle</em>, on the other hand, represents the entire paper
+area including the non-printable border. Thus, the coordinates of the top left
+corner of the paper rectangle will have small negative values, while the width
+and height will be somewhat larger than that of the page rectangle. The
+wxPrinterDC-specific function wxPrinterDC::GetPaperRect returns the paper
+rectangle of the given wxPrinterDC.
+
+
+@section overview_printing_postscriptdc wxPostScriptDC
+
+Class wxPostScriptDC is the wxDC that represents the actual printed page under
+GTK and other PostScript printing. During printing, an object of this class
+will be passed to your derived wxPrintout object to draw upon. The size of the
+wxPostScriptDC will depend upon the wxPrintData used to construct it.
+
+Unlike a wxPrinterDC, there is no distinction between the page rectangle and
+the paper rectangle in a wxPostScriptDC; both rectangles are taken to represent
+the entire sheet of paper.
+
+
+@section overview_printing_printdialog wxPrintDialog
+
+Class wxPrintDialog puts up the standard print dialog, which allows you to
+select the page range for printing (as well as many other print settings, which
+may vary from platform to platform). You provide an object of type
+wxPrintDialogData to the wxPrintDialog at construction, which is used to
+populate the dialog.
+
+
+@section overview_printing_printdata wxPrintData

 
 

+Class wxPrintData is a subset of wxPrintDialogData that is used (internally) to
+initialize a wxPrinterDC or wxPostScriptDC. (In fact, a wxPrintData is a data
+member of a wxPrintDialogData and a wxPageSetupDialogData). Essentially,
+wxPrintData contains those bits of information from the two dialogs necessary
+to configure the wxPrinterDC or wxPostScriptDC (e.g., size, orientation, etc.).
+You might wish to create a global instance of this object to provide
+call-to-call persistence to your application's print settings.
+
+
+@section overview_printing_printdialogdata wxPrintDialogData
+
+Class wxPrintDialogData contains the settings entered by the user in the print
+dialog. It contains such things as page range, number of copies, and so forth.
+In most cases, you won't need to access this information; the framework takes
+care of asking your wxPrintout derived object for the pages requested by the
+user.
+
+
+@section overview_printing_pagesetupdialog wxPageSetupDialog
+
+Class wxPageSetupDialog puts up the standard page setup dialog, which allows
+you to specify the orientation, paper size, and related settings. You provide
+it with a wxPageSetupDialogData object at intialization, which is used to
+populate the dialog; when the dialog is dismissed, this object contains the
+settings chosen by the user, including orientation and/or page margins.
+
+Note that on Macintosh, the native page setup dialog does not contain entries
+that allow you to change the page margins. You can use the Mac-specific class
+wxMacPageMarginsDialog (which, like wxPageSetupDialog, takes a
+wxPageSetupDialogData object in its constructor) to provide this capability;
+see the printing sample for an example.
+
+
+@section overview_printing_pagesetupdialogdata wxPageSetupDialogData
+
+Class wxPageSetupDialogData contains settings affecting the page size (paper
+size), orientation, margins, and so forth. Note that not all platforms populate
+all fields; for example, the MSW page setup dialog lets you set the page
+margins while the Mac setup dialog does not.
+
+You will typically create a global instance of each of a wxPrintData and
+wxPageSetupDialogData at program initiation, which will contain the default
+settings provided by the system. Each time the user calls up either the
+wxPrintDialog or the wxPageSetupDialog, you pass these data structures to
+initialize the dialog values and to be updated by the dialog. The framework
+then queries these data structures to get information like the printed page
+range (from the wxPrintDialogData) or the paper size and/or page orientation
+(from the wxPageSetupDialogData).
+
+*/

 
 

diff --git a/docs/doxygen/overviews/python.h b/docs/doxygen/overviews/python.h
index 2812ead7cdcb8291af9bdee2946d814ed777eb9e..71b1d25ff8ef92214c14426b85dec7cfe0f8d0bf 100644 (file)
--- a/docs/doxygen/overviews/python.h
+++ b/docs/doxygen/overviews/python.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        python
+// Name:        python.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,460 +8,464 @@
 
 /*!
 
 
 /*!
 

- @page python_overview wxPython overview
-
- This topic was written by Robin Dunn, author of the wxPython wrapper.
- @ref pwhat_overview
- @ref pwhy_overview
- @ref pother_overview
- @ref pusing_overview
- @ref pclasses_overview
- @ref phelp_overview
-
-
- @section wxpwhat What is wxPython?
-
- wxPython is a blending of the wxWidgets GUI classes and the
- #Python programming language.
- @b Python
- So what is Python?  Go to
- #http://www.python.org to learn more,
- but in a nutshell Python is an interpreted,
- interactive, object-oriented programming language. It is often
- compared to Tcl, Perl, Scheme or Java.
- Python combines remarkable power with very clear syntax. It has
- modules, classes, exceptions, very high level dynamic data types, and
- dynamic typing. There are interfaces to many system calls and
- libraries, and new built-in modules are easily written in C or
- C++. Python is also usable as an extension language for applications
- that need a programmable interface.
- Python is copyrighted but freely usable and distributable, even for
- commercial use.
- @b wxPython
- wxPython is a Python package that can be imported at runtime that
- includes a collection of Python modules and an extension module
- (native code). It provides a series of Python classes that mirror (or
- shadow) many of the wxWidgets GUI classes. This extension module
- attempts to mirror the class hierarchy of wxWidgets as closely as
- possible. This means that there is a wxFrame class in wxPython that
- looks, smells, tastes and acts almost the same as the wxFrame class in
- the C++ version.
- wxPython is very versatile. It can be used to create standalone GUI
- applications, or in situations where Python is embedded in a C++
- application as an internal scripting or macro language.
- Currently wxPython is available for Win32 platforms and the GTK
- toolkit (wxGTK) on most Unix/X-windows platforms. See the wxPython
- website #http://wxPython.org/ for
- details about getting wxPython working for you.
-
- @section wxpwhy Why use wxPython?
-
- So why would you want to use wxPython over just C++ and wxWidgets?
- Personally I prefer using Python for everything. I only use C++ when I
- absolutely have to eke more performance out of an algorithm, and even
- then I usually code it as an extension module and leave the majority
- of the program in Python.
- Another good thing to use wxPython for is quick prototyping of your
- wxWidgets apps. With C++ you have to continuously go though the
- edit-compile-link-run cycle, which can be quite time consuming. With
- Python it is only an edit-run cycle. You can easily build an
- application in a few hours with Python that would normally take a few
- days or longer with C++. Converting a wxPython app to a C++/wxWidgets app
- should be a straight forward task.
-
- @section wxpother Other Python GUIs
-
- There are other GUI solutions out there for Python.
- @b Tkinter
- Tkinter is the de facto standard GUI for Python. It is available
- on nearly every platform that Python and Tcl/TK are. Why Tcl/Tk?
- Well because Tkinter is just a wrapper around Tcl's GUI toolkit, Tk.
- This has its upsides and its downsides...
- The upside is that Tk is a pretty versatile toolkit. It can be made
- to do a lot of things in a lot of different environments. It is fairly
- easy to create new widgets and use them interchangeably in your
- programs.
- The downside is Tcl. When using Tkinter you actually have two
- separate language interpreters running, the Python interpreter and the
- Tcl interpreter for the GUI. Since the guts of Tcl is mostly about
- string processing, it is fairly slow as well. (Not too bad on a fast
- Pentium II, but you really notice the difference on slower machines.)
- It wasn't until the latest version of Tcl/Tk that native Look and
- Feel was possible on non-Motif platforms. This is because Tk
- usually implements its own widgets (controls) even when there are
- native controls available.
- Tkinter is a pretty low-level toolkit. You have to do a lot of work
- (verbose program code) to do things that would be much simpler with a higher
- level of abstraction.
- @b PythonWin
- PythonWin is an add-on package for Python for the Win32 platform. It
- includes wrappers for MFC as well as much of the Win32 API. Because
- of its foundation, it is very familiar for programmers who have
- experience with MFC and the Win32 API. It is obviously not compatible
- with other platforms and toolkits. PythonWin is organized as separate
- packages and modules so you can use the pieces you need without having
- to use the GUI portions.
- @b Others
- There are quite a few other GUI modules available for Python, some in
- active use, some that haven't been updated for ages. Most are simple
- wrappers around some C or C++ toolkit or another, and most are not
- cross-platform compatible. See @ref Graphics_overview
- for a listing of a few of them.
-
- @section wxpusing Using wxPython
-
- @b First things first...
- I'm not going to try and teach the Python language here. You can do
- that at the http://www.python.org/doc/tut/tut.html.
- I'm also going to assume that you know a bit about wxWidgets already,
- enough to notice the similarities in the classes used.
- Take a look at the following wxPython program. You can find a similar
- program in the @c wxPython/demo directory, named @c DialogUnits.py. If your
- Python and wxPython are properly installed, you should be able to run
- it by issuing this command:
-
-
-     @b @c python DialogUnits.py
-
-
-
-
-
- @code
- 001: ## import all of the wxPython GUI package
- 002: from wxPython.wx import *
- 003:
- 004: ## Create a new frame class, derived from the wxPython Frame.
- 005: class MyFrame(wxFrame):
- 006:
- 007:     def __init__(self, parent, id, title):
- 008:         # First, call the base class' __init__ method to create the frame
- 009:         wxFrame.__init__(self, parent, id, title,
- 010:                          wxPoint(100, 100), wxSize(160, 100))
- 011:
- 012:         # Associate some events with methods of this class
- 013:         EVT_SIZE(self, self.OnSize)
- 014:         EVT_MOVE(self, self.OnMove)
- 015:
- 016:         # Add a panel and some controls to display the size and position
- 017:         panel = wxPanel(self, -1)
- 018:         wxStaticText(panel, -1, "Size:",
- 019:                      wxDLG_PNT(panel, wxPoint(4, 4)),  wxDefaultSize)
- 020:         wxStaticText(panel, -1, "Pos:",
- 021:                      wxDLG_PNT(panel, wxPoint(4, 14)), wxDefaultSize)
- 022:         self.sizeCtrl = wxTextCtrl(panel, -1, "",
- 023:                                    wxDLG_PNT(panel, wxPoint(24, 4)),
- 024:                                    wxDLG_SZE(panel, wxSize(36, -1)),
- 025:                                    wxTE_READONLY)
- 026:         self.posCtrl = wxTextCtrl(panel, -1, "",
- 027:                                   wxDLG_PNT(panel, wxPoint(24, 14)),
- 028:                                   wxDLG_SZE(panel, wxSize(36, -1)),
- 029:                                   wxTE_READONLY)
- 030:
- 031:
- 032:     # This method is called automatically when the CLOSE event is
- 033:     # sent to this window
- 034:     def OnCloseWindow(self, event):
- 035:         # tell the window to kill itself
- 036:         self.Destroy()
- 037:
- 038:     # This method is called by the system when the window is resized,
- 039:     # because of the association above.
- 040:     def OnSize(self, event):
- 041:         size = event.GetSize()
- 042:         self.sizeCtrl.SetValue("%s, %s" % (size.width, size.height))
- 043:
- 044:         # tell the event system to continue looking for an event handler,
- 045:         # so the default handler will get called.
- 046:         event.Skip()
- 047:
- 048:     # This method is called by the system when the window is moved,
- 049:     # because of the association above.
- 050:     def OnMove(self, event):
- 051:         pos = event.GetPosition()
- 052:         self.posCtrl.SetValue("%s, %s" % (pos.x, pos.y))
- 053:
- 054:
- 055: # Every wxWidgets application must have a class derived from wxApp
- 056: class MyApp(wxApp):
- 057:
- 058:     # wxWidgets calls this method to initialize the application
- 059:     def OnInit(self):
- 060:
- 061:         # Create an instance of our customized Frame class
- 062:         frame = MyFrame(@NULL, -1, "This is a test")
- 063:         frame.Show(@true)
- 064:
- 065:         # Tell wxWidgets that this is our main window
- 066:         self.SetTopWindow(frame)
- 067:
- 068:         # Return a success flag
- 069:         return @true
- 070:
- 071:
- 072: app = MyApp(0)     # Create an instance of the application class
- 073: app.MainLoop()     # Tell it to start processing events
- 074:
- @endcode
-
-
-
- @b Things to notice
-
-
-  At line 2 the wxPython classes, constants, and etc. are imported
- into the current module's namespace. If you prefer to reduce
- namespace pollution you can use "@c from wxPython import wx" and
- then access all the wxPython identifiers through the wx module, for
- example, "@c wx.wxFrame".
-  At line 13 the frame's sizing and moving events are connected to
- methods of the class. These helper functions are intended to be like
- the event table macros that wxWidgets employs. But since static event
- tables are impossible with wxPython, we use helpers that are named the
- same to dynamically build the table. The only real difference is
- that the first argument to the event helpers is always the window that
- the event table entry should be added to.
-  Notice the use of @c wxDLG_PNT and @c wxDLG_SZE in lines 19
- - 29 to convert from dialog units to pixels. These helpers are unique
- to wxPython since Python can't do method overloading like C++.
-  There is an @c OnCloseWindow method at line 34 but no call to
- EVT_CLOSE to attach the event to the method. Does it really get
- called?  The answer is, yes it does. This is because many of the
- standard events are attached to windows that have the associated
- standard method names. I have tried to follow the lead of the
- C++ classes in this area to determine what is standard but since
- that changes from time to time I can make no guarantees, nor will it
- be fully documented. When in doubt, use an EVT_*** function.
-  At lines 17 to 21 notice that there are no saved references to
- the panel or the static text items that are created. Those of you
- who know Python might be wondering what happens when Python deletes
- these objects when they go out of scope. Do they disappear from the GUI?  They
- don't. Remember that in wxPython the Python objects are just shadows of the
- corresponding C++ objects. Once the C++ windows and controls are
- attached to their parents, the parents manage them and delete them
- when necessary. For this reason, most wxPython objects do not need to
- have a __del__ method that explicitly causes the C++ object to be
- deleted. If you ever have the need to forcibly delete a window, use
- the Destroy() method as shown on line 36.
-  Just like wxWidgets in C++, wxPython apps need to create a class
- derived from @c wxApp (line 56) that implements a method named
- @c OnInit, (line 59.) This method should create the application's
- main window (line 62) and use @c wxApp.SetTopWindow() (line 66) to
- inform wxWidgets about it.
-  And finally, at line 72 an instance of the application class is
- created. At this point wxPython finishes initializing itself, and calls
- the @c OnInit method to get things started. (The zero parameter here is
- a flag for functionality that isn't quite implemented yet. Just
- ignore it for now.)  The call to @c MainLoop at line 73 starts the event
- loop which continues until the application terminates or all the top
- level windows are closed.
-
-
-
- @section wxpclasses wxWidgets classes implemented in wxPython
-
- The following classes are supported in wxPython. Most provide nearly
- full implementations of the public interfaces specified in the C++
- documentation, others are less so. They will all be brought as close
- as possible to the C++ spec over time.
-
-
-  #wxAcceleratorEntry
-  #wxAcceleratorTable
-  #wxActivateEvent
-  #wxBitmap
-  #wxBitmapButton
-  #wxBitmapDataObject
-  wxBMPHandler
-  #wxBoxSizer
-  #wxBrush
-  #wxBusyInfo
-  #wxBusyCursor
-  #wxButton
-  #wxCalculateLayoutEvent
-  #wxCalendarCtrl
-  #wxCaret
-  #wxCheckBox
-  #wxCheckListBox
-  #wxChoice
-  #wxClientDC
-  #wxClipboard
-  #wxCloseEvent
-  #wxColourData
-  #wxColourDialog
-  #wxColour
-  #wxComboBox
-  #wxCommandEvent
-  #wxConfig
-  #wxControl
-  #wxCursor
-  #wxCustomDataObject
-  #wxDataFormat
-  #wxDataObject
-  #wxDataObjectComposite
-  #wxDataObjectSimple
-  #wxDateTime
-  #wxDateSpan
-  #wxDC
-  #wxDialog
-  #wxDirDialog
-  #wxDragImage
-  #wxDropFilesEvent
-  #wxDropSource
-  #wxDropTarget
-  #wxEraseEvent
-  #wxEvent
-  #wxEvtHandler
-  #wxFileConfig
-  #wxFileDataObject
-  #wxFileDialog
-  #wxFileDropTarget
-  #wxFileSystem
-  #wxFileSystemHandler
-  #wxFocusEvent
-  #wxFontData
-  #wxFontDialog
-  #wxFont
-  #wxFrame
-  #wxFSFile
-  #wxGauge
-  wxGIFHandler
-  #wxGLCanvas
-  #wxHtmlCell
-  #wxHtmlContainerCell
-  #wxHtmlDCRenderer
-  #wxHtmlEasyPrinting
-  #wxHtmlParser
-  #wxHtmlTagHandler
-  #wxHtmlTag
-  #wxHtmlWinParser
-  #wxHtmlPrintout
-  #wxHtmlWinTagHandler
-  #wxHtmlWindow
-  #wxIconizeEvent
-  #wxIcon
-  #wxIdleEvent
-  #wxImage
-  #wxImageHandler
-  #wxImageList
-  #wxIndividualLayoutConstraint
-  #wxInitDialogEvent
-  #wxInputStream
-  #wxInternetFSHandler
-  #wxJoystickEvent
-  wxJPEGHandler
-  #wxKeyEvent
-  #wxLayoutAlgorithm
-  #wxLayoutConstraints
-  #wxListBox
-  #wxListCtrl
-  #wxListEvent
-  #wxListItem
-  #wxMask
-  #wxMaximizeEvent
-  #wxMDIChildFrame
-  #wxMDIClientWindow
-  #wxMDIParentFrame
-  #wxMemoryDC
-  #wxMemoryFSHandler
-  #wxMenuBar
-  #wxMenuEvent
-  #wxMenuItem
-  #wxMenu
-  #wxMessageDialog
-  #wxMetaFileDC
-  #wxMiniFrame
-  #wxMouseEvent
-  #wxMoveEvent
-  #wxNotebookEvent
-  #wxNotebook
-  #wxPageSetupDialogData
-  #wxPageSetupDialog
-  #wxPaintDC
-  #wxPaintEvent
-  #wxPalette
-  #wxPanel
-  #wxPen
-  wxPNGHandler
-  #wxPoint
-  #wxPostScriptDC
-  #wxPreviewFrame
-  #wxPrintData
-  #wxPrintDialogData
-  #wxPrintDialog
-  #wxPrinter
-  #wxPrintPreview
-  #wxPrinterDC
-  #wxPrintout
-  #wxProcess
-  #wxQueryLayoutInfoEvent
-  #wxRadioBox
-  #wxRadioButton
-  #wxRealPoint
-  #wxRect
-  #wxRegionIterator
-  #wxRegion
-  #wxSashEvent
-  #wxSashLayoutWindow
-  #wxSashWindow
-  #wxScreenDC
-  #wxScrollBar
-  #wxScrollEvent
-  #wxScrolledWindow
-  #wxScrollWinEvent
-  wxShowEvent
-  #wxSingleChoiceDialog
-  #wxSizeEvent
-  #wxSize
-  #wxSizer
-  #wxSizerItem
-  #wxSlider
-  #wxSpinButton
-  #wxSpinEvent
-  #wxSplitterWindow
-  #wxStaticBitmap
-  #wxStaticBox
-  #wxStaticBoxSizer
-  #wxStaticLine
-  #wxStaticText
-  #wxStatusBar
-  #wxSysColourChangedEvent
-  #wxTaskBarIcon
-  #wxTextCtrl
-  #wxTextDataObject
-  #wxTextDropTarget
-  #wxTextEntryDialog
-  #wxTimer
-  #wxTimerEvent
-  #wxTimeSpan
-  #wxTipProvider
-  wxToolBarTool
-  #wxToolBar
-  #wxToolTip
-  #wxTreeCtrl
-  #wxTreeEvent
-  #wxTreeItemData
-  wxTreeItemId
-  #wxUpdateUIEvent
-  #wxValidator
-  #wxWindowDC
-  #wxWindow
-  #wxZipFSHandler
-
-
-
- @section wxphelp Where to go for help
-
- Since wxPython is a blending of multiple technologies, help comes from
- multiple sources. See
- #http://wxpython.org/ for details on
- various sources of help, but probably the best source is the
- wxPython-users mail list. You can view the archive or subscribe by
- going to
- #http://lists.wxwindows.org/mailman/listinfo/wxpython-users
- Or you can send mail directly to the list using this address:
- wxpython-users@lists.wxwindows.org
-
- */
+@page overview_python wxPython Overview

 
 

+This topic was written by Robin Dunn, author of the wxPython wrapper.
+
+@li @ref overview_python_what
+@li @ref overview_python_why
+@li @ref overview_python_othergui
+@li @ref overview_python_using
+@li @ref overview_python_classes
+@li @ref overview_python_help
+
+
+<hr>
+
+
+@section overview_python_what What is wxPython?
+
+wxPython is a blending of the wxWidgets GUI classes and the Python programming
+language.
+
+@subsection overview_python_what_py Python
+
+So what is Python?  Go to http://www.python.org to learn more, but in a
+nutshell Python is an interpreted, interactive, object-oriented programming
+language. It is often compared to Tcl, Perl, Scheme or Java.
+
+Python combines remarkable power with very clear syntax. It has modules,
+classes, exceptions, very high level dynamic data types, and dynamic typing.
+There are interfaces to many system calls and libraries, and new built-in
+modules are easily written in C or C++. Python is also usable as an extension
+language for applications that need a programmable interface.
+
+Python is copyrighted but freely usable and distributable, even for commercial
+use.
+
+@subsection overview_python_what_wxpy wxPython
+
+wxPython is a Python package that can be imported at runtime that includes a
+collection of Python modules and an extension module (native code). It provides
+a series of Python classes that mirror (or shadow) many of the wxWidgets GUI
+classes. This extension module attempts to mirror the class hierarchy of
+wxWidgets as closely as possible. This means that there is a wxFrame class in
+wxPython that looks, smells, tastes and acts almost the same as the wxFrame
+class in the C++ version.
+
+wxPython is very versatile. It can be used to create standalone GUI
+applications, or in situations where Python is embedded in a C++ application as
+an internal scripting or macro language.
+
+Currently wxPython is available for Win32 platforms and the GTK toolkit (wxGTK)
+on most Unix/X-windows platforms. See the wxPython website http://wxPython.org/
+for details about getting wxPython working for you.
+
+
+@section overview_python_why Why Use wxPython?
+
+So why would you want to use wxPython over just C++ and wxWidgets? Personally I
+prefer using Python for everything. I only use C++ when I absolutely have to
+eke more performance out of an algorithm, and even then I usually code it as an
+extension module and leave the majority of the program in Python.
+
+Another good thing to use wxPython for is quick prototyping of your wxWidgets
+apps. With C++ you have to continuously go though the edit-compile-link-run
+cycle, which can be quite time consuming. With Python it is only an edit-run
+cycle. You can easily build an application in a few hours with Python that
+would normally take a few days or longer with C++. Converting a wxPython app to
+a C++/wxWidgets app should be a straight forward task.
+
+
+@section overview_python_othergui Other Python GUIs
+
+There are other GUI solutions out there for Python.
+
+@subsection overview_python_othergui_tkinter Tkinter
+
+Tkinter is the de facto standard GUI for Python. It is available on nearly
+every platform that Python and Tcl/TK are. Why Tcl/Tk? Well because Tkinter is
+just a wrapper around Tcl's GUI toolkit, Tk. This has it's upsides and it's
+downsides...
+
+The upside is that Tk is a pretty versatile toolkit. It can be made to do a lot
+of things in a lot of different environments. It is fairly easy to create new
+widgets and use them interchangeably in your programs.
+
+The downside is Tcl. When using Tkinter you actually have two separate language
+interpreters running, the Python interpreter and the Tcl interpreter for the
+GUI. Since the guts of Tcl is mostly about string processing, it is fairly slow
+as well. (Not too bad on a fast Pentium II, but you really notice the
+difference on slower machines.)
+
+It wasn't until the latest version of Tcl/Tk that native Look and Feel was
+possible on non-Motif platforms. This is because Tk usually implements its own
+widgets (controls) even when there are native controls available.
+
+Tkinter is a pretty low-level toolkit. You have to do a lot of work (verbose
+program code) to do things that would be much simpler with a higher level of
+abstraction.
+
+@subsection overview_python_othergui_pythonwin PythonWin
+
+PythonWin is an add-on package for Python for the Win32 platform. It includes
+wrappers for MFC as well as much of the Win32 API. Because of its foundation,
+it is very familiar for programmers who have experience with MFC and the Win32
+API. It is obviously not compatible with other platforms and toolkits.
+PythonWin is organized as separate packages and modules so you can use the
+pieces you need without having to use the GUI portions.
+
+@subsection overview_python_othergui_others Others
+
+There are quite a few other GUI modules available for Python, some in active
+use, some that haven't been updated for ages. Most are simple wrappers around
+some C or C++ toolkit or another, and most are not cross-platform compatible.
+See http://pypi.python.org/pypi?:action=browse&show=all&c=433 for a listing of
+a few of them.
+
+
+@section overview_python_using Using wxPython
+
+I'm not going to try and teach the Python language here. You can do that at the
+<http://www.python.org/doc/tut/tut.html>. I'm also going to assume that you
+know a bit about wxWidgets already, enough to notice the similarities in the
+classes used.
+
+Take a look at the following wxPython program. You can find a similar program
+in the wxPython/demo directory, named "DialogUnits.py". If your Python and
+wxPython are properly installed, you should be able to run it by issuing this
+command:
+
+@code
+python DialogUnits.py
+@endcode
+
+@code
+01: ## import all of the wxPython GUI package
+02: from wxPython.wx import *
+03:
+04: ## Create a new frame class, derived from the wxPython Frame.
+05: class MyFrame(wxFrame):
+06:
+07:     def __init__(self, parent, id, title):
+08:         # First, call the base class' __init__ method to create the frame
+09:         wxFrame.__init__(self, parent, id, title,
+10:                          wxPoint(100, 100), wxSize(160, 100))
+11:
+12:         # Associate some events with methods of this class
+13:         EVT_SIZE(self, self.OnSize)
+14:         EVT_MOVE(self, self.OnMove)
+15:
+16:         # Add a panel and some controls to display the size and position
+17:         panel = wxPanel(self, -1)
+18:         wxStaticText(panel, -1, "Size:",
+19:                      wxDLG_PNT(panel, wxPoint(4, 4)),  wxDefaultSize)
+20:         wxStaticText(panel, -1, "Pos:",
+21:                      wxDLG_PNT(panel, wxPoint(4, 14)), wxDefaultSize)
+22:         self.sizeCtrl = wxTextCtrl(panel, -1, "",
+23:                                    wxDLG_PNT(panel, wxPoint(24, 4)),
+24:                                    wxDLG_SZE(panel, wxSize(36, -1)),
+25:                                    wxTE_READONLY)
+26:         self.posCtrl = wxTextCtrl(panel, -1, "",
+27:                                   wxDLG_PNT(panel, wxPoint(24, 14)),
+28:                                   wxDLG_SZE(panel, wxSize(36, -1)),
+29:                                   wxTE_READONLY)
+30:
+31:
+32:     # This method is called automatically when the CLOSE event is
+33:     # sent to this window
+34:     def OnCloseWindow(self, event):
+35:         # tell the window to kill itself
+36:         self.Destroy()
+37:
+38:     # This method is called by the system when the window is resized,
+39:     # because of the association above.
+40:     def OnSize(self, event):
+41:         size = event.GetSize()
+42:         self.sizeCtrl.SetValue("%s, %s" % (size.width, size.height))
+43:
+44:         # tell the event system to continue looking for an event handler,
+45:         # so the default handler will get called.
+46:         event.Skip()
+47:
+48:     # This method is called by the system when the window is moved,
+49:     # because of the association above.
+50:     def OnMove(self, event):
+51:         pos = event.GetPosition()
+52:         self.posCtrl.SetValue("%s, %s" % (pos.x, pos.y))
+53:
+54:
+55: # Every wxWidgets application must have a class derived from wxApp
+56: class MyApp(wxApp):
+57:
+58:     # wxWidgets calls this method to initialize the application
+59:     def OnInit(self):
+60:
+61:         # Create an instance of our customized Frame class
+62:         frame = MyFrame(NULL, -1, "This is a test")
+63:         frame.Show(true)
+64:
+65:         # Tell wxWidgets that this is our main window
+66:         self.SetTopWindow(frame)
+67:
+68:         # Return a success flag
+69:         return true
+70:
+71:
+72: app = MyApp(0)     # Create an instance of the application class
+73: app.MainLoop()     # Tell it to start processing events
+74:
+@endcode
+
+@subsection overview_python_using_notice Things to Notice
+
+At line 2 the wxPython classes, constants, and etc. are imported into the
+current module's namespace. If you prefer to reduce namespace pollution you can
+use "from wxPython import wx" and then access all the wxPython identifiers
+through the wx module, for example, "wx.wxFrame".
+
+At line 13 the frame's sizing and moving events are connected to methods of the
+class. These helper functions are intended to be like the event table macros
+that wxWidgets employs. But since static event tables are impossible with
+wxPython, we use helpers that are named the same to dynamically build the
+table. The only real difference is that the first argument to the event helpers
+is always the window that the event table entry should be added to.
+
+Notice the use of @c wxDLG_PNT and @c wxDLG_SZE in lines 19-29 to convert from
+dialog units to pixels. These helpers are unique to wxPython since Python can't
+do method overloading like C++.
+
+There is an @c OnCloseWindow method at line 34 but no call to EVT_CLOSE to
+attach the event to the method. Does it really get called?  The answer is, yes
+it does. This is because many of the standard events are attached to windows
+that have the associated standard method names. I have tried to follow the lead
+of the C++ classes in this area to determine what is standard but since that
+changes from time to time I can make no guarantees, nor will it be fully
+documented. When in doubt, use an EVT_*** function.
+
+At lines 17 to 21 notice that there are no saved references to the panel or the
+static text items that are created. Those of you who know Python might be
+wondering what happens when Python deletes these objects when they go out of
+scope. Do they disappear from the GUI?  They don't. Remember that in wxPython
+the Python objects are just shadows of the corresponding C++ objects. Once the
+C++ windows and controls are attached to their parents, the parents manage them
+and delete them when necessary. For this reason, most wxPython objects do not
+need to have a __del__ method that explicitly causes the C++ object to be
+deleted. If you ever have the need to forcibly delete a window, use the
+Destroy() method as shown on line 36.
+
+Just like wxWidgets in C++, wxPython apps need to create a class derived from
+@c wxApp (line 56) that implements a method named @c OnInit, (line 59.) This
+method should create the application's main window (line 62) and use
+wxApp.SetTopWindow() (line 66) to inform wxWidgets about it.
+
+And finally, at line 72 an instance of the application class is created. At
+this point wxPython finishes initializing itself, and calls the @c OnInit
+method to get things started. (The zero parameter here is a flag for
+functionality that isn't quite implemented yet. Just ignore it for now.) The
+call to @c MainLoop at line 73 starts the event loop which continues until the
+application terminates or all the top level windows are closed.
+
+
+@section overview_python_classes Classes Implemented in wxPython
+
+The following classes are supported in wxPython. Most provide nearly full
+implementations of the public interfaces specified in the C++ documentation,
+others are less so. They will all be brought as close as possible to the C++
+spec over time.
+
+@li wxAcceleratorEntry
+@li wxAcceleratorTable
+@li wxActivateEvent
+@li wxBitmap
+@li wxBitmapButton
+@li wxBitmapDataObject
+@li wxBMPHandler
+@li wxBoxSizer
+@li wxBrush
+@li wxBusyInfo
+@li wxBusyCursor
+@li wxButton
+@li wxCalculateLayoutEvent
+@li wxCalendarCtrl
+@li wxCaret
+@li wxCheckBox
+@li wxCheckListBox
+@li wxChoice
+@li wxClientDC
+@li wxClipboard
+@li wxCloseEvent
+@li wxColourData
+@li wxColourDialog
+@li wxColour
+@li wxComboBox
+@li wxCommandEvent
+@li wxConfig
+@li wxControl
+@li wxCursor
+@li wxCustomDataObject
+@li wxDataFormat
+@li wxDataObject
+@li wxDataObjectComposite
+@li wxDataObjectSimple
+@li wxDateTime
+@li wxDateSpan
+@li wxDC
+@li wxDialog
+@li wxDirDialog
+@li wxDragImage
+@li wxDropFilesEvent
+@li wxDropSource
+@li wxDropTarget
+@li wxEraseEvent
+@li wxEvent
+@li wxEvtHandler
+@li wxFileConfig
+@li wxFileDataObject
+@li wxFileDialog
+@li wxFileDropTarget
+@li wxFileSystem
+@li wxFileSystemHandler
+@li wxFocusEvent
+@li wxFontData
+@li wxFontDialog
+@li wxFont
+@li wxFrame
+@li wxFSFile
+@li wxGauge
+@li wxGIFHandler
+@li wxGLCanvas
+@li wxHtmlCell
+@li wxHtmlContainerCell
+@li wxHtmlDCRenderer
+@li wxHtmlEasyPrinting
+@li wxHtmlParser
+@li wxHtmlTagHandler
+@li wxHtmlTag
+@li wxHtmlWinParser
+@li wxHtmlPrintout
+@li wxHtmlWinTagHandler
+@li wxHtmlWindow
+@li wxIconizeEvent
+@li wxIcon
+@li wxIdleEvent
+@li wxImage
+@li wxImageHandler
+@li wxImageList
+@li wxIndividualLayoutConstraint
+@li wxInitDialogEvent
+@li wxInputStream
+@li wxInternetFSHandler
+@li wxJoystickEvent
+@li wxJPEGHandler
+@li wxKeyEvent
+@li wxLayoutAlgorithm
+@li wxLayoutConstraints
+@li wxListBox
+@li wxListCtrl
+@li wxListEvent
+@li wxListItem
+@li wxMask
+@li wxMaximizeEvent
+@li wxMDIChildFrame
+@li wxMDIClientWindow
+@li wxMDIParentFrame
+@li wxMemoryDC
+@li wxMemoryFSHandler
+@li wxMenuBar
+@li wxMenuEvent
+@li wxMenuItem
+@li wxMenu
+@li wxMessageDialog
+@li wxMetaFileDC
+@li wxMiniFrame
+@li wxMouseEvent
+@li wxMoveEvent
+@li wxNotebookEvent
+@li wxNotebook
+@li wxPageSetupDialogData
+@li wxPageSetupDialog
+@li wxPaintDC
+@li wxPaintEvent
+@li wxPalette
+@li wxPanel
+@li wxPen
+@li wxPNGHandler
+@li wxPoint
+@li wxPostScriptDC
+@li wxPreviewFrame
+@li wxPrintData
+@li wxPrintDialogData
+@li wxPrintDialog
+@li wxPrinter
+@li wxPrintPreview
+@li wxPrinterDC
+@li wxPrintout
+@li wxProcess
+@li wxQueryLayoutInfoEvent
+@li wxRadioBox
+@li wxRadioButton
+@li wxRealPoint
+@li wxRect
+@li wxRegionIterator
+@li wxRegion
+@li wxSashEvent
+@li wxSashLayoutWindow
+@li wxSashWindow
+@li wxScreenDC
+@li wxScrollBar
+@li wxScrollEvent
+@li wxScrolledWindow
+@li wxScrollWinEvent
+@li wxShowEvent
+@li wxSingleChoiceDialog
+@li wxSizeEvent
+@li wxSize
+@li wxSizer
+@li wxSizerItem
+@li wxSlider
+@li wxSpinButton
+@li wxSpinEvent
+@li wxSplitterWindow
+@li wxStaticBitmap
+@li wxStaticBox
+@li wxStaticBoxSizer
+@li wxStaticLine
+@li wxStaticText
+@li wxStatusBar
+@li wxSysColourChangedEvent
+@li wxTaskBarIcon
+@li wxTextCtrl
+@li wxTextDataObject
+@li wxTextDropTarget
+@li wxTextEntryDialog
+@li wxTimer
+@li wxTimerEvent
+@li wxTimeSpan
+@li wxTipProvider
+@li wxToolBarTool
+@li wxToolBar
+@li wxToolTip
+@li wxTreeCtrl
+@li wxTreeEvent
+@li wxTreeItemData
+@li wxTreeItemId
+@li wxUpdateUIEvent
+@li wxValidator
+@li wxWindowDC
+@li wxWindow
+@li wxZipFSHandler
+
+
+@section overview_python_help Where to Go for Help
+
+Since wxPython is a blending of multiple technologies, help comes from multiple
+sources. See http://wxpython.org/ for details on various sources of help, but
+probably the best source is the wxPython-users mail list. You can view the
+archive or subscribe by going to http://wxpython.org/maillist.php
+
+Or you can send mail directly to the list using this address:
+wxpython-users@lists.wxwidgets.org
+
+*/

 
 

diff --git a/docs/doxygen/overviews/runtimeclass.h b/docs/doxygen/overviews/runtimeclass.h
index 92116dfaeadf51ee9a6a0319264408ede675b4e6..39ee9cfdf4812952b6699bbf5bf9f63c7cec91ef 100644 (file)
--- a/docs/doxygen/overviews/runtimeclass.h
+++ b/docs/doxygen/overviews/runtimeclass.h
@@ -93,7 +93,7 @@ You can get the wxClassInfo for a class by using the CLASSINFO macro, e.g.
 CLASSINFO(wxFrame). You can get the wxClassInfo for an object using
 wxObject::GetClassInfo.
 
 CLASSINFO(wxFrame). You can get the wxClassInfo for an object using
 wxObject::GetClassInfo.
 

-@seeaslso
+@seealso

 
 @li wxObject
 @li wxCreateDynamicObject
 
 @li wxObject
 @li wxCreateDynamicObject

diff --git a/docs/doxygen/overviews/string.h b/docs/doxygen/overviews/string.h
index 7da5c19b8d12526ed70a3abe6d4ff0b260ad273e..6da53ca8f8251040c551d60503a9fd681e86650f 100644 (file)
--- a/docs/doxygen/overviews/string.h
+++ b/docs/doxygen/overviews/string.h
@@ -158,7 +158,7 @@ the resulting string with a @NULL) and are in general not very safe (passing
 functions are not standard at all. This is why in addition to all wxString
 functions, there are also a few global string functions which try to correct
 these problems: wxIsEmpty() verifies whether the string is empty (returning
 functions are not standard at all. This is why in addition to all wxString
 functions, there are also a few global string functions which try to correct
 these problems: wxIsEmpty() verifies whether the string is empty (returning

-@true for @NULL pointers), wxStrlen() also handles @NULLs correctly and returns
+@true for @NULL pointers), wxStrlen() also handles @NULL correctly and returns

 0 for them and wxStricmp() is just a platform-independent version of
 case-insensitive string comparison function known either as @c stricmp() or
 @c strcasecmp() on different platforms.
 0 for them and wxStricmp() is just a platform-independent version of
 case-insensitive string comparison function known either as @c stricmp() or
 @c strcasecmp() on different platforms.

diff --git a/docs/doxygen/overviews/thread.h b/docs/doxygen/overviews/thread.h
index 9dae705ae11027bae56d332c65c5fa718d5d98dc..ca8eb56d6ca6406cf5f8bcedb6986b13cca4965b 100644 (file)
--- a/docs/doxygen/overviews/thread.h
+++ b/docs/doxygen/overviews/thread.h
@@ -8,50 +8,51 @@
 
 /*!
 
 
 /*!
 

- @page overview_thread Multithreading overview
-
- Classes: #wxThread, #wxMutex, #wxCriticalSection, #wxCondition
-
- wxWidgets provides a complete set of classes encapsulating objects necessary in
- multithreaded (MT) programs: the wxThread class itself and different
- synchronization objects: mutexes (see wxMutex) and critical sections (see 
- wxCriticalSection)  with conditions (see wxCondition). The thread API in wxWidgets 
- resembles to POSIX1.c threads API (a.k.a. pthreads), although several functions have
- different names and some features inspired by Win32 thread API are there as well.
-
- These classes will hopefully make writing MT programs easier and they also
- provide some extra error checking (compared to the native (be it Win32 or Posix)
- thread API), however it is still a non-trivial undertaking especially for large
- projects. Before starting an MT application (or starting to add MT features to
- an existing one) it is worth asking oneself if there is no easier and safer way
- to implement the same functionality. Of course, in some situations threads
- really make sense (classical example is a server application which launches a
- new thread for each new client), but in others it might be a very poor choice
- (example: launching a separate thread when doing a long computation to show a
- progress dialog). Other implementation choices are available: for the progress
- dialog example it is far better to do the calculations in the idle handler
- (see @ref wxIdleEvent) or even simply do everything at once but call wxWindow::Update() 
- periodically to update the screen.
-
- If you do decide to use threads in your application, it is strongly recommended
- that no more than one thread calls GUI functions. The thread sample shows that
- it @e is possible for many different threads to call GUI functions at once
- (all the threads created in the sample access GUI), but it is a very poor design
- choice for anything except an example. The design which uses one GUI thread and
- several worker threads which communicate with the main one using events is much
- more robust and will undoubtedly save you countless problems (example: under
- Win32 a thread can only access GDI objects such as pens, brushes, c created by
- itself and not by the other threads).
-
- For communication between secondary threads and the main thread, you may use
- wxEvtHandler::AddPendingEvent or its short version #wxPostEvent. These functions
- have a thread-safe implementation so that they can be used as they are for
- sending events from one thread to another. However there is no built in method
- to send messages to the worker threads and you will need to use the available
- synchronization classes to implement the solution which suits your needs
- yourself. In particular, please note that it is not enough to derive
- your class from #wxThread and #wxEvtHandler to send messages to it: 
- in fact, this does not work at all.
+@page overview_thread Multithreading Overview
+
+Classes: wxThread, wxMutex, wxCriticalSection, wxCondition
+
+wxWidgets provides a complete set of classes encapsulating objects necessary in
+multithreaded (MT) programs: the wxThread class itself and different
+synchronization objects: mutexes (see wxMutex) and critical sections (see
+wxCriticalSection)  with conditions (see wxCondition). The thread API i
+wxWidgets resembles to POSIX1.c threads API (a.k.a. pthreads), although several
+functions have different names and some features inspired by Win32 thread API
+are there as well.
+
+These classes will hopefully make writing MT programs easier and they also
+provide some extra error checking (compared to the native (be it Win32 or
+Posix) thread API), however it is still a non-trivial undertaking especially
+for large projects. Before starting an MT application (or starting to add MT
+features to an existing one) it is worth asking oneself if there is no easier
+and safer way to implement the same functionality. Of course, in some
+situations threads really make sense (classical example is a server application
+which launches a new thread for each new client), but in others it might be a
+very poor choice (example: launching a separate thread when doing a long
+computation to show a progress dialog). Other implementation choices are
+available: for the progress dialog example it is far better to do the
+calculations in the idle handler (see wxIdleEvent) or even simply do everything
+at once but call wxWindow::Update() periodically to update the screen.
+
+If you do decide to use threads in your application, it is strongly recommended
+that no more than one thread calls GUI functions. The thread sample shows that
+it @e is possible for many different threads to call GUI functions at once (all
+the threads created in the sample access GUI), but it is a very poor design
+choice for anything except an example. The design which uses one GUI thread and
+several worker threads which communicate with the main one using events is much
+more robust and will undoubtedly save you countless problems (example: under
+Win32 a thread can only access GDI objects such as pens, brushes, c created by
+itself and not by the other threads).
+
+For communication between secondary threads and the main thread, you may use
+wxEvtHandler::AddPendingEvent or its short version wxPostEvent. These functions
+have a thread-safe implementation so that they can be used as they are for
+sending events from one thread to another. However there is no built in method
+to send messages to the worker threads and you will need to use the available
+synchronization classes to implement the solution which suits your needs
+yourself. In particular, please note that it is not enough to derive
+your class from wxThread and wxEvtHandler to send messages to it: in fact, this
+does not work at all.

 
 */
 
 
 */
 

diff --git a/docs/doxygen/overviews/tips.h b/docs/doxygen/overviews/tips.h
index ff41fe4389fc7e43a737483359da136cfce7bc32..f678bbd261d92518584b4b62fbc3cc01c192c594 100644 (file)
--- a/docs/doxygen/overviews/tips.h
+++ b/docs/doxygen/overviews/tips.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        tips
+// Name:        tips.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,76 +8,69 @@
 
 /*!
 
 
 /*!
 

- @page overview_tips wxTipProvider overview
-
- Many "modern" Windows programs have a feature (some would say annoyance) of
- presenting the user tips at program startup. While this is probably useless to
- the advanced users of the program, the experience shows that the tips may be
- quite helpful for the novices and so more and more programs now do this.
- For a wxWidgets programmer, implementing this feature is extremely easy. To
- show a tip, it is enough to just call #wxShowTip function
- like this:
-
- @code
- if ( ...show tips at startup?... )
-     {
-         wxTipProvider *tipProvider = wxCreateFileTipProvider("tips.txt", 0);
-         wxShowTip(windowParent, tipProvider);
-         delete tipProvider;
-     }
- @endcode
-
- Of course, you need to get the text of the tips from somewhere - in the example
- above, the text is supposed to be in the file tips.txt from where it is read by
- the @e tip provider. The tip provider is just an object of a class deriving
- from #wxTipProvider. It has to implement one pure
- virtual function of the base class: #GetTip.
- In the case of the tip provider created by
- #wxCreateFileTipProvider, the tips are just
- the lines of the text file.
-
- If you want to implement your own tip provider (for example, if you wish to
- hardcode the tips inside your program), you just have to derive another class
- from wxTipProvider and pass a pointer to the object of this class to wxShowTip - 
- then you don't need wxCreateFileTipProvider at all.
-
- You will probably want to save somewhere the index of the tip last
- shown - so that the program doesn't always show the same tip on startup. As you
- also need to remember whether to show tips or not (you shouldn't do it if the
- user unchecked "Show tips on startup" checkbox in the dialog), you will
- probably want to store both the index of the
- last shown tip (as returned by
- wxTipProvider::GetCurrentTip and the flag
- telling whether to show the tips at startup at all.
-
- In a tips.txt file, lines that begin with a # character are considered comments
- and are automatically skipped. Blank lines and lines only having spaces are also
- skipped.
-
- You can easily add runtime-translation capacity by placing each line of the
- tips.txt file inside the usual translation macro. For example, your tips.txt
- file would look like this:
-
- @code
- _("This is my first tip")
- _("This is my second tip")
- @endcode
-
- Now add your tips.txt file into the list of files that gettext searches
- for translatable strings. The tips will thus get included into your
- generated .po file catalog and be translated at runtime along with the rest of
- your application's translatable strings.
-
- Note1: Each line in the tips.txt file needs to strictly begin with exactly the
- 3 characters of underscore-parenthesis-doublequote, and end with
- doublequote-parenthesis, as shown above.
-
- Note2: Remember to escape any doublequote characters within the tip string with
- a backslash-doublequote.
-
- See the dialogs program in your samples folder for a working example inside a
- program.
-
- */
-
+@page overview_tips wxTipProvider Overview
+
+Many "modern" Windows programs have a feature (some would say annoyance) of
+presenting the user tips at program startup. While this is probably useless to
+the advanced users of the program, the experience shows that the tips may be
+quite helpful for the novices and so more and more programs now do this. For a
+wxWidgets programmer, implementing this feature is extremely easy. To show a
+tip, it is enough to just call wxShowTip function like this:
+
+@code
+if ( ...show tips at startup?... )
+{
+    wxTipProvider *tipProvider = wxCreateFileTipProvider("tips.txt", 0);
+    wxShowTip(windowParent, tipProvider);
+    delete tipProvider;
+}
+@endcode
+
+Of course, you need to get the text of the tips from somewhere - in the example
+above, the text is supposed to be in the file tips.txt from where it is read by
+the <em>tip provider</em>. The tip provider is just an object of a class
+deriving from wxTipProvider. It has to implement one pure virtual function of
+the base class: GetTip. In the case of the tip provider created by
+wxCreateFileTipProvider, the tips are just the lines of the text file.
+
+If you want to implement your own tip provider (for example, if you wish to
+hardcode the tips inside your program), you just have to derive another class
+from wxTipProvider and pass a pointer to the object of this class to
+wxShowTip - then you don't need wxCreateFileTipProvider at all.
+
+You will probably want to save somewhere the index of the tip last shown - so
+that the program doesn't always show the same tip on startup. As you also need
+to remember whether to show tips or not (you shouldn't do it if the user
+unchecked "Show tips on startup" checkbox in the dialog), you will probably
+want to store both the index of the last shown tip (as returned by
+wxTipProvider::GetCurrentTip and the flag telling whether to show the tips at
+startup at all.
+
+In a tips.txt file, lines that begin with a # character are considered comments
+and are automatically skipped. Blank lines and lines only having spaces are
+also skipped.
+
+You can easily add runtime-translation capacity by placing each line of the
+tips.txt file inside the usual translation macro. For example, your tips.txt
+file would look like this:
+
+@code
+_("This is my first tip")
+_("This is my second tip")
+@endcode
+
+Now add your tips.txt file into the list of files that gettext searches for
+translatable strings. The tips will thus get included into your generated .po
+file catalog and be translated at runtime along with the rest of your
+application's translatable strings.
+
+@note Each line in the tips.txt file needs to strictly begin with exactly the 3
+characters of underscore-parenthesis-doublequote, and end with
+doublequote-parenthesis, as shown above. Also, remember to escape any
+doublequote characters within the tip string with a backslash-doublequote.
+
+See the dialogs program in your samples folder for a working example inside a
+program.
+
+*/

 
 

diff --git a/docs/doxygen/overviews/toolbar.h b/docs/doxygen/overviews/toolbar.h
index dd2cc3de8f332468b2263c687ff8bc840697f5ab..4acbb584a86d12a9f8f2b7c855c0e717c5a07134 100644 (file)
--- a/docs/doxygen/overviews/toolbar.h
+++ b/docs/doxygen/overviews/toolbar.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        toolbar
+// Name:        toolbar.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,292 +8,77 @@
 
 /*!
 
 
 /*!
 

- @page overview_toolbar Toolbar overview
-
- Classes: #wxToolBar
-
- 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, wxWidgets 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.
-
- For each platform, the symbol @b wxToolBar is defined to be one of the
- specific toolbar classes.
-
- The following is a summary of the toolbar classes and their differences.
-
- - @b wxToolBarBase. This is a base class with pure virtual functions,
- and should not be used directly.
- - @b wxToolBarSimple. A simple toolbar class written entirely with generic wxWidgets
- functionality. A simple 3D effect for buttons is possible, but it is not consistent
- with the Windows look and feel. This toolbar can scroll, and you can have arbitrary
- numbers of rows and columns.
- - @b wxToolBarMSW. This class implements an old-style Windows toolbar, only on
- Windows. There are small, three-dimensional buttons, which do not (currently) reflect
- the current Windows colour settings: the buttons are grey. This is the default wxToolBar
- on 16-bit windows.
- - @b wxToolBar95. Uses the native Windows 95 toolbar class. It dynamically adjusts its
- background and button colours according to user colour settings.
- CreateTools must be called after the tools have been added.
- No absolute positioning is supported but you can specify the number
- of rows, and add tool separators with @b AddSeparator.
- Tooltips are supported. @b OnRightClick is not supported. This is the default wxToolBar
- on Windows 95, Windows NT 4 and above. With the style wxTB_FLAT, the flat toolbar
- look is used, with a border that is highlighted when the cursor moves over the buttons.
-
- 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 @b 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.
-
- @ref overview_usingtoolbarlibrary
-
-
- @section overview_usingtoolbarlibrary Using the toolbar library
-
- Include @c "wx/toolbar.h", or if using a class directly, one of:
-
- - @c "wx/msw/tbarmsw.h for wxToolBarMSW
- - @c "wx/msw/tbar95.h for wxToolBar95
- - @c "wx/tbarsmpl.h for wxToolBarSimple
-
-
- Example of toolbar use are given in the sample program "toolbar''. The
- source is given below. In fact it is out of date because recommended
- practise is to use event handlers (using EVT_MENU or EVT_TOOL) instead of
- overriding OnLeftClick.
-
-
- @code
- /////////////////////////////////////////////////////////////////////////////
- // Name:        test.cpp
- // Purpose:     wxToolBar sample
- // Author:      Julian Smart
- // Modified by:
- // Created:     04/01/98
- // RCS-ID:      $Id$
- // Copyright:   (c) Julian Smart
- // License:    wxWindows license
- /////////////////////////////////////////////////////////////////////////////
-
- // For compilers that support precompilation, includes "wx/wx.h".
- #include "wx/wxprec.h"
-
- #ifdef __BORLANDC__
- #pragma hdrstop
- #endif
-
- #ifndef WX_PRECOMP
- #include "wx/wx.h"
- #endif
-
- #include "wx/toolbar.h"
- #include wx/log.h
-
- #include "test.h"
-
- #if defined(__WXGTK__) || defined(__WXMOTIF__)
- #include "mondrian.xpm"
- #include "bitmaps/new.xpm"
- #include "bitmaps/open.xpm"
- #include "bitmaps/save.xpm"
- #include "bitmaps/copy.xpm"
- #include "bitmaps/cut.xpm"
- #include "bitmaps/print.xpm"
- #include "bitmaps/preview.xpm"
- #include "bitmaps/help.xpm"
- #endif
-
- IMPLEMENT_APP(MyApp)
-
- // The `main program' equivalent, creating the windows and returning the
- // main frame
- bool MyApp::OnInit(void)
- {
-   // Create the main frame window
-   MyFrame* frame = new MyFrame((wxFrame *) @NULL, -1, (const wxString) "wxToolBar Sample",
-      wxPoint(100, 100), wxSize(450, 300));
-
-   // Give it a status line
-   frame-CreateStatusBar();
-
-   // Give it an icon
-   frame-SetIcon(wxICON(mondrian));
-
-   // Make a menubar
-   wxMenu *fileMenu = new wxMenu;
-   fileMenu-Append(wxID_EXIT, "E", "Quit toolbar sample" );
-
-   wxMenu *helpMenu = new wxMenu;
-   helpMenu-Append(wxID_HELP, "", "About toolbar sample");
-
-   wxMenuBar* menuBar = new wxMenuBar;
-
-   menuBar-Append(fileMenu, "");
-   menuBar-Append(helpMenu, "");
-
-   // Associate the menu bar with the frame
-   frame-SetMenuBar(menuBar);
-
-   // Create the toolbar
-   frame-CreateToolBar(wxBORDER\_NONE|wxHORIZONTAL|wxTB_FLAT, ID_TOOLBAR);
-
-   frame-GetToolBar()-SetMargins( 2, 2 );
-
-   InitToolbar(frame-GetToolBar());
-
-   // Force a resize. This should probably be replaced by a call to a wxFrame
-   // function that lays out default decorations and the remaining content window.
-   wxSizeEvent event(wxSize(-1, -1), frame-GetId());
-   frame-OnSize(event);
-   frame-Show(@true);
-
-   frame-SetStatusText("Hello, wxWidgets");
-
-   SetTopWindow(frame);
-
-   return @true;
- }
-
- bool MyApp::InitToolbar(wxToolBar* toolBar)
- {
-   // Set up toolbar
-   wxBitmap* toolBarBitmaps[8];
-
- #ifdef __WXMSW__
-   toolBarBitmaps[0] = new wxBitmap("icon1");
-   toolBarBitmaps[1] = new wxBitmap("icon2");
-   toolBarBitmaps[2] = new wxBitmap("icon3");
-   toolBarBitmaps[3] = new wxBitmap("icon4");
-   toolBarBitmaps[4] = new wxBitmap("icon5");
-   toolBarBitmaps[5] = new wxBitmap("icon6");
-   toolBarBitmaps[6] = new wxBitmap("icon7");
-   toolBarBitmaps[7] = new wxBitmap("icon8");
- #else
-   toolBarBitmaps[0] = new wxBitmap( new_xpm );
-   toolBarBitmaps[1] = new wxBitmap( open_xpm );
-   toolBarBitmaps[2] = new wxBitmap( save_xpm );
-   toolBarBitmaps[3] = new wxBitmap( copy_xpm );
-   toolBarBitmaps[4] = new wxBitmap( cut_xpm );
-   toolBarBitmaps[5] = new wxBitmap( preview_xpm );
-   toolBarBitmaps[6] = new wxBitmap( print_xpm );
-   toolBarBitmaps[7] = new wxBitmap( help_xpm );
- #endif
-
- #ifdef __WXMSW__
-   int width = 24;
- #else
-   int width = 16;
- #endif
-   int currentX = 5;
-
-   toolBar-AddTool(wxID_NEW, *(toolBarBitmaps[0]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "New file");
-   currentX += width + 5;
-   toolBar-AddTool(wxID_OPEN, *(toolBarBitmaps[1]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Open file");
-   currentX += width + 5;
-   toolBar-AddTool(wxID_SAVE, *(toolBarBitmaps[2]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Save file");
-   currentX += width + 5;
-   toolBar-AddSeparator();
-   toolBar-AddTool(wxID_COPY, *(toolBarBitmaps[3]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Copy");
-   currentX += width + 5;
-   toolBar-AddTool(wxID_CUT, *(toolBarBitmaps[4]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Cut");
-   currentX += width + 5;
-   toolBar-AddTool(wxID_PASTE, *(toolBarBitmaps[5]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Paste");
-   currentX += width + 5;
-   toolBar-AddSeparator();
-   toolBar-AddTool(wxID_PRINT, *(toolBarBitmaps[6]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Print");
-   currentX += width + 5;
-   toolBar-AddSeparator();
-   toolBar-AddTool(wxID_HELP, *(toolBarBitmaps[7]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Help");
-
-   toolBar-Realize();
-
-   // Can delete the bitmaps since they're reference counted
-   int i;
-   for (i = 0; i  8; i++)
-     delete toolBarBitmaps[i];
-
-   return @true;
- }
-
- // wxID_HELP will be processed for the 'About' menu and the toolbar help button.
-
- BEGIN_EVENT_TABLE(MyFrame, wxFrame)
-     EVT_MENU(wxID_EXIT, MyFrame::OnQuit)
-     EVT_MENU(wxID_HELP, MyFrame::OnAbout)
-     EVT_CLOSE(MyFrame::OnCloseWindow)
-     EVT_TOOL_RANGE(wxID_OPEN, wxID_PASTE, MyFrame::OnToolLeftClick)
-     EVT_TOOL_ENTER(wxID_OPEN, MyFrame::OnToolEnter)
- END_EVENT_TABLE()
-
- // Define my frame constructor
- MyFrame::MyFrame(wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos,
-         const wxSize& size, long style):
-   wxFrame(parent, id, title, pos, size, style)
- {
-   m_textWindow = new wxTextCtrl(this, -1, "", wxPoint(0, 0), wxSize(-1, -1), wxTE_MULTILINE);
- }
-
- void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
- {
-     Close(@true);
- }
-
- void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
- {
-     (void)wxMessageBox("wxWidgets toolbar sample", "About wxToolBar");
- }
-
- // Define the behaviour for the frame closing
- // - must delete all frames except for the main one.
- void MyFrame::OnCloseWindow(wxCloseEvent& WXUNUSED(event))
- {
-   Destroy();
- }
-
- void MyFrame::OnToolLeftClick(wxCommandEvent& event)
- {
-   wxString str;
-   str.Printf("Clicked on tool %d", event.GetId());
-   SetStatusText(str);
- }
-
- void MyFrame::OnToolEnter(wxCommandEvent& event)
- {
-   if (event.GetSelection()  -1)
-   {
-     wxString str;
-     str.Printf("This is tool number %d", event.GetSelection());
-     SetStatusText(str);
-   }
-   else
-     SetStatusText("");
- }
- @endcode
-
- */
-
+@page overview_toolbar Toolbar Overview
+
+Classes: wxToolBar
+
+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, wxWidgets 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.
+
+For each platform, the symbol wxToolBar is defined to be one of the specific
+toolbar classes.
+
+The following is a summary of the toolbar classes and their differences:
+
+@li wxToolBarBase: This is a base class with pure virtual functions, and should
+    not be used directly.
+@li wxToolBarSimple: A simple toolbar class written entirely with generic
+    wxWidgets functionality. A simple 3D effect for buttons is possible, but it
+    is not consistent with the Windows look and feel. This toolbar can scroll,
+    and you can have arbitrary numbers of rows and columns.
+@li wxToolBarMSW: This class implements an old-style Windows toolbar, only on
+    Windows. There are small, three-dimensional buttons, which do not
+    (currently) reflect the current Windows colour settings: the buttons are
+    grey. This is the default wxToolBar on 16-bit windows.
+@li wxToolBar95: Uses the native Windows 95 toolbar class. It dynamically
+    adjusts it's background and button colours according to user colour
+    settings. CreateTools must be called after the tools have been added. No
+    absolute positioning is supported but you can specify the number of rows,
+    and add tool separators with @c AddSeparator. Tooltips are supported.
+    @c OnRightClick is not supported. This is the default wxToolBar on Windows
+    95, Windows NT 4 and above. With the style wxTB_FLAT, the flat toolbar look
+    is used, with a border that is highlighted when the cursor moves over the
+    buttons.
+
+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
+@c 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.
+
+
+@section overview_toolbar_library Using the Toolbar Library
+
+Include @c "wx/toolbar.h", or if using a class directly, one of:
+
+- @c "wx/msw/tbarmsw.h" for wxToolBarMSW
+- @c "wx/msw/tbar95.h" for wxToolBar95
+- @c "wx/tbarsmpl.h" for wxToolBarSimple
+
+An example of using a toolbar is given in the "toolbar" sample.
+
+*/

 
 

diff --git a/docs/doxygen/overviews/treectrl.h b/docs/doxygen/overviews/treectrl.h
index 4a3f07300a314081730770b76c06aa93da873a8f..b501a86831769776388607f24e9118a67c6da45d 100644 (file)
--- a/docs/doxygen/overviews/treectrl.h
+++ b/docs/doxygen/overviews/treectrl.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        treectrl
+// Name:        treectrl.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,85 +8,75 @@
 
 /*!
 
 
 /*!
 

- @page overview_treectrl wxTreeCtrl overview
+@page overview_treectrl wxTreeCtrl Overview

 
 

- Classes: #wxTreeCtrl, #wxImageList
- 
- The tree control displays its items in a tree like structure. Each item has its
- own (optional) icon and a label. An item may be either collapsed (meaning that
- its children are not visible) or expanded (meaning that its children are
- shown). Each item in the tree is identified by its @e itemId which is of
- opaque data type @e wxTreeItemId. You can test whether an item is valid
- by calling wxTreeItemId::IsOk.
+Classes: wxTreeCtrl, wxImageList

 
 

- The items text and image may be retrieved and changed with
- #GetItemText/#SetItemText
- and
- #GetItemImage/#SetItemImage.
- In fact, an item may even have two images associated with it: the normal one
- and another one for selected state which is set/retrieved with
- #SetItemSelectedImage/#GetItemSelectedImage
- functions, but this functionality might be unavailable on some platforms.
+The tree control displays its items in a tree like structure. Each item has
+its own (optional) icon and a label. An item may be either collapsed (meaning
+that its children are not visible) or expanded (meaning that its children are
+shown). Each item in the tree is identified by its @c itemId which is of opaque
+data type wxTreeItemId. You can test whether an item is valid by calling
+wxTreeItemId::IsOk.

 
 

- Tree items have several attributes: an item may be selected or not, visible or
- not, bold or not. It may also be expanded or collapsed. All these attributes
- may be retrieved with the corresponding functions:
- #IsSelected,
- #IsVisible, #IsBold
- and #IsExpanded. Only one item at a time may be
- selected, selecting another one (with
- #SelectItem) automatically unselects the
- previously selected one.
+The items text and image may be retrieved and changed with (Get|Set)ItemText
+and (Get|Set)ItemImage. In fact, an item may even have two images associated
+with it: the normal one and another one for selected state which is
+set/retrieved with (Get|Set)ItemSelectedImage functions, but this functionality
+might be unavailable on some platforms.

 
 

- In addition to its icon and label, a user-specific data structure may be associated
- with all tree items. If you wish to do it, you should derive a class from @e wxTreeItemData which is a very simple class having only one function @e GetId() which returns the id of the item this data is associated with. This
- data will be freed by the control itself when the associated item is deleted
- (all items are deleted when the control is destroyed), so you shouldn't delete
- it yourself (if you do it, you should call
- #SetItemData(@NULL) to prevent the tree from
- deleting the pointer second time). The associated data may be retrieved with
- #GetItemData() function.
+Tree items have several attributes: an item may be selected or not, visible or
+not, bold or not. It may also be expanded or collapsed. All these attributes
+may be retrieved with the corresponding functions: IsSelected, IsVisible,
+IsBold and IsExpanded. Only one item at a time may be selected, selecting
+another one (with SelectItem) automatically unselects the previously selected
+one.

 
 

- Working with trees is relatively straightforward if all the items are added to
- the tree at the moment of its creation. However, for large trees it may be
- very inefficient. To improve the performance you may want to delay adding the
- items to the tree until the branch containing the items is expanded: so, in the
- beginning, only the root item is created (with
- #AddRoot). Other items are added when
- EVT_TREE_ITEM_EXPANDING event is received: then all items lying immediately
- under the item being expanded should be added, but, of course, only when this
- event is received for the first time for this item - otherwise, the items would
- be added twice if the user expands/collapses/re-expands the branch.
+In addition to its icon and label, a user-specific data structure may be
+associated with all tree items. If you wish to do it, you should derive a class
+from wxTreeItemData which is a very simple class having only one function
+GetId() which returns the id of the item this data is associated with. This
+data will be freed by the control itself when the associated item is deleted
+(all items are deleted when the control is destroyed), so you shouldn't delete
+it yourself (if you do it, you should call SetItemData(@NULL) to prevent the
+tree from deleting the pointer second time). The associated data may be
+retrieved with GetItemData() function.

 
 

- The tree control provides functions for enumerating its items. There are 3
- groups of enumeration functions: for the children of a given item, for the
- sibling of the given item and for the visible items (those which are currently
- shown to the user: an item may be invisible either because its branch is
- collapsed or because it is scrolled out of view). Child enumeration functions
- require the caller to give them a @e cookie parameter: it is a number which
- is opaque to the caller but is used by the tree control itself to allow
- multiple enumerations to run simultaneously (this is explicitly allowed). The
- only thing to remember is that the @e cookie passed to
- #GetFirstChild and to
- #GetNextChild should be the same variable (and
- that nothing should be done with it by the user code).
+Working with trees is relatively straightforward if all the items are added to
+the tree at the moment of its creation. However, for large trees it may be
+very inefficient. To improve the performance you may want to delay adding the
+items to the tree until the branch containing the items is expanded: so, in the
+beginning, only the root item is created (with AddRoot). Other items are added
+when EVT_TREE_ITEM_EXPANDING event is received: then all items lying
+immediately under the item being expanded should be added, but, of course, only
+when this event is received for the first time for this item - otherwise, the
+items would be added twice if the user expands/collapses/re-expands the branch.

 
 

- Among other features of the tree control are: item sorting with
- #SortChildren which uses the user-defined comparison
- function #OnCompareItems (by default the
- comparison is the alphabetic comparison of tree labels), hit testing
- (determining to which portion of the control the given point belongs, useful
- for implementing drag-and-drop in the tree) with
- #HitTest and editing of the tree item labels in
- place (see #EditLabel).
+The tree control provides functions for enumerating its items. There are 3
+groups of enumeration functions: for the children of a given item, for the
+sibling of the given item and for the visible items (those which are currently
+shown to the user: an item may be invisible either because its branch is
+collapsed or because it is scrolled out of view). Child enumeration functions
+require the caller to give them a @e cookie parameter: it is a number which
+is opaque to the caller but is used by the tree control itself to allow
+multiple enumerations to run simultaneously (this is explicitly allowed). The
+only thing to remember is that the @e cookie passed to GetFirstChild and to
+GetNextChild should be the same variable (and that nothing should be done with
+it by the user code).

 
 

- Finally, the tree control has a keyboard interface: the cursor navigation (arrow) keys
- may be used to change the current selection. HOME and END are used to go to
- the first/last sibling of the current item. '+', '-' and '*' expand, collapse
- and toggle the current branch. Note, however, that DEL and INS keys do
- nothing by default, but it is common to associate them with deleting an item from
- a tree and inserting a new one into it.
+Among other features of the tree control are: item sorting with SortChildren
+which uses the user-defined comparison function OnCompareItems (by default the
+comparison is the alphabetic comparison of tree labels), hit testing
+(determining to which portion of the control the given point belongs, useful
+for implementing drag-and-drop in the tree) with HitTest and editing of the
+tree item labels in place (see EditLabel).

 
 

- */
+Finally, the tree control has a keyboard interface: the cursor navigation
+(arrow) keys may be used to change the current selection. HOME and END are used
+to go to the first/last sibling of the current item. '+', '-' and '*' expand,
+collapse and toggle the current branch. Note, however, that DEL and INS keys do
+nothing by default, but it is common to associate them with deleting an item
+from a tree and inserting a new one into it.

 
 

+*/

 
 

diff --git a/docs/doxygen/overviews/unicode.h b/docs/doxygen/overviews/unicode.h
index 6d941f6c15a5fb5c2e174ee2c67397206a544cd4..0645ba06e37bab2b573009933de24d6e48439768 100644 (file)
--- a/docs/doxygen/overviews/unicode.h
+++ b/docs/doxygen/overviews/unicode.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        unicode
+// Name:        unicode.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,204 +8,200 @@
 
 /*!
 
 
 /*!
 

- @page overview_unicode Unicode support in wxWidgets
-
- This section briefly describes the state of the Unicode support in wxWidgets.
- Read it if you want to know more about how to write programs able to work with
- characters from languages other than English.
-
- @li @ref overview_whatisunicode
- @li @ref overview_unicodeandansi
- @li @ref overview_unicodeinsidewxw
- @li @ref overview_unicodeoutsidewxw
- @li @ref overview_unicodesettings
- @li @ref overview_topic8
-
-
- @section overview_whatisunicode What is Unicode?
-
- wxWidgets has support for compiling in Unicode mode
- on the platforms which support it. Unicode is a standard for character
- encoding which addresses the shortcomings of the previous, 8 bit standards, by
- using at least 16 (and possibly 32) bits for encoding each character. This
- allows to have at least 65536 characters (what is called the BMP, or basic
- multilingual plane) and possible 2^32 of them instead of the usual 256 and
- is sufficient to encode all of the world languages at once. More details about
- Unicode may be found at #http://www.unicode.org.
-
- As this solution is obviously preferable to the previous ones (think of
- incompatible encodings for the same language, locale chaos and so on), many
- modern operating systems support it. The probably first example is Windows NT
- which uses only Unicode internally since its very first version.
-
- Writing internationalized programs is much easier with Unicode and, as the
- support for it improves, it should become more and more so. Moreover, in the
- Windows NT/2000 case, even the program which uses only standard ASCII can profit
- from using Unicode because they will work more efficiently - there will be no
- need for the system to convert all strings the program uses to/from Unicode
- each time a system call is made.
-
- @section overview_unicodeandansi Unicode and ANSI modes
-
- As not all platforms supported by wxWidgets support Unicode (fully) yet, in
- many cases it is unwise to write a program which can only work in Unicode
- environment. A better solution is to write programs in such way that they may
- be compiled either in ANSI (traditional) mode or in the Unicode one.
-
- This can be achieved quite simply by using the means provided by wxWidgets.
- Basically, there are only a few things to watch out for:
-
-
- - Character type (@c char or @c wchar_t)
- - Literal strings (i.e. @c "Hello, world!" or @c '*')
- - String functions (@c strlen(), @c strcpy(), ...)
- - Special preprocessor tokens (@c __FILE__, @c __DATE__
- and @c __TIME__)
-
-
- Let's look at them in order. First of all, each character in an Unicode
- program takes 2 bytes instead of usual one, so another type should be used to
- store the characters (@c char only holds 1 byte usually). This type is
- called @c wchar_t which stands for @e wide-character type.
-
- Also, the string and character constants should be encoded using wide
- characters (@c wchar_t type) which typically take 2 or 4 bytes instead
- of @c char which only takes one. This is achieved by using the standard C
- (and C++) way: just put the letter @c 'L' after any string constant and it
- becomes a @e long constant, i.e. a wide character one. To make things a bit
- more readable, you are also allowed to prefix the constant with @c 'L'
- instead of putting it after it.
-
- Of course, the usual standard C functions don't work with @c wchar_t
- strings, so another set of functions exists which do the same thing but accept
- @c wchar_t * instead of @c char *. For example, a function to get the
- length of a wide-character string is called @c wcslen() (compare with
- @c strlen() - you see that the only difference is that the "str" prefix
- standing for "string" has been replaced with "wcs" standing for "wide-character
- string").
-
- And finally, the standard preprocessor tokens enumerated above expand to ANSI
- strings but it is more likely that Unicode strings are wanted in the Unicode
- build. wxWidgets provides the macros @c __TFILE__, @c __TDATE__
- and @c __TTIME__ which behave exactly as the standard ones except that
- they produce ANSI strings in ANSI build and Unicode ones in the Unicode build.
-
- To summarize, here is a brief example of how a program which can be compiled
- in both ANSI and Unicode modes could look like:
-
- @code
- #ifdef __UNICODE__
-     wchar_t wch = L'*';
-     const wchar_t *ws = L"Hello, world!";
-     int len = wcslen(ws);
-
-     wprintf(L"Compiled at %s\n", __TDATE__);
- #else // ANSI
-     char ch = '*';
-     const char *s = "Hello, world!";
-     int len = strlen(s);
-
-     printf("Compiled at %s\n", __DATE__);
- #endif // Unicode/ANSI
- @endcode
-
- Of course, it would be nearly impossibly to write such programs if it had to
- be done this way (try to imagine the number of @c #ifdef UNICODE an average
- program would have had!). Luckily, there is another way - see the next
- section.
-
- @section overview_unicodeinsidewxw Unicode support in wxWidgets
-
- In wxWidgets, the code fragment from above should be written instead:
-
- @code
- wxChar ch = wxT('*');
-     wxString s = wxT("Hello, world!");
-     int len = s.Len();
- @endcode
-
- What happens here? First of all, you see that there are no more @c #ifdefs
- at all. Instead, we define some types and macros which behave differently in
- the Unicode and ANSI builds and allow us to avoid using conditional
- compilation in the program itself.
-
- We have a @c wxChar type which maps either on @c char or @c wchar_t
- depending on the mode in which program is being compiled. There is no need for
- a separate type for strings though, because the standard
- #wxString supports Unicode, i.e. it stores either ANSI or
- Unicode strings depending on the compile mode.
-
- Finally, there is a special #wxT() macro which should enclose all
- literal strings in the program. As it is easy to see comparing the last
- fragment with the one above, this macro expands to nothing in the (usual) ANSI
- mode and prefixes @c 'L' to its argument in the Unicode mode.
-
- The important conclusion is that if you use @c wxChar instead of
- @c char, avoid using C style strings and use @c wxString instead and
- don't forget to enclose all string literals inside #wxT() macro, your
- program automatically becomes (almost) Unicode compliant!
-
- Just let us state once again the rules:
-
- - Always use @c wxChar instead of @c char
- - Always enclose literal string constants in #wxT() macro
- unless they're already converted to the right representation (another standard
- wxWidgets macro #_() does it, for example, so there is no
- need for @c wxT() in this case) or you intend to pass the constant directly
- to an external function which doesn't accept wide-character strings.
- - Use @c wxString instead of C style strings.
-
- @section overview_unicodeoutsidewxw Unicode and the outside world
-
- We have seen that it was easy to write Unicode programs using wxWidgets types
- and macros, but it has been also mentioned that it isn't quite enough.
- Although everything works fine inside the program, things can get nasty when
- it tries to communicate with the outside world which, sadly, often expects
- ANSI strings (a notable exception is the entire Win32 API which accepts either
- Unicode or ANSI strings and which thus makes it unnecessary to ever perform
- any conversions in the program). GTK 2.0 only accepts UTF-8 strings.
-
- To get an ANSI string from a wxString, you may use the
- mb_str() function which always returns an ANSI
- string (independently of the mode - while the usual
- #c_str() returns a pointer to the internal
- representation which is either ASCII or Unicode). More rarely used, but still
- useful, is wc_str() function which always returns
- the Unicode string.
-
- Sometimes it is also necessary to go from ANSI strings to wxStrings.
- In this case, you can use the converter-constructor, as follows:
-
-
- @code
- const char* ascii_str = "Some text";
-    wxString str(ascii_str, wxConvUTF8);
- @endcode
-
- This code also compiles fine under a non-Unicode build of wxWidgets,
- but in that case the converter is ignored.
-
- For more information about converters and Unicode see
- the @ref overview_mbconvclasses.
-
- @section overview_unicodesettings Unicode-related compilation settings
+@page overview_unicode Unicode Support in wxWidgets
+
+This section briefly describes the state of the Unicode support in wxWidgets.
+Read it if you want to know more about how to write programs able to work with
+characters from languages other than English.

 
 

- You should define @c wxUSE_UNICODE to 1 to compile your program in
- Unicode mode. This currently works for wxMSW, wxGTK, wxMac and wxX11. If you
- compile your program in ANSI mode you can still define @c wxUSE_WCHAR_T
- to get some limited support for @c wchar_t type.
-
- This will allow your program to perform conversions between Unicode strings and
- ANSI ones (using @ref overview_mbconvclasses)
- and construct wxString objects from Unicode strings (presumably read
- from some external file or elsewhere).
-
- @section overview_topic8 Traps for the unwary
+@li @ref overview_unicode_what
+@li @ref overview_unicode_ansi
+@li @ref overview_unicode_supportin
+@li @ref overview_unicode_supportout
+@li @ref overview_unicode_settings
+@li @ref overview_unicode_traps

 
 

- - Casting c_str() to void* is now char*, not wxChar*
- - Passing c_str(), mb_str() or wc_str() to variadic functions
- doesn't work

 
 

- */
+<hr>

 
 
 
 

+@section overview_unicode_what What is Unicode?
+
+wxWidgets has support for compiling in Unicode mode on the platforms which
+support it. Unicode is a standard for character encoding which addresses the
+shortcomings of the previous, 8 bit standards, by using at least 16 (and
+possibly 32) bits for encoding each character. This allows to have at least
+65536 characters (what is called the BMP, or basic multilingual plane) and
+possible 2^32 of them instead of the usual 256 and is sufficient to encode all
+of the world languages at once. More details about Unicode may be found at
+<http://www.unicode.org/>.
+
+As this solution is obviously preferable to the previous ones (think of
+incompatible encodings for the same language, locale chaos and so on), many
+modern operating systems support it. The probably first example is Windows NT
+which uses only Unicode internally since its very first version.
+
+Writing internationalized programs is much easier with Unicode and, as the
+support for it improves, it should become more and more so. Moreover, in the
+Windows NT/2000 case, even the program which uses only standard ASCII can
+profit from using Unicode because they will work more efficiently - there will
+be no need for the system to convert all strings the program uses to/from
+Unicode each time a system call is made.
+
+
+@section overview_unicode_ansi Unicode and ANSI Modes
+
+As not all platforms supported by wxWidgets support Unicode (fully) yet, in
+many cases it is unwise to write a program which can only work in Unicode
+environment. A better solution is to write programs in such way that they may
+be compiled either in ANSI (traditional) mode or in the Unicode one.
+
+This can be achieved quite simply by using the means provided by wxWidgets.
+Basically, there are only a few things to watch out for:
+
+- Character type (@c char or @c wchar_t)
+- Literal strings (i.e. @c "Hello, world!" or @c '*')
+- String functions (@c strlen(), @c strcpy(), ...)
+- Special preprocessor tokens (@c __FILE__, @c __DATE__ and @c __TIME__)
+
+Let's look at them in order. First of all, each character in an Unicode program
+takes 2 bytes instead of usual one, so another type should be used to store the
+characters (@c char only holds 1 byte usually). This type is called @c wchar_t
+which stands for @e wide-character type.
+
+Also, the string and character constants should be encoded using wide
+characters (@c wchar_t type) which typically take 2 or 4 bytes instead of
+@c char which only takes one. This is achieved by using the standard C (and
+C++) way: just put the letter @c 'L' after any string constant and it becomes a
+@e long constant, i.e. a wide character one. To make things a bit more
+readable, you are also allowed to prefix the constant with @c 'L' instead of
+putting it after it.
+
+Of course, the usual standard C functions don't work with @c wchar_t strings,
+so another set of functions exists which do the same thing but accept
+@c wchar_t* instead of @c char*. For example, a function to get the length of a
+wide-character string is called @c wcslen() (compare with @c strlen() - you see
+that the only difference is that the "str" prefix standing for "string" has
+been replaced with "wcs" standing for "wide-character string").
+
+And finally, the standard preprocessor tokens enumerated above expand to ANSI
+strings but it is more likely that Unicode strings are wanted in the Unicode
+build. wxWidgets provides the macros @c __TFILE__, @c __TDATE__ and
+@c __TTIME__ which behave exactly as the standard ones except that they produce
+ANSI strings in ANSI build and Unicode ones in the Unicode build.
+
+To summarize, here is a brief example of how a program which can be compiled
+in both ANSI and Unicode modes could look like:
+
+@code
+#ifdef __UNICODE__
+    wchar_t wch = L'*';
+    const wchar_t *ws = L"Hello, world!";
+    int len = wcslen(ws);
+
+    wprintf(L"Compiled at %s\n", __TDATE__);
+#else // ANSI
+    char ch = '*';
+    const char *s = "Hello, world!";
+    int len = strlen(s);
+
+    printf("Compiled at %s\n", __DATE__);
+#endif // Unicode/ANSI
+@endcode
+
+Of course, it would be nearly impossibly to write such programs if it had to
+be done this way (try to imagine the number of @ifdef UNICODE an average
+program would have had!). Luckily, there is another way - see the next section.
+
+
+@section overview_unicode_supportin Unicode Support in wxWidgets
+
+In wxWidgets, the code fragment from above should be written instead:
+
+@code
+wxChar ch = wxT('*');
+wxString s = wxT("Hello, world!");
+int len = s.Len();
+@endcode
+
+What happens here? First of all, you see that there are no more UNICODE checks
+at all. Instead, we define some types and macros which behave differently in
+the Unicode and ANSI builds and allow us to avoid using conditional compilation
+in the program itself.
+
+We have a @c wxChar type which maps either on @c char or @c wchar_t depending
+on the mode in which program is being compiled. There is no need for a separate
+type for strings though, because the standard wxString supports Unicode, i.e.
+it stores either ANSI or Unicode strings depending on the compile mode.
+
+Finally, there is a special wxT() macro which should enclose all literal
+strings in the program. As it is easy to see comparing the last fragment with
+the one above, this macro expands to nothing in the (usual) ANSI mode and
+prefixes @c 'L' to its argument in the Unicode mode.
+
+The important conclusion is that if you use @c wxChar instead of @c char, avoid
+using C style strings and use @c wxString instead and don't forget to enclose
+all string literals inside wxT() macro, your program automatically becomes
+(almost) Unicode compliant!
+
+Just let us state once again the rules:
+
+@li Always use wxChar instead of @c char
+@li Always enclose literal string constants in wxT() macro unless they're
+    already converted to the right representation (another standard wxWidgets
+    macro _() does it, for example, so there is no need for wxT() in this case)
+    or you intend to pass the constant directly to an external function which
+    doesn't accept wide-character strings.
+@li Use wxString instead of C style strings.
+
+
+@section overview_unicode_supportout Unicode and the Outside World
+
+We have seen that it was easy to write Unicode programs using wxWidgets types
+and macros, but it has been also mentioned that it isn't quite enough. Although
+everything works fine inside the program, things can get nasty when it tries to
+communicate with the outside world which, sadly, often expects ANSI strings (a
+notable exception is the entire Win32 API which accepts either Unicode or ANSI
+strings and which thus makes it unnecessary to ever perform any conversions in
+the program). GTK 2.0 only accepts UTF-8 strings.
+
+To get an ANSI string from a wxString, you may use the mb_str() function which
+always returns an ANSI string (independently of the mode - while the usual
+c_str() returns a pointer to the internal representation which is either ASCII
+or Unicode). More rarely used, but still useful, is wc_str() function which
+always returns the Unicode string.
+
+Sometimes it is also necessary to go from ANSI strings to wxStrings. In this
+case, you can use the converter-constructor, as follows:
+
+@code
+const char* ascii_str = "Some text";
+wxString str(ascii_str, wxConvUTF8);
+@endcode
+
+This code also compiles fine under a non-Unicode build of wxWidgets, but in
+that case the converter is ignored.
+
+For more information about converters and Unicode see the @ref overview_mbconv.
+
+
+@section overview_unicode_settings Unicode Related Compilation Settings
+
+You should define @c wxUSE_UNICODE to 1 to compile your program in Unicode
+mode. This currently works for wxMSW, wxGTK, wxMac and wxX11. If you compile
+your program in ANSI mode you can still define @c wxUSE_WCHAR_T to get some
+limited support for @c wchar_t type.
+
+This will allow your program to perform conversions between Unicode strings and
+ANSI ones (using @ref overview_mbconv "wxMBConv") and construct wxString
+objects from Unicode strings (presumably read from some external file or
+elsewhere).
+
+
+@section overview_unicode_traps Traps for the Unwary
+
+@li Casting c_str() to void* is now char*, not wxChar*
+@li Passing c_str(), mb_str() or wc_str() to variadic functions doesn't work.
+
+*/
+

diff --git a/docs/doxygen/overviews/unixprinting.h b/docs/doxygen/overviews/unixprinting.h
index 634a8b3d199657ade191c176a2e29f695c5a394d..c7aa0b69c242768ca6e27305a3bfc7fcd8246f76 100644 (file)
--- a/docs/doxygen/overviews/unixprinting.h
+++ b/docs/doxygen/overviews/unixprinting.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        unixprinting
+// Name:        unixprinting.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,46 +8,39 @@
 
 /*!
 
 
 /*!
 

- @page overview_unixprinting Printing under Unix (GTK+)
-
- Printing under Unix has always been a cause of problems as Unix
- does not provide a standard way to display text and graphics
- on screen and print it to a printer using the same application
- programming interface - instead, displaying on screen is done
- via the X11 library while printing has to be done with using
- PostScript commands. This was particularly difficult to handle
- for the case of fonts with the result that only a selected
- number of application could offer WYSIWYG under Unix. Equally,
- wxWidgets offered its own printing implementation using PostScript
- which never really matched the screen display.
-
- Starting with version 2.8.X, the GNOME project provides printing
- support through the libgnomeprint and libgnomeprintui libraries
- by which especially the font problem is mostly solved. Beginning
- with version 2.5.4, the GTK+ port of wxWidgets can make use of
- these libraries if wxWidgets is configured accordingly and if the
- libraries are present. You need to configure wxWidgets with the
- @e configure --with-gnomeprint switch and your application will
- then search for the GNOME print libraries at runtime. If they
- are found, printing will be done through these, otherwise the
- application will fall back to the old PostScript printing code.
- Note that the application will not require the GNOME print libraries
- to be installed in order to run (there will be no dependency on
- these libraries).
-
- In version GTK+ 2.10, support for printing has been added to GTK+
- itself. Beginning with version wxWidgets 2.9.X, the GTK+ port of
- wxWidgets can make use of this feature
- if wxWidgets is configured accordingly and if the GTK+ version is = 2.10.
- You need to configure wxWidgets with the @e configure --with-gtkprint
- switch and your application will then search for the GTK+ print support
- at runtime. If it is found, printing will be done through GTK+, otherwise the
- application will fall back to GNOME printing support if it is available or,
- if it isn't, to the old PostScript printing code.
- Note that the application will not require a GTK+ version = 2.10
- to be installed in order to run (there will be no dependency on
- this version).
-
- */
-
+@page overview_unixprinting Printing Under Unix (GTK+)
+
+Printing under Unix has always been a cause of problems as Unix does not
+provide a standard way to display text and graphics on screen and print it to a
+printer using the same application programming interface - instead, displaying
+on screen is done via the X11 library while printing has to be done with using
+PostScript commands. This was particularly difficult to handle for the case of
+fonts with the result that only a selected number of application could offer
+WYSIWYG under Unix. Equally, wxWidgets offered its own printing implementation
+using PostScript which never really matched the screen display.
+
+Starting with version 2.8.X, the GNOME project provides printing support
+through the libgnomeprint and libgnomeprintui libraries by which especially the
+font problem is mostly solved. Beginning with version 2.5.4, the GTK+ port of
+wxWidgets can make use of these libraries if wxWidgets is configured
+accordingly and if the libraries are present. You need to configure wxWidgets
+with the <tt>configure --with-gnomeprint</tt> switch and your application will
+then search for the GNOME print libraries at runtime. If they are found,
+printing will be done through these, otherwise the application will fall back
+to the old PostScript printing code. Note that the application will not require
+the GNOME print libraries to be installed in order to run (there will be no
+dependency on these libraries).
+
+In version GTK+ 2.10, support for printing has been added to GTK+ itself.
+Beginning with version wxWidgets 2.9.X, the GTK+ port of wxWidgets can make use
+of this feature if wxWidgets is configured accordingly and if the GTK+ version
+is = 2.10. You need to configure wxWidgets with the
+<tt>configure --with-gtkprint</tt> switch and your application will then search
+for the GTK+ print support at runtime. If it is found, printing will be done
+through GTK+, otherwise the application will fall back to GNOME printing
+support if it is available or, if it isn't, to the old PostScript printing
+code. Note that the application will not require a GTK+ version = 2.10 to be
+installed in order to run (there will be no dependency on this version).
+
+*/