Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More doxygen topic overview cleanup.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52237 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-03-02 04:32:30 +00:00
parent a85ad1db05
commit 2cd3cc948e
10 changed files with 1046 additions and 1274 deletions
Download Patch File Download Diff File Expand all files Collapse all files

372
docs/doxygen/overviews/printing.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: printing // Name: printing.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,197 +8,207 @@
/*! /*!
@page overview_printing Printing overview @page overview_printing Printing Overview
Classes: #wxPrintout, Classes:
#wxPrinter, @li wxPrintout
#wxPrintPreview, @li wxPrinter
#wxPrinterDC, @li wxPrintPreview
#wxPostScriptDC, @li wxPrinterDC
#wxPrintDialog, @li wxPostScriptDC
#wxPrintData, @li wxPrintDialog
#wxPrintDialogData, @li wxPrintData
#wxPageSetupDialog, @li wxPrintDialogData
#wxPageSetupDialogData @li wxPageSetupDialog
The printing framework relies on the application to provide classes whose member @li wxPageSetupDialogData
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 The printing framework relies on the application to provide classes whose
housekeeping duties of turning preview pages, calling the print dialog box, member functions can respond to particular requests, such as 'print this page'
creating the printer device context, and so on: the application can concentrate or 'does this page exist in the document?'. This method allows wxWidgets to
on the rendering of the information onto a device context. take over the housekeeping duties of turning preview pages, calling the print
In most cases, the only class you will need to derive from is dialog box, creating the printer device context, and so on: the application can
#wxPrintout; all others will be used as-is. concentrate on the rendering of the information onto a device context.
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 In most cases, the only class you will need to derive from is wxPrintout; all
printing backends have to be offered, please have a look at the others will be used as-is.
@ref unixprinting_overview.
@ref topic9_overview A brief description of each class's role and how they work together follows.
@ref topic10_overview
@ref topic11_overview For the special case of printing under Unix, where various different printing
@ref topic12_overview backends have to be offered, please have a look at @ref overview_unixprinting.
@ref topic13_overview
@ref topic14_overview
@ref topic15_overview
@ref topic16_overview
@ref topic17_overview
@ref topic18_overview
@section topic9 #wxPrintout @section overview_printing_printout wxPrintout
A document's printing ability is represented in an application by a derived 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 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 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 passed to a wxPrintPreview object to initiate previewing. The following code
(from the printing sample) shows how easy it is to initiate printing, previewing (from the printing sample) shows how easy it is to initiate printing,
and the print setup dialog, once the wxPrintout functionality has been defined. previewing and the print setup dialog, once the wxPrintout functionality has
Notice the use of MyPrintout for both printing and previewing. All the preview been defined. Notice the use of MyPrintout for both printing and previewing.
user interface functionality is taken care of by wxWidgets. For more details on how All the preview user interface functionality is taken care of by wxWidgets. For
MyPrintout is defined, please look at the printout sample code. more details on how MyPrintout is defined, please look at the printout sample
code.
@code @code
case WXPRINT_PRINT: case WXPRINT_PRINT:
{ {
wxPrinter printer; wxPrinter printer;
MyPrintout printout("My printout"); MyPrintout printout("My printout");
printer.Print(this, , @true); printer.Print(this, &printout, true);
break; break;
} }
case WXPRINT_PREVIEW: case WXPRINT_PREVIEW:
{ {
// Pass two printout objects: for preview, and possible printing. // Pass two printout objects: for preview, and possible printing.
wxPrintPreview *preview = new wxPrintPreview(new MyPrintout, new MyPrintout); wxPrintPreview *preview = new wxPrintPreview(new MyPrintout, new MyPrintout);
wxPreviewFrame *frame = new wxPreviewFrame(preview, this, "Demo Print Preview", wxPoint(100, 100), wxSize(600, 650)); wxPreviewFrame *frame = new wxPreviewFrame(preview, this,
frame-Centre(wxBOTH); "Demo Print Preview",
frame-Initialize(); wxPoint(100, 100),
frame-Show(@true); wxSize(600, 650));
break; frame->Centre(wxBOTH);
} frame->Initialize();
@endcode frame->Show(true);
break;
}
@endcode
Class #wxPrintout assembles the printed page and (using wxPrintout assembles the printed page and (using your subclass's overrides)
your subclass's overrides) writes requested pages to a #wxDC that writes requested pages to a wxDC that is passed to it. This wxDC could be a
is passed to it. This wxDC could be a #wxMemoryDC (for wxMemoryDC (for displaying the preview image on-screen), a wxPrinterDC (for
displaying the preview image on-screen), a #wxPrinterDC printing under MSW and Mac), or a wxPostScriptDC (for printing under GTK or
(for printing under MSW and Mac), or a #wxPostScriptDC generating PostScript output).
(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 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.
Class wxPrinter encapsulates the platform-dependent print function with a common If your window classes have a Draw(wxDC *dc) routine to do screen rendering,
interface. In most cases, you will not need to derive a class from wxPrinter; your wxPrintout subclass will typically call those routines to create portions
simply create a wxPrinter object in your Print function as in the example above. 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.
@section topic11 #wxPrintPreview 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
Class wxPrintPreview manages the print preview process. Among other things, it FitThisSizeToXXX(), MapScreenSizeToXXX(), and GetLogicalXXXRect, which can be
constructs the wxDCs that get passed to your wxPrintout subclass for printing used to set the user scale and origin of the wxPrintout's DC so that your class
and manages the display of multiple pages, a zoomable preview image, and so can easily map your image to the printout withough getting into the details of
forth. In most cases you will use this class as-is, but you can create your own screen and printer PPI and scaling. See the printing sample for examples of how
subclass, for example, to change the layout or contents of the preview window. these routines are used.
@section topic12 #wxPrinterDC @section overview_printing_printer wxPrinter
Class wxPrinterDC is the wxDC that represents the actual printed page under MSW Class wxPrinter encapsulates the platform-dependent print function with a common
and Mac. During printing, an object of this class will be passed to your derived interface. In most cases, you will not need to derive a class from wxPrinter;
wxPrintout object to draw upon. The size of the wxPrinterDC will depend on the simply create a wxPrinter object in your Print function as in the example above.
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).
*/
@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).
*/

878
docs/doxygen/overviews/python.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: python // Name: python.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,460 +8,464 @@
/*! /*!
@page python_overview wxPython overview @page overview_python wxPython Overview
This topic was written by Robin Dunn, author of the wxPython wrapper. This topic was written by Robin Dunn, author of the wxPython wrapper.
@ref pwhat_overview
@ref pwhy_overview @li @ref overview_python_what
@ref pother_overview @li @ref overview_python_why
@ref pusing_overview @li @ref overview_python_othergui
@ref pclasses_overview @li @ref overview_python_using
@ref phelp_overview @li @ref overview_python_classes
@li @ref overview_python_help
@section wxpwhat What is wxPython? <hr>
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 @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
@code There are other GUI solutions out there for Python.
001: ## import all of the wxPython GUI package
002: from wxPython.wx import * @subsection overview_python_othergui_tkinter Tkinter
003:
004: ## Create a new frame class, derived from the wxPython Frame. Tkinter is the de facto standard GUI for Python. It is available on nearly
005: class MyFrame(wxFrame): every platform that Python and Tcl/TK are. Why Tcl/Tk? Well because Tkinter is
006: just a wrapper around Tcl's GUI toolkit, Tk. This has it's upsides and it's
007: def __init__(self, parent, id, title): downsides...
008: # First, call the base class' __init__ method to create the frame
009: wxFrame.__init__(self, parent, id, title, The upside is that Tk is a pretty versatile toolkit. It can be made to do a lot
010: wxPoint(100, 100), wxSize(160, 100)) of things in a lot of different environments. It is fairly easy to create new
011: widgets and use them interchangeably in your programs.
012: # Associate some events with methods of this class
013: EVT_SIZE(self, self.OnSize) The downside is Tcl. When using Tkinter you actually have two separate language
014: EVT_MOVE(self, self.OnMove) interpreters running, the Python interpreter and the Tcl interpreter for the
015: GUI. Since the guts of Tcl is mostly about string processing, it is fairly slow
016: # Add a panel and some controls to display the size and position as well. (Not too bad on a fast Pentium II, but you really notice the
017: panel = wxPanel(self, -1) difference on slower machines.)
018: wxStaticText(panel, -1, "Size:",
019: wxDLG_PNT(panel, wxPoint(4, 4)), wxDefaultSize) It wasn't until the latest version of Tcl/Tk that native Look and Feel was
020: wxStaticText(panel, -1, "Pos:", possible on non-Motif platforms. This is because Tk usually implements its own
021: wxDLG_PNT(panel, wxPoint(4, 14)), wxDefaultSize) widgets (controls) even when there are native controls available.
022: self.sizeCtrl = wxTextCtrl(panel, -1, "",
023: wxDLG_PNT(panel, wxPoint(24, 4)), Tkinter is a pretty low-level toolkit. You have to do a lot of work (verbose
024: wxDLG_SZE(panel, wxSize(36, -1)), program code) to do things that would be much simpler with a higher level of
025: wxTE_READONLY) abstraction.
026: self.posCtrl = wxTextCtrl(panel, -1, "",
027: wxDLG_PNT(panel, wxPoint(24, 14)), @subsection overview_python_othergui_pythonwin PythonWin
028: wxDLG_SZE(panel, wxSize(36, -1)),
029: wxTE_READONLY) PythonWin is an add-on package for Python for the Win32 platform. It includes
030: wrappers for MFC as well as much of the Win32 API. Because of its foundation,
031: it is very familiar for programmers who have experience with MFC and the Win32
032: # This method is called automatically when the CLOSE event is API. It is obviously not compatible with other platforms and toolkits.
033: # sent to this window PythonWin is organized as separate packages and modules so you can use the
034: def OnCloseWindow(self, event): pieces you need without having to use the GUI portions.
035: # tell the window to kill itself
036: self.Destroy() @subsection overview_python_othergui_others Others
037:
038: # This method is called by the system when the window is resized, There are quite a few other GUI modules available for Python, some in active
039: # because of the association above. use, some that haven't been updated for ages. Most are simple wrappers around
040: def OnSize(self, event): some C or C++ toolkit or another, and most are not cross-platform compatible.
041: size = event.GetSize() See http://pypi.python.org/pypi?:action=browse&show=all&c=433 for a listing of
042: self.sizeCtrl.SetValue("%s, %s" % (size.width, size.height)) a few of them.
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
@section overview_python_using Using wxPython
@b Things to notice 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.
At line 2 the wxPython classes, constants, and etc. are imported @section overview_python_classes Classes Implemented in wxPython
into the current module's namespace. If you prefer to reduce
namespace pollution you can use "@c from wxPython import wx" and The following classes are supported in wxPython. Most provide nearly full
then access all the wxPython identifiers through the wx module, for implementations of the public interfaces specified in the C++ documentation,
example, "@c wx.wxFrame". others are less so. They will all be brought as close as possible to the C++
At line 13 the frame's sizing and moving events are connected to spec over time.
methods of the class. These helper functions are intended to be like
the event table macros that wxWidgets employs. But since static event @li wxAcceleratorEntry
tables are impossible with wxPython, we use helpers that are named the @li wxAcceleratorTable
same to dynamically build the table. The only real difference is @li wxActivateEvent
that the first argument to the event helpers is always the window that @li wxBitmap
the event table entry should be added to. @li wxBitmapButton
Notice the use of @c wxDLG_PNT and @c wxDLG_SZE in lines 19 @li wxBitmapDataObject
- 29 to convert from dialog units to pixels. These helpers are unique @li wxBMPHandler
to wxPython since Python can't do method overloading like C++. @li wxBoxSizer
There is an @c OnCloseWindow method at line 34 but no call to @li wxBrush
EVT_CLOSE to attach the event to the method. Does it really get @li wxBusyInfo
called? The answer is, yes it does. This is because many of the @li wxBusyCursor
standard events are attached to windows that have the associated @li wxButton
standard method names. I have tried to follow the lead of the @li wxCalculateLayoutEvent
C++ classes in this area to determine what is standard but since @li wxCalendarCtrl
that changes from time to time I can make no guarantees, nor will it @li wxCaret
be fully documented. When in doubt, use an EVT_*** function. @li wxCheckBox
At lines 17 to 21 notice that there are no saved references to @li wxCheckListBox
the panel or the static text items that are created. Those of you @li wxChoice
who know Python might be wondering what happens when Python deletes @li wxClientDC
these objects when they go out of scope. Do they disappear from the GUI? They @li wxClipboard
don't. Remember that in wxPython the Python objects are just shadows of the @li wxCloseEvent
corresponding C++ objects. Once the C++ windows and controls are @li wxColourData
attached to their parents, the parents manage them and delete them @li wxColourDialog
when necessary. For this reason, most wxPython objects do not need to @li wxColour
have a __del__ method that explicitly causes the C++ object to be @li wxComboBox
deleted. If you ever have the need to forcibly delete a window, use @li wxCommandEvent
the Destroy() method as shown on line 36. @li wxConfig
Just like wxWidgets in C++, wxPython apps need to create a class @li wxControl
derived from @c wxApp (line 56) that implements a method named @li wxCursor
@c OnInit, (line 59.) This method should create the application's @li wxCustomDataObject
main window (line 62) and use @c wxApp.SetTopWindow() (line 66) to @li wxDataFormat
inform wxWidgets about it. @li wxDataObject
And finally, at line 72 an instance of the application class is @li wxDataObjectComposite
created. At this point wxPython finishes initializing itself, and calls @li wxDataObjectSimple
the @c OnInit method to get things started. (The zero parameter here is @li wxDateTime
a flag for functionality that isn't quite implemented yet. Just @li wxDateSpan
ignore it for now.) The call to @c MainLoop at line 73 starts the event @li wxDC
loop which continues until the application terminates or all the top @li wxDialog
level windows are closed. @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
@section wxpclasses wxWidgets classes implemented in wxPython 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
The following classes are supported in wxPython. Most provide nearly Or you can send mail directly to the list using this address:
full implementations of the public interfaces specified in the C++ wxpython-users@lists.wxwidgets.org
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
*/
*/

2
docs/doxygen/overviews/runtimeclass.h
View File

@@ -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 CLASSINFO(wxFrame). You can get the wxClassInfo for an object using
wxObject::GetClassInfo. wxObject::GetClassInfo.
@seeaslso @seealso
@li wxObject @li wxObject
@li wxCreateDynamicObject @li wxCreateDynamicObject

2
docs/doxygen/overviews/string.h
View File

@@ -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 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 functions, there are also a few global string functions which try to correct
these problems: wxIsEmpty() verifies whether the string is empty (returning 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 0 for them and wxStricmp() is just a platform-independent version of
case-insensitive string comparison function known either as @c stricmp() or case-insensitive string comparison function known either as @c stricmp() or
@c strcasecmp() on different platforms. @c strcasecmp() on different platforms.

79
docs/doxygen/overviews/thread.h
View File

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

115
docs/doxygen/overviews/tips.h
View File

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

331
docs/doxygen/overviews/toolbar.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: toolbar // Name: toolbar.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,292 +8,77 @@
/*! /*!
@page overview_toolbar Toolbar overview @page overview_toolbar Toolbar Overview
Classes: #wxToolBar Classes: wxToolBar
The toolbar family of classes allows an application to use toolbars The toolbar family of classes allows an application to use toolbars in a
in a variety of configurations and styles. variety of configurations and styles.
The toolbar is a popular user interface component and contains a set of bitmap 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 buttons or toggles. A toolbar gives faster access to an application's
menus, which have to be popped up and selected rather laboriously. facilities than menus, which have to be popped up and selected rather
laboriously.
Instead of supplying one toolbar class with a number Instead of supplying one toolbar class with a number of different
of different implementations depending on platform, wxWidgets separates implementations depending on platform, wxWidgets separates out the classes.
out the classes. This is because there are a number of different toolbar This is because there are a number of different toolbar styles that you may
styles that you may wish to use simultaneously, and also, future wish to use simultaneously, and also, future toolbar implementations will
toolbar implementations will emerge which emerge which cannot all be shoe-horned into the one class.
cannot all be shoe-horned into the one class.
For each platform, the symbol @b wxToolBar is defined to be one of the For each platform, the symbol wxToolBar is defined to be one of the specific
specific toolbar classes. toolbar classes.
The following is a summary of the toolbar classes and their differences. The following is a summary of the toolbar classes and their differences:
- @b wxToolBarBase. This is a base class with pure virtual functions, @li wxToolBarBase: This is a base class with pure virtual functions, and should
and should not be used directly. not be used directly.
- @b wxToolBarSimple. A simple toolbar class written entirely with generic wxWidgets @li wxToolBarSimple: A simple toolbar class written entirely with generic
functionality. A simple 3D effect for buttons is possible, but it is not consistent wxWidgets functionality. A simple 3D effect for buttons is possible, but it
with the Windows look and feel. This toolbar can scroll, and you can have arbitrary is not consistent with the Windows look and feel. This toolbar can scroll,
numbers of rows and columns. and you can have arbitrary numbers of rows and columns.
- @b wxToolBarMSW. This class implements an old-style Windows toolbar, only on @li wxToolBarMSW: This class implements an old-style Windows toolbar, only on
Windows. There are small, three-dimensional buttons, which do not (currently) reflect Windows. There are small, three-dimensional buttons, which do not
the current Windows colour settings: the buttons are grey. This is the default wxToolBar (currently) reflect the current Windows colour settings: the buttons are
on 16-bit windows. grey. This is the default wxToolBar on 16-bit windows.
- @b wxToolBar95. Uses the native Windows 95 toolbar class. It dynamically adjusts its @li wxToolBar95: Uses the native Windows 95 toolbar class. It dynamically
background and button colours according to user colour settings. adjusts it's background and button colours according to user colour
CreateTools must be called after the tools have been added. settings. CreateTools must be called after the tools have been added. No
No absolute positioning is supported but you can specify the number absolute positioning is supported but you can specify the number of rows,
of rows, and add tool separators with @b AddSeparator. and add tool separators with @c AddSeparator. Tooltips are supported.
Tooltips are supported. @b OnRightClick is not supported. This is the default wxToolBar @c OnRightClick is not supported. This is the default wxToolBar on Windows
on Windows 95, Windows NT 4 and above. With the style wxTB_FLAT, the flat toolbar 95, Windows NT 4 and above. With the style wxTB_FLAT, the flat toolbar look
look is used, with a border that is highlighted when the cursor moves over the buttons. 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 A toolbar might appear as a single row of images under the menubar, or it might
the menubar, or it might be in a separate frame layout in several rows be in a separate frame layout in several rows and columns. The class handles
and columns. The class handles the layout of the images, unless explicit the layout of the images, unless explicit positioning is requested.
positioning is requested.
A tool is a bitmap which can either be a button (there is no 'state', A tool is a bitmap which can either be a button (there is no 'state', it just
it just generates an event when clicked) or it can be a toggle. If a generates an event when clicked) or it can be a toggle. If a toggle, a second
toggle, a second bitmap can be provided to depict the 'on' state; if bitmap can be provided to depict the 'on' state; if the second bitmap is
the second bitmap is omitted, either the inverse of the first bitmap omitted, either the inverse of the first bitmap will be used (for monochrome
will be used (for monochrome displays) or a thick border is drawn displays) or a thick border is drawn around the bitmap (for colour displays
around the bitmap (for colour displays where inverting will not have where inverting will not have the desired result).
the desired result).
The Windows-specific toolbar classes expect 16-colour bitmaps that are 16 pixels wide and 15 pixels The Windows-specific toolbar classes expect 16-colour bitmaps that are 16
high. If you want to use a different size, call @b SetToolBitmapSize pixels wide and 15 pixels high. If you want to use a different size, call
as the demo shows, before adding tools to the button bar. Don't supply more than @c SetToolBitmapSize as the demo shows, before adding tools to the button bar.
one bitmap for each tool, because the toolbar generates all three images (normal, Don't supply more than one bitmap for each tool, because the toolbar generates
depressed and checked) from the single bitmap you give it. all three images (normal, depressed, and checked) from the single bitmap you
give it.
@ref overview_usingtoolbarlibrary
@section overview_usingtoolbarlibrary Using the toolbar library @section overview_toolbar_library Using the Toolbar Library
Include @c "wx/toolbar.h", or if using a class directly, one of: Include @c "wx/toolbar.h", or if using a class directly, one of:
- @c "wx/msw/tbarmsw.h for wxToolBarMSW - @c "wx/msw/tbarmsw.h" for wxToolBarMSW
- @c "wx/msw/tbar95.h for wxToolBar95 - @c "wx/msw/tbar95.h" for wxToolBar95
- @c "wx/tbarsmpl.h for wxToolBarSimple - @c "wx/tbarsmpl.h" for wxToolBarSimple
An example of using a toolbar is given in the "toolbar" sample.
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
*/

134
docs/doxygen/overviews/treectrl.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: treectrl // Name: treectrl.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,85 +8,75 @@
/*! /*!
@page overview_treectrl wxTreeCtrl overview @page overview_treectrl wxTreeCtrl Overview
Classes: #wxTreeCtrl, #wxImageList 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.
The items text and image may be retrieved and changed with The tree control displays its items in a tree like structure. Each item has
#GetItemText/#SetItemText its own (optional) icon and a label. An item may be either collapsed (meaning
and that its children are not visible) or expanded (meaning that its children are
#GetItemImage/#SetItemImage. shown). Each item in the tree is identified by its @c itemId which is of opaque
In fact, an item may even have two images associated with it: the normal one data type wxTreeItemId. You can test whether an item is valid by calling
and another one for selected state which is set/retrieved with wxTreeItemId::IsOk.
#SetItemSelectedImage/#GetItemSelectedImage
functions, but this functionality might be unavailable on some platforms.
Tree items have several attributes: an item may be selected or not, visible or The items text and image may be retrieved and changed with (Get|Set)ItemText
not, bold or not. It may also be expanded or collapsed. All these attributes and (Get|Set)ItemImage. In fact, an item may even have two images associated
may be retrieved with the corresponding functions: with it: the normal one and another one for selected state which is
#IsSelected, set/retrieved with (Get|Set)ItemSelectedImage functions, but this functionality
#IsVisible, #IsBold might be unavailable on some platforms.
and #IsExpanded. Only one item at a time may be
selected, selecting another one (with
#SelectItem) automatically unselects the
previously selected one.
In addition to its icon and label, a user-specific data structure may be associated Tree items have several attributes: an item may be selected or not, visible or
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 not, bold or not. It may also be expanded or collapsed. All these attributes
data will be freed by the control itself when the associated item is deleted may be retrieved with the corresponding functions: IsSelected, IsVisible,
(all items are deleted when the control is destroyed), so you shouldn't delete IsBold and IsExpanded. Only one item at a time may be selected, selecting
it yourself (if you do it, you should call another one (with SelectItem) automatically unselects the previously selected
#SetItemData(@NULL) to prevent the tree from one.
deleting the pointer second time). The associated data may be retrieved with
#GetItemData() function.
Working with trees is relatively straightforward if all the items are added to In addition to its icon and label, a user-specific data structure may be
the tree at the moment of its creation. However, for large trees it may be associated with all tree items. If you wish to do it, you should derive a class
very inefficient. To improve the performance you may want to delay adding the from wxTreeItemData which is a very simple class having only one function
items to the tree until the branch containing the items is expanded: so, in the GetId() which returns the id of the item this data is associated with. This
beginning, only the root item is created (with data will be freed by the control itself when the associated item is deleted
#AddRoot). Other items are added when (all items are deleted when the control is destroyed), so you shouldn't delete
EVT_TREE_ITEM_EXPANDING event is received: then all items lying immediately it yourself (if you do it, you should call SetItemData(@NULL) to prevent the
under the item being expanded should be added, but, of course, only when this tree from deleting the pointer second time). The associated data may be
event is received for the first time for this item - otherwise, the items would retrieved with GetItemData() function.
be added twice if the user expands/collapses/re-expands the branch.
The tree control provides functions for enumerating its items. There are 3 Working with trees is relatively straightforward if all the items are added to
groups of enumeration functions: for the children of a given item, for the the tree at the moment of its creation. However, for large trees it may be
sibling of the given item and for the visible items (those which are currently very inefficient. To improve the performance you may want to delay adding the
shown to the user: an item may be invisible either because its branch is items to the tree until the branch containing the items is expanded: so, in the
collapsed or because it is scrolled out of view). Child enumeration functions beginning, only the root item is created (with AddRoot). Other items are added
require the caller to give them a @e cookie parameter: it is a number which when EVT_TREE_ITEM_EXPANDING event is received: then all items lying
is opaque to the caller but is used by the tree control itself to allow immediately under the item being expanded should be added, but, of course, only
multiple enumerations to run simultaneously (this is explicitly allowed). The when this event is received for the first time for this item - otherwise, the
only thing to remember is that the @e cookie passed to items would be added twice if the user expands/collapses/re-expands the branch.
#GetFirstChild and to
#GetNextChild should be the same variable (and
that nothing should be done with it by the user code).
Among other features of the tree control are: item sorting with The tree control provides functions for enumerating its items. There are 3
#SortChildren which uses the user-defined comparison groups of enumeration functions: for the children of a given item, for the
function #OnCompareItems (by default the sibling of the given item and for the visible items (those which are currently
comparison is the alphabetic comparison of tree labels), hit testing shown to the user: an item may be invisible either because its branch is
(determining to which portion of the control the given point belongs, useful collapsed or because it is scrolled out of view). Child enumeration functions
for implementing drag-and-drop in the tree) with require the caller to give them a @e cookie parameter: it is a number which
#HitTest and editing of the tree item labels in is opaque to the caller but is used by the tree control itself to allow
place (see #EditLabel). 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 Among other features of the tree control are: item sorting with SortChildren
may be used to change the current selection. HOME and END are used to go to which uses the user-defined comparison function OnCompareItems (by default the
the first/last sibling of the current item. '+', '-' and '*' expand, collapse comparison is the alphabetic comparison of tree labels), hit testing
and toggle the current branch. Note, however, that DEL and INS keys do (determining to which portion of the control the given point belongs, useful
nothing by default, but it is common to associate them with deleting an item from for implementing drag-and-drop in the tree) with HitTest and editing of the
a tree and inserting a new one into it. 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.
*/

336
docs/doxygen/overviews/unicode.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: unicode // Name: unicode.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,204 +8,200 @@
/*! /*!
@page overview_unicode Unicode support in wxWidgets @page overview_unicode Unicode Support in wxWidgets
This section briefly describes the state of the 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 Read it if you want to know more about how to write programs able to work with
characters from languages other than English. characters from languages other than English.
@li @ref overview_whatisunicode @li @ref overview_unicode_what
@li @ref overview_unicodeandansi @li @ref overview_unicode_ansi
@li @ref overview_unicodeinsidewxw @li @ref overview_unicode_supportin
@li @ref overview_unicodeoutsidewxw @li @ref overview_unicode_supportout
@li @ref overview_unicodesettings @li @ref overview_unicode_settings
@li @ref overview_topic8 @li @ref overview_unicode_traps
@section overview_whatisunicode What is Unicode? <hr>
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) @section overview_unicode_what What is Unicode?
- Literal strings (i.e. @c "Hello, world!" or @c '*')
- String functions (@c strlen(), @c strcpy(), ...) wxWidgets has support for compiling in Unicode mode on the platforms which
- Special preprocessor tokens (@c __FILE__, @c __DATE__ support it. Unicode is a standard for character encoding which addresses the
and @c __TIME__) 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.
Let's look at them in order. First of all, each character in an Unicode @section overview_unicode_ansi Unicode and ANSI Modes
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 As not all platforms supported by wxWidgets support Unicode (fully) yet, in
characters (@c wchar_t type) which typically take 2 or 4 bytes instead many cases it is unwise to write a program which can only work in Unicode
of @c char which only takes one. This is achieved by using the standard C environment. A better solution is to write programs in such way that they may
(and C++) way: just put the letter @c 'L' after any string constant and it be compiled either in ANSI (traditional) mode or in the Unicode one.
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 This can be achieved quite simply by using the means provided by wxWidgets.
strings, so another set of functions exists which do the same thing but accept Basically, there are only a few things to watch out for:
@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 - Character type (@c char or @c wchar_t)
strings but it is more likely that Unicode strings are wanted in the Unicode - Literal strings (i.e. @c "Hello, world!" or @c '*')
build. wxWidgets provides the macros @c __TFILE__, @c __TDATE__ - String functions (@c strlen(), @c strcpy(), ...)
and @c __TTIME__ which behave exactly as the standard ones except that - Special preprocessor tokens (@c __FILE__, @c __DATE__ and @c __TIME__)
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 Let's look at them in order. First of all, each character in an Unicode program
in both ANSI and Unicode modes could look like: 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.
@code Also, the string and character constants should be encoded using wide
#ifdef __UNICODE__ characters (@c wchar_t type) which typically take 2 or 4 bytes instead of
wchar_t wch = L'*'; @c char which only takes one. This is achieved by using the standard C (and
const wchar_t *ws = L"Hello, world!"; C++) way: just put the letter @c 'L' after any string constant and it becomes a
int len = wcslen(ws); @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.
wprintf(L"Compiled at %s\n", __TDATE__); Of course, the usual standard C functions don't work with @c wchar_t strings,
#else // ANSI so another set of functions exists which do the same thing but accept
char ch = '*'; @c wchar_t* instead of @c char*. For example, a function to get the length of a
const char *s = "Hello, world!"; wide-character string is called @c wcslen() (compare with @c strlen() - you see
int len = strlen(s); that the only difference is that the "str" prefix standing for "string" has
been replaced with "wcs" standing for "wide-character string").
printf("Compiled at %s\n", __DATE__); And finally, the standard preprocessor tokens enumerated above expand to ANSI
#endif // Unicode/ANSI strings but it is more likely that Unicode strings are wanted in the Unicode
@endcode 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.
Of course, it would be nearly impossibly to write such programs if it had to To summarize, here is a brief example of how a program which can be compiled
be done this way (try to imagine the number of @c #ifdef UNICODE an average in both ANSI and Unicode modes could look like:
program would have had!). Luckily, there is another way - see the next
section.
@section overview_unicodeinsidewxw Unicode support in wxWidgets @code
#ifdef __UNICODE__
wchar_t wch = L'*';
const wchar_t *ws = L"Hello, world!";
int len = wcslen(ws);
In wxWidgets, the code fragment from above should be written instead: wprintf(L"Compiled at %s\n", __TDATE__);
#else // ANSI
char ch = '*';
const char *s = "Hello, world!";
int len = strlen(s);
@code printf("Compiled at %s\n", __DATE__);
wxChar ch = wxT('*'); #endif // Unicode/ANSI
wxString s = wxT("Hello, world!"); @endcode
int len = s.Len();
@endcode
What happens here? First of all, you see that there are no more @c #ifdefs Of course, it would be nearly impossibly to write such programs if it had to
at all. Instead, we define some types and macros which behave differently in be done this way (try to imagine the number of @ifdef UNICODE an average
the Unicode and ANSI builds and allow us to avoid using conditional program would have had!). Luckily, there is another way - see the next section.
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 @section overview_unicode_supportin Unicode Support in wxWidgets
const char* ascii_str = "Some text";
wxString str(ascii_str, wxConvUTF8);
@endcode
This code also compiles fine under a non-Unicode build of wxWidgets, In wxWidgets, the code fragment from above should be written instead:
but in that case the converter is ignored.
For more information about converters and Unicode see @code
the @ref overview_mbconvclasses. wxChar ch = wxT('*');
wxString s = wxT("Hello, world!");
int len = s.Len();
@endcode
@section overview_unicodesettings Unicode-related compilation settings 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.
You should define @c wxUSE_UNICODE to 1 to compile your program in We have a @c wxChar type which maps either on @c char or @c wchar_t depending
Unicode mode. This currently works for wxMSW, wxGTK, wxMac and wxX11. If you on the mode in which program is being compiled. There is no need for a separate
compile your program in ANSI mode you can still define @c wxUSE_WCHAR_T type for strings though, because the standard wxString supports Unicode, i.e.
to get some limited support for @c wchar_t type. it stores either ANSI or Unicode strings depending on the compile mode.
This will allow your program to perform conversions between Unicode strings and Finally, there is a special wxT() macro which should enclose all literal
ANSI ones (using @ref overview_mbconvclasses) strings in the program. As it is easy to see comparing the last fragment with
and construct wxString objects from Unicode strings (presumably read the one above, this macro expands to nothing in the (usual) ANSI mode and
from some external file or elsewhere). prefixes @c 'L' to its argument in the Unicode mode.
@section overview_topic8 Traps for the unwary 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!
- Casting c_str() to void* is now char*, not wxChar* Just let us state once again the rules:
- Passing c_str(), mb_str() or wc_str() to variadic functions
doesn't work
*/ @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.
*/

71
docs/doxygen/overviews/unixprinting.h
View File

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