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

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

@@ -1,5 +1,5 @@
/////////////////////////////////////////////////////////////////////////////
// Name: printing
// Name: printing.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
@@ -8,87 +8,87 @@
/*!
@page overview_printing Printing overview
@page overview_printing Printing Overview
Classes:
@li wxPrintout
@li wxPrinter
@li wxPrintPreview
@li wxPrinterDC
@li wxPostScriptDC
@li wxPrintDialog
@li wxPrintData
@li wxPrintDialogData
@li wxPageSetupDialog
@li wxPageSetupDialogData
The printing framework relies on the application to provide classes whose
member functions can respond to particular requests, such as 'print this page'
or 'does this page exist in the document?'. This method allows wxWidgets to
take over the housekeeping duties of turning preview pages, calling the print
dialog box, creating the printer device context, and so on: the application can
concentrate on the rendering of the information onto a device context.
In most cases, the only class you will need to derive from is wxPrintout; all
others will be used as-is.
Classes: #wxPrintout,
#wxPrinter,
#wxPrintPreview,
#wxPrinterDC,
#wxPostScriptDC,
#wxPrintDialog,
#wxPrintData,
#wxPrintDialogData,
#wxPageSetupDialog,
#wxPageSetupDialogData
The printing framework relies on the application to provide classes whose member
functions can respond to particular requests, such as 'print this page' or 'does
this page exist in the document?'. This method allows wxWidgets to take over the
housekeeping duties of turning preview pages, calling the print dialog box,
creating the printer device context, and so on: the application can concentrate
on the rendering of the information onto a device context.
In most cases, the only class you will need to derive from is
#wxPrintout; all others will be used as-is.
A brief description of each class's role and how they work together follows.
For the special case of printing under Unix, where various different
printing backends have to be offered, please have a look at the
@ref unixprinting_overview.
@ref topic9_overview
@ref topic10_overview
@ref topic11_overview
@ref topic12_overview
@ref topic13_overview
@ref topic14_overview
@ref topic15_overview
@ref topic16_overview
@ref topic17_overview
@ref topic18_overview
For the special case of printing under Unix, where various different printing
backends have to be offered, please have a look at @ref overview_unixprinting.
@section topic9 #wxPrintout
@section overview_printing_printout wxPrintout
A document's printing ability is represented in an application by a derived
wxPrintout class. This class prints a page on request, and can be passed to the
Print function of a wxPrinter object to actually print the document, or can be
passed to a wxPrintPreview object to initiate previewing. The following code
(from the printing sample) shows how easy it is to initiate printing, previewing
and the print setup dialog, once the wxPrintout functionality has been defined.
Notice the use of MyPrintout for both printing and previewing. All the preview
user interface functionality is taken care of by wxWidgets. For more details on how
MyPrintout is defined, please look at the printout sample code.
(from the printing sample) shows how easy it is to initiate printing,
previewing and the print setup dialog, once the wxPrintout functionality has
been defined. Notice the use of MyPrintout for both printing and previewing.
All the preview user interface functionality is taken care of by wxWidgets. For
more details on how MyPrintout is defined, please look at the printout sample
code.
@code
case WXPRINT_PRINT:
{
wxPrinter printer;
MyPrintout printout("My printout");
printer.Print(this, , @true);
printer.Print(this, &printout, true);
break;
}
case WXPRINT_PREVIEW:
{
// Pass two printout objects: for preview, and possible printing.
wxPrintPreview *preview = new wxPrintPreview(new MyPrintout, new MyPrintout);
wxPreviewFrame *frame = new wxPreviewFrame(preview, this, "Demo Print Preview", wxPoint(100, 100), wxSize(600, 650));
frame-Centre(wxBOTH);
frame-Initialize();
frame-Show(@true);
wxPreviewFrame *frame = new wxPreviewFrame(preview, this,
"Demo Print Preview",
wxPoint(100, 100),
wxSize(600, 650));
frame->Centre(wxBOTH);
frame->Initialize();
frame->Show(true);
break;
}
@endcode
Class #wxPrintout assembles the printed page and (using
your subclass's overrides) writes requested pages to a #wxDC that
is passed to it. This wxDC could be a #wxMemoryDC (for
displaying the preview image on-screen), a #wxPrinterDC
(for printing under MSW and Mac), or a #wxPostScriptDC
(for printing under GTK or generating PostScript output).
The @ref docview_overview creates a default
wxPrintout assembles the printed page and (using your subclass's overrides)
writes requested pages to a wxDC that is passed to it. This wxDC could be a
wxMemoryDC (for displaying the preview image on-screen), a wxPrinterDC (for
printing under MSW and Mac), or a wxPostScriptDC (for printing under GTK or
generating PostScript output).
The @ref overview_docview "document/view framework" creates a default
wxPrintout object for every view, calling wxView::OnDraw to achieve a
prepackaged print/preview facility.
If your window classes have a Draw(wxDC *dc) routine to do screen rendering,
your wxPrintout subclass will typically call those routines to create portions
of the image on your printout. Your wxPrintout subclass can also make its own
calls to its wxDC to draw headers, footers, page numbers, etc.
The scaling of the drawn image typically differs from the screen to the preview
and printed images. This class provides a set of routines named
FitThisSizeToXXX(), MapScreenSizeToXXX(), and GetLogicalXXXRect, which can be
@@ -97,13 +97,15 @@
screen and printer PPI and scaling. See the printing sample for examples of how
these routines are used.
@section topic10 #wxPrinter
@section overview_printing_printer wxPrinter
Class wxPrinter encapsulates the platform-dependent print function with a common
interface. In most cases, you will not need to derive a class from wxPrinter;
simply create a wxPrinter object in your Print function as in the example above.
@section topic11 #wxPrintPreview
@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
@@ -112,58 +114,63 @@
subclass, for example, to change the layout or contents of the preview window.
@section topic12 #wxPrinterDC
@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 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
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 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
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 topic13 #wxPostScriptDC
@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.
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.
@section topic14 #wxPrintDialog
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.
wxPrintDialogData to the wxPrintDialog at construction, which is used to
populate the dialog.
@section topic15 #wxPrintData
@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.
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
@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.
@@ -171,34 +178,37 @@
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.
@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.
wxPageSetupDialogData object in its constructor) to provide this capability;
see the printing sample for an example.
@section topic18 #wxPageSetupDialogData
@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.
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).
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).
*/

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

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

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

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

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

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

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

@@ -1,5 +1,5 @@
/////////////////////////////////////////////////////////////////////////////
// Name: toolbar
// Name: toolbar.h
// Purpose: topic overview
// Author: wxWidgets team
// 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
in a variety of configurations and styles.
The toolbar family of classes allows an application to use toolbars in a
variety of configurations and styles.
The toolbar is a popular user interface component and contains a set of bitmap
buttons or toggles. A toolbar gives faster access to an application's facilities than
menus, which have to be popped up and selected rather laboriously.
buttons or toggles. A toolbar gives faster access to an application's
facilities than menus, which have to be popped up and selected rather
laboriously.
Instead of supplying one toolbar class with a number
of different implementations depending on platform, wxWidgets separates
out the classes. This is because there are a number of different toolbar
styles that you may wish to use simultaneously, and also, future
toolbar implementations will emerge which
cannot all be shoe-horned into the one class.
Instead of supplying one toolbar class with a number of different
implementations depending on platform, wxWidgets separates out the classes.
This is because there are a number of different toolbar styles that you may
wish to use simultaneously, and also, future toolbar implementations will
emerge which cannot all be shoe-horned into the one class.
For each platform, the symbol @b wxToolBar is defined to be one of the
specific toolbar classes.
For each platform, the symbol wxToolBar is defined to be one of the specific
toolbar classes.
The following is a summary of the toolbar classes and their differences.
The following is a summary of the toolbar classes and their differences:
- @b wxToolBarBase. This is a base class with pure virtual functions,
and should not be used directly.
- @b wxToolBarSimple. A simple toolbar class written entirely with generic wxWidgets
functionality. A simple 3D effect for buttons is possible, but it is not consistent
with the Windows look and feel. This toolbar can scroll, and you can have arbitrary
numbers of rows and columns.
- @b wxToolBarMSW. This class implements an old-style Windows toolbar, only on
Windows. There are small, three-dimensional buttons, which do not (currently) reflect
the current Windows colour settings: the buttons are grey. This is the default wxToolBar
on 16-bit windows.
- @b wxToolBar95. Uses the native Windows 95 toolbar class. It dynamically adjusts its
background and button colours according to user colour settings.
CreateTools must be called after the tools have been added.
No absolute positioning is supported but you can specify the number
of rows, and add tool separators with @b AddSeparator.
Tooltips are supported. @b OnRightClick is not supported. This is the default wxToolBar
on Windows 95, Windows NT 4 and above. With the style wxTB_FLAT, the flat toolbar
look is used, with a border that is highlighted when the cursor moves over the buttons.
@li wxToolBarBase: This is a base class with pure virtual functions, and should
not be used directly.
@li wxToolBarSimple: A simple toolbar class written entirely with generic
wxWidgets functionality. A simple 3D effect for buttons is possible, but it
is not consistent with the Windows look and feel. This toolbar can scroll,
and you can have arbitrary numbers of rows and columns.
@li wxToolBarMSW: This class implements an old-style Windows toolbar, only on
Windows. There are small, three-dimensional buttons, which do not
(currently) reflect the current Windows colour settings: the buttons are
grey. This is the default wxToolBar on 16-bit windows.
@li wxToolBar95: Uses the native Windows 95 toolbar class. It dynamically
adjusts it's background and button colours according to user colour
settings. CreateTools must be called after the tools have been added. No
absolute positioning is supported but you can specify the number of rows,
and add tool separators with @c AddSeparator. Tooltips are supported.
@c OnRightClick is not supported. This is the default wxToolBar on Windows
95, Windows NT 4 and above. With the style wxTB_FLAT, the flat toolbar look
is used, with a border that is highlighted when the cursor moves over the
buttons.
A toolbar might appear as a single row of images under
the menubar, or it might be in a separate frame layout in several rows
and columns. The class handles the layout of the images, unless explicit
positioning is requested.
A toolbar might appear as a single row of images under the menubar, or it might
be in a separate frame layout in several rows and columns. The class handles
the layout of the images, unless explicit positioning is requested.
A tool is a bitmap which can either be a button (there is no 'state',
it just generates an event when clicked) or it can be a toggle. If a
toggle, a second bitmap can be provided to depict the 'on' state; if
the second bitmap is omitted, either the inverse of the first bitmap
will be used (for monochrome displays) or a thick border is drawn
around the bitmap (for colour displays where inverting will not have
the desired result).
A tool is a bitmap which can either be a button (there is no 'state', it just
generates an event when clicked) or it can be a toggle. If a toggle, a second
bitmap can be provided to depict the 'on' state; if the second bitmap is
omitted, either the inverse of the first bitmap will be used (for monochrome
displays) or a thick border is drawn around the bitmap (for colour displays
where inverting will not have the desired result).
The Windows-specific toolbar classes expect 16-colour bitmaps that are 16 pixels wide and 15 pixels
high. If you want to use a different size, call @b SetToolBitmapSize
as the demo shows, before adding tools to the button bar. Don't supply more than
one bitmap for each tool, because the toolbar generates all three images (normal,
depressed and checked) from the single bitmap you give it.
@ref overview_usingtoolbarlibrary
The Windows-specific toolbar classes expect 16-colour bitmaps that are 16
pixels wide and 15 pixels high. If you want to use a different size, call
@c SetToolBitmapSize as the demo shows, before adding tools to the button bar.
Don't supply more than one bitmap for each tool, because the toolbar generates
all three images (normal, depressed, and checked) from the single bitmap you
give it.
@section overview_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:
- @c "wx/msw/tbarmsw.h for wxToolBarMSW
- @c "wx/msw/tbar95.h for wxToolBar95
- @c "wx/tbarsmpl.h for wxToolBarSimple
- @c "wx/msw/tbarmsw.h" for wxToolBarMSW
- @c "wx/msw/tbar95.h" for wxToolBar95
- @c "wx/tbarsmpl.h" for wxToolBarSimple
Example of toolbar use are given in the sample program "toolbar''. The
source is given below. In fact it is out of date because recommended
practise is to use event handlers (using EVT_MENU or EVT_TOOL) instead of
overriding OnLeftClick.
@code
/////////////////////////////////////////////////////////////////////////////
// Name: test.cpp
// Purpose: wxToolBar sample
// Author: Julian Smart
// Modified by:
// Created: 04/01/98
// RCS-ID: $Id$
// Copyright: (c) Julian Smart
// License: wxWindows license
/////////////////////////////////////////////////////////////////////////////
// For compilers that support precompilation, includes "wx/wx.h".
#include "wx/wxprec.h"
#ifdef __BORLANDC__
#pragma hdrstop
#endif
#ifndef WX_PRECOMP
#include "wx/wx.h"
#endif
#include "wx/toolbar.h"
#include wx/log.h
#include "test.h"
#if defined(__WXGTK__) || defined(__WXMOTIF__)
#include "mondrian.xpm"
#include "bitmaps/new.xpm"
#include "bitmaps/open.xpm"
#include "bitmaps/save.xpm"
#include "bitmaps/copy.xpm"
#include "bitmaps/cut.xpm"
#include "bitmaps/print.xpm"
#include "bitmaps/preview.xpm"
#include "bitmaps/help.xpm"
#endif
IMPLEMENT_APP(MyApp)
// The `main program' equivalent, creating the windows and returning the
// main frame
bool MyApp::OnInit(void)
{
// Create the main frame window
MyFrame* frame = new MyFrame((wxFrame *) @NULL, -1, (const wxString) "wxToolBar Sample",
wxPoint(100, 100), wxSize(450, 300));
// Give it a status line
frame-CreateStatusBar();
// Give it an icon
frame-SetIcon(wxICON(mondrian));
// Make a menubar
wxMenu *fileMenu = new wxMenu;
fileMenu-Append(wxID_EXIT, "E", "Quit toolbar sample" );
wxMenu *helpMenu = new wxMenu;
helpMenu-Append(wxID_HELP, "", "About toolbar sample");
wxMenuBar* menuBar = new wxMenuBar;
menuBar-Append(fileMenu, "");
menuBar-Append(helpMenu, "");
// Associate the menu bar with the frame
frame-SetMenuBar(menuBar);
// Create the toolbar
frame-CreateToolBar(wxBORDER\_NONE|wxHORIZONTAL|wxTB_FLAT, ID_TOOLBAR);
frame-GetToolBar()-SetMargins( 2, 2 );
InitToolbar(frame-GetToolBar());
// Force a resize. This should probably be replaced by a call to a wxFrame
// function that lays out default decorations and the remaining content window.
wxSizeEvent event(wxSize(-1, -1), frame-GetId());
frame-OnSize(event);
frame-Show(@true);
frame-SetStatusText("Hello, wxWidgets");
SetTopWindow(frame);
return @true;
}
bool MyApp::InitToolbar(wxToolBar* toolBar)
{
// Set up toolbar
wxBitmap* toolBarBitmaps[8];
#ifdef __WXMSW__
toolBarBitmaps[0] = new wxBitmap("icon1");
toolBarBitmaps[1] = new wxBitmap("icon2");
toolBarBitmaps[2] = new wxBitmap("icon3");
toolBarBitmaps[3] = new wxBitmap("icon4");
toolBarBitmaps[4] = new wxBitmap("icon5");
toolBarBitmaps[5] = new wxBitmap("icon6");
toolBarBitmaps[6] = new wxBitmap("icon7");
toolBarBitmaps[7] = new wxBitmap("icon8");
#else
toolBarBitmaps[0] = new wxBitmap( new_xpm );
toolBarBitmaps[1] = new wxBitmap( open_xpm );
toolBarBitmaps[2] = new wxBitmap( save_xpm );
toolBarBitmaps[3] = new wxBitmap( copy_xpm );
toolBarBitmaps[4] = new wxBitmap( cut_xpm );
toolBarBitmaps[5] = new wxBitmap( preview_xpm );
toolBarBitmaps[6] = new wxBitmap( print_xpm );
toolBarBitmaps[7] = new wxBitmap( help_xpm );
#endif
#ifdef __WXMSW__
int width = 24;
#else
int width = 16;
#endif
int currentX = 5;
toolBar-AddTool(wxID_NEW, *(toolBarBitmaps[0]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "New file");
currentX += width + 5;
toolBar-AddTool(wxID_OPEN, *(toolBarBitmaps[1]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Open file");
currentX += width + 5;
toolBar-AddTool(wxID_SAVE, *(toolBarBitmaps[2]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Save file");
currentX += width + 5;
toolBar-AddSeparator();
toolBar-AddTool(wxID_COPY, *(toolBarBitmaps[3]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Copy");
currentX += width + 5;
toolBar-AddTool(wxID_CUT, *(toolBarBitmaps[4]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Cut");
currentX += width + 5;
toolBar-AddTool(wxID_PASTE, *(toolBarBitmaps[5]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Paste");
currentX += width + 5;
toolBar-AddSeparator();
toolBar-AddTool(wxID_PRINT, *(toolBarBitmaps[6]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Print");
currentX += width + 5;
toolBar-AddSeparator();
toolBar-AddTool(wxID_HELP, *(toolBarBitmaps[7]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Help");
toolBar-Realize();
// Can delete the bitmaps since they're reference counted
int i;
for (i = 0; i 8; i++)
delete toolBarBitmaps[i];
return @true;
}
// wxID_HELP will be processed for the 'About' menu and the toolbar help button.
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
EVT_MENU(wxID_EXIT, MyFrame::OnQuit)
EVT_MENU(wxID_HELP, MyFrame::OnAbout)
EVT_CLOSE(MyFrame::OnCloseWindow)
EVT_TOOL_RANGE(wxID_OPEN, wxID_PASTE, MyFrame::OnToolLeftClick)
EVT_TOOL_ENTER(wxID_OPEN, MyFrame::OnToolEnter)
END_EVENT_TABLE()
// Define my frame constructor
MyFrame::MyFrame(wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos,
const wxSize& size, long style):
wxFrame(parent, id, title, pos, size, style)
{
m_textWindow = new wxTextCtrl(this, -1, "", wxPoint(0, 0), wxSize(-1, -1), wxTE_MULTILINE);
}
void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
{
Close(@true);
}
void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
{
(void)wxMessageBox("wxWidgets toolbar sample", "About wxToolBar");
}
// Define the behaviour for the frame closing
// - must delete all frames except for the main one.
void MyFrame::OnCloseWindow(wxCloseEvent& WXUNUSED(event))
{
Destroy();
}
void MyFrame::OnToolLeftClick(wxCommandEvent& event)
{
wxString str;
str.Printf("Clicked on tool %d", event.GetId());
SetStatusText(str);
}
void MyFrame::OnToolEnter(wxCommandEvent& event)
{
if (event.GetSelection() -1)
{
wxString str;
str.Printf("This is tool number %d", event.GetSelection());
SetStatusText(str);
}
else
SetStatusText("");
}
@endcode
An example of using a toolbar is given in the "toolbar" sample.
*/

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

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

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

@@ -1,5 +1,5 @@
/////////////////////////////////////////////////////////////////////////////
// Name: unicode
// Name: unicode.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
@@ -8,30 +8,33 @@
/*!
@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.
Read it if you want to know more about how to write programs able to work with
characters from languages other than English.
@li @ref overview_whatisunicode
@li @ref overview_unicodeandansi
@li @ref overview_unicodeinsidewxw
@li @ref overview_unicodeoutsidewxw
@li @ref overview_unicodesettings
@li @ref overview_topic8
@li @ref overview_unicode_what
@li @ref overview_unicode_ansi
@li @ref overview_unicode_supportin
@li @ref overview_unicode_supportout
@li @ref overview_unicode_settings
@li @ref overview_unicode_traps
@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.
@section overview_unicode_what What is Unicode?
wxWidgets has support for compiling in Unicode mode on the platforms which
support it. Unicode is a standard for character encoding which addresses the
shortcomings of the previous, 8 bit standards, by using at least 16 (and
possibly 32) bits for encoding each character. This allows to have at least
65536 characters (what is called the BMP, or basic multilingual plane) and
possible 2^32 of them instead of the usual 256 and is sufficient to encode all
of the world languages at once. More details about Unicode may be found at
<http://www.unicode.org/>.
As this solution is obviously preferable to the previous ones (think of
incompatible encodings for the same language, locale chaos and so on), many
@@ -40,12 +43,13 @@
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.
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
@section overview_unicode_ansi Unicode and ANSI Modes
As not all platforms supported by wxWidgets support Unicode (fully) yet, in
many cases it is unwise to write a program which can only work in Unicode
@@ -55,40 +59,36 @@
This can be achieved quite simply by using the means provided by wxWidgets.
Basically, there are only a few things to watch out for:
- Character type (@c char or @c wchar_t)
- Literal strings (i.e. @c "Hello, world!" or @c '*')
- String functions (@c strlen(), @c strcpy(), ...)
- Special preprocessor tokens (@c __FILE__, @c __DATE__
and @c __TIME__)
- Special preprocessor tokens (@c __FILE__, @c __DATE__ and @c __TIME__)
Let's look at them in order. First of all, each character in an Unicode
program takes 2 bytes instead of usual one, so another type should be used to
store the characters (@c char only holds 1 byte usually). This type is
called @c wchar_t which stands for @e wide-character type.
Let's look at them in order. First of all, each character in an Unicode program
takes 2 bytes instead of usual one, so another type should be used to store the
characters (@c char only holds 1 byte usually). This type is called @c wchar_t
which stands for @e wide-character type.
Also, the string and character constants should be encoded using wide
characters (@c wchar_t type) which typically take 2 or 4 bytes instead
of @c char which only takes one. This is achieved by using the standard C
(and C++) way: just put the letter @c 'L' after any string constant and it
becomes a @e long constant, i.e. a wide character one. To make things a bit
more readable, you are also allowed to prefix the constant with @c 'L'
instead of putting it after it.
characters (@c wchar_t type) which typically take 2 or 4 bytes instead of
@c char which only takes one. This is achieved by using the standard C (and
C++) way: just put the letter @c 'L' after any string constant and it becomes a
@e long constant, i.e. a wide character one. To make things a bit more
readable, you are also allowed to prefix the constant with @c 'L' instead of
putting it after it.
Of course, the usual standard C functions don't work with @c wchar_t
strings, so another set of functions exists which do the same thing but accept
@c wchar_t * instead of @c char *. For example, a function to get the
length of a wide-character string is called @c wcslen() (compare with
@c strlen() - you see that the only difference is that the "str" prefix
standing for "string" has been replaced with "wcs" standing for "wide-character
string").
Of course, the usual standard C functions don't work with @c wchar_t strings,
so another set of functions exists which do the same thing but accept
@c wchar_t* instead of @c char*. For example, a function to get the length of a
wide-character string is called @c wcslen() (compare with @c strlen() - you see
that the only difference is that the "str" prefix standing for "string" has
been replaced with "wcs" standing for "wide-character string").
And finally, the standard preprocessor tokens enumerated above expand to ANSI
strings but it is more likely that Unicode strings are wanted in the Unicode
build. wxWidgets provides the macros @c __TFILE__, @c __TDATE__
and @c __TTIME__ which behave exactly as the standard ones except that
they produce ANSI strings in ANSI build and Unicode ones in the Unicode build.
build. wxWidgets provides the macros @c __TFILE__, @c __TDATE__ and
@c __TTIME__ which behave exactly as the standard ones except that they produce
ANSI strings in ANSI build and Unicode ones in the Unicode build.
To summarize, here is a brief example of how a program which can be compiled
in both ANSI and Unicode modes could look like:
@@ -110,11 +110,11 @@
@endcode
Of course, it would be nearly impossibly to write such programs if it had to
be done this way (try to imagine the number of @c #ifdef UNICODE an average
program would have had!). Luckily, there is another way - see the next
section.
be done this way (try to imagine the number of @ifdef UNICODE an average
program would have had!). Luckily, there is another way - see the next section.
@section overview_unicodeinsidewxw Unicode support in wxWidgets
@section overview_unicode_supportin Unicode Support in wxWidgets
In wxWidgets, the code fragment from above should be written instead:
@@ -124,88 +124,84 @@
int len = s.Len();
@endcode
What happens here? First of all, you see that there are no more @c #ifdefs
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.
the Unicode and ANSI builds and allow us to avoid using conditional compilation
in the program itself.
We have a @c wxChar type which maps either on @c char or @c wchar_t
depending on the mode in which program is being compiled. There is no need for
a separate type for strings though, because the standard
#wxString supports Unicode, i.e. it stores either ANSI or
Unicode strings depending on the compile mode.
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.
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!
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.
@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_unicodeoutsidewxw Unicode and the outside world
@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.
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:
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.
This code also compiles fine under a non-Unicode build of wxWidgets, but in
that case the converter is ignored.
For more information about converters and Unicode see
the @ref overview_mbconvclasses.
For more information about converters and Unicode see the @ref overview_mbconv.
@section overview_unicodesettings 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.
@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_mbconvclasses)
and construct wxString objects from Unicode strings (presumably read
from some external file or elsewhere).
ANSI ones (using @ref overview_mbconv "wxMBConv") and construct wxString
objects from Unicode strings (presumably read from some external file or
elsewhere).
@section overview_topic8 Traps for the unwary
- Casting c_str() to void* is now char*, not wxChar*
- Passing c_str(), mb_str() or wc_str() to variadic functions
doesn't work
@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.
*/

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

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