/////////////////////////////////////////////////////////////////////////////
-// Name: printing
+// Name: printing.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page overview_printing Printing overview
-
- Classes: #wxPrintout,
- #wxPrinter,
- #wxPrintPreview,
- #wxPrinterDC,
- #wxPostScriptDC,
- #wxPrintDialog,
- #wxPrintData,
- #wxPrintDialogData,
- #wxPageSetupDialog,
- #wxPageSetupDialogData
- The printing framework relies on the application to provide classes whose member
- functions can respond to particular requests, such as 'print this page' or 'does
- this page exist in the document?'. This method allows wxWidgets to take over the
- housekeeping duties of turning preview pages, calling the print dialog box,
- creating the printer device context, and so on: the application can concentrate
- on the rendering of the information onto a device context.
- In most cases, the only class you will need to derive from is
- #wxPrintout; all others will be used as-is.
- A brief description of each class's role and how they work together follows.
- For the special case of printing under Unix, where various different
- printing backends have to be offered, please have a look at the
- @ref unixprinting_overview.
- @ref topic9_overview
- @ref topic10_overview
- @ref topic11_overview
- @ref topic12_overview
- @ref topic13_overview
- @ref topic14_overview
- @ref topic15_overview
- @ref topic16_overview
- @ref topic17_overview
- @ref topic18_overview
-
-
- @section topic9 #wxPrintout
-
- A document's printing ability is represented in an application by a derived
- wxPrintout class. This class prints a page on request, and can be passed to the
- Print function of a wxPrinter object to actually print the document, or can be
- passed to a wxPrintPreview object to initiate previewing. The following code
- (from the printing sample) shows how easy it is to initiate printing, previewing
- and the print setup dialog, once the wxPrintout functionality has been defined.
- Notice the use of MyPrintout for both printing and previewing. All the preview
- user interface functionality is taken care of by wxWidgets. For more details on how
- MyPrintout is defined, please look at the printout sample code.
-
- @code
- case WXPRINT_PRINT:
- {
- wxPrinter printer;
- MyPrintout printout("My printout");
- printer.Print(this, , @true);
- break;
- }
- case WXPRINT_PREVIEW:
- {
- // Pass two printout objects: for preview, and possible printing.
- wxPrintPreview *preview = new wxPrintPreview(new MyPrintout, new MyPrintout);
- wxPreviewFrame *frame = new wxPreviewFrame(preview, this, "Demo Print Preview", wxPoint(100, 100), wxSize(600, 650));
- frame-Centre(wxBOTH);
- frame-Initialize();
- frame-Show(@true);
- break;
- }
- @endcode
-
- Class #wxPrintout assembles the printed page and (using
- your subclass's overrides) writes requested pages to a #wxDC that
- is passed to it. This wxDC could be a #wxMemoryDC (for
- displaying the preview image on-screen), a #wxPrinterDC
- (for printing under MSW and Mac), or a #wxPostScriptDC
- (for printing under GTK or generating PostScript output).
- The @ref docview_overview creates a default
- wxPrintout object for every view, calling wxView::OnDraw to achieve a
- prepackaged print/preview facility.
- If your window classes have a Draw(wxDC *dc) routine to do screen rendering,
- your wxPrintout subclass will typically call those routines to create portions
- of the image on your printout. Your wxPrintout subclass can also make its own
- calls to its wxDC to draw headers, footers, page numbers, etc.
- The scaling of the drawn image typically differs from the screen to the preview
- and printed images. This class provides a set of routines named
- FitThisSizeToXXX(), MapScreenSizeToXXX(), and GetLogicalXXXRect, which can be
- used to set the user scale and origin of the wxPrintout's DC so that your class
- can easily map your image to the printout withough getting into the details of
- screen and printer PPI and scaling. See the printing sample for examples of how
- these routines are used.
-
- @section topic10 #wxPrinter
-
- Class wxPrinter encapsulates the platform-dependent print function with a common
- interface. In most cases, you will not need to derive a class from wxPrinter;
- simply create a wxPrinter object in your Print function as in the example above.
-
- @section topic11 #wxPrintPreview
-
- Class wxPrintPreview manages the print preview process. Among other things, it
- constructs the wxDCs that get passed to your wxPrintout subclass for printing
- and manages the display of multiple pages, a zoomable preview image, and so
- forth. In most cases you will use this class as-is, but you can create your own
- subclass, for example, to change the layout or contents of the preview window.
-
-
- @section topic12 #wxPrinterDC
-
- Class wxPrinterDC is the wxDC that represents the actual printed page under MSW
- and Mac. During printing, an object of this class will be passed to your derived
- wxPrintout object to draw upon. The size of the wxPrinterDC will depend on the
- paper orientation and the resolution of the printer.
- There are two important rectangles in printing: the page rectangle defines
- the printable area seen by the application, and under MSW and Mac, it is the
- printable area specified by the printer. (For PostScript printing, the page
- rectangle is the entire page.) The inherited function
- wxDC::GetSize returns the page size in device pixels. The
- point (0,0) on the wxPrinterDC represents the top left corner of the page
- rectangle; that is, the page rect is given by wxRect(0, 0, w, h), where (w,h)
- are the values returned by GetSize.
- The paper rectangle, on the other hand, represents the entire paper area
- including the non-printable border. Thus, the coordinates of the top left corner
- of the paper rectangle will have small negative values, while the width and
- height will be somewhat larger than that of the page rectangle. The
- wxPrinterDC-specific function
- wxPrinterDC::GetPaperRect returns the paper
- rectangle of the given wxPrinterDC.
-
- @section topic13 #wxPostScriptDC
-
- Class wxPostScriptDC is the wxDC that represents the actual printed page under
- GTK and other PostScript printing. During printing, an object of this class will
- be passed to your derived wxPrintout object to draw upon. The size of the
- wxPostScriptDC will depend upon the #wxPrintData used to
- construct it.
- Unlike a wxPrinterDC, there is no distinction between the page rectangle and the
- paper rectangle in a wxPostScriptDC; both rectangles are taken to represent the
- entire sheet of paper.
-
- @section topic14 #wxPrintDialog
-
- Class wxPrintDialog puts up the standard print dialog, which allows you to
- select the page range for printing (as well as many other print settings, which
- may vary from platform to platform). You provide an object of type
- #wxPrintDialogData to the wxPrintDialog at
- construction, which is used to populate the dialog.
-
- @section topic15 #wxPrintData
-
- Class wxPrintData is a subset of wxPrintDialogData that is used (internally) to
- initialize a wxPrinterDC or wxPostScriptDC. (In fact, a wxPrintData is a data
- member of a wxPrintDialogData and a wxPageSetupDialogData). Essentially,
- wxPrintData contains those bits of information from the two dialogs necessary to
- configure the wxPrinterDC or wxPostScriptDC (e.g., size, orientation, etc.). You
- might wish to create a global instance of this object to provide call-to-call
- persistence to your application's print settings.
-
- @section topic16 #wxPrintDialogData
-
- Class wxPrintDialogData contains the settings entered by the user in the print
- dialog. It contains such things as page range, number of copies, and so forth.
- In most cases, you won't need to access this information; the framework takes
- care of asking your wxPrintout derived object for the pages requested by the
- user.
-
- @section topic17 #wxPageSetupDialog
-
- Class wxPageSetupDialog puts up the standard page setup dialog, which allows you
- to specify the orientation, paper size, and related settings. You provide it
- with a wxPageSetupDialogData object at intialization, which is used to populate
- the dialog; when the dialog is dismissed, this object contains the settings
- chosen by the user, including orientation and/or page margins.
- Note that on Macintosh, the native page setup dialog does not contain entries
- that allow you to change the page margins. You can use the Mac-specific class
- wxMacPageMarginsDialog (which, like wxPageSetupDialog, takes a
- wxPageSetupDialogData object in its constructor) to provide this capability; see
- the printing sample for an example.
-
- @section topic18 #wxPageSetupDialogData
-
- Class wxPageSetupDialogData contains settings affecting the page size (paper
- size), orientation, margins, and so forth. Note that not all platforms populate
- all fields; for example, the MSW page setup dialog lets you set the page margins
- while the Mac setup dialog does not.
- You will typically create a global instance of each of a wxPrintData and
- wxPageSetupDialogData at program initiation, which will contain the default
- settings provided by the system. Each time the user calls up either the
- wxPrintDialog or the wxPageSetupDialog, you pass these data structures to
- initialize the dialog values and to be updated by the dialog. The framework then
- queries these data structures to get information like the printed page range
- (from the wxPrintDialogData) or the paper size and/or page orientation (from the
- wxPageSetupDialogData).
-
- */
+@page overview_printing Printing Overview
+
+Classes:
+@li wxPrintout
+@li wxPrinter
+@li wxPrintPreview
+@li wxPrinterDC
+@li wxPostScriptDC
+@li wxPrintDialog
+@li wxPrintData
+@li wxPrintDialogData
+@li wxPageSetupDialog
+@li wxPageSetupDialogData
+
+The printing framework relies on the application to provide classes whose
+member functions can respond to particular requests, such as 'print this page'
+or 'does this page exist in the document?'. This method allows wxWidgets to
+take over the housekeeping duties of turning preview pages, calling the print
+dialog box, creating the printer device context, and so on: the application can
+concentrate on the rendering of the information onto a device context.
+
+In most cases, the only class you will need to derive from is wxPrintout; all
+others will be used as-is.
+
+A brief description of each class's role and how they work together follows.
+
+For the special case of printing under Unix, where various different printing
+backends have to be offered, please have a look at @ref overview_unixprinting.
+
+
+@section overview_printing_printout wxPrintout
+
+A document's printing ability is represented in an application by a derived
+wxPrintout class. This class prints a page on request, and can be passed to the
+Print function of a wxPrinter object to actually print the document, or can be
+passed to a wxPrintPreview object to initiate previewing. The following code
+(from the printing sample) shows how easy it is to initiate printing,
+previewing and the print setup dialog, once the wxPrintout functionality has
+been defined. Notice the use of MyPrintout for both printing and previewing.
+All the preview user interface functionality is taken care of by wxWidgets. For
+more details on how MyPrintout is defined, please look at the printout sample
+code.
+
+@code
+case WXPRINT_PRINT:
+{
+ wxPrinter printer;
+ MyPrintout printout("My printout");
+ printer.Print(this, &printout, true);
+ break;
+}
+case WXPRINT_PREVIEW:
+{
+ // Pass two printout objects: for preview, and possible printing.
+ wxPrintPreview *preview = new wxPrintPreview(new MyPrintout, new MyPrintout);
+ wxPreviewFrame *frame = new wxPreviewFrame(preview, this,
+ "Demo Print Preview",
+ wxPoint(100, 100),
+ wxSize(600, 650));
+ frame->Centre(wxBOTH);
+ frame->Initialize();
+ frame->Show(true);
+ break;
+}
+@endcode
+
+wxPrintout assembles the printed page and (using your subclass's overrides)
+writes requested pages to a wxDC that is passed to it. This wxDC could be a
+wxMemoryDC (for displaying the preview image on-screen), a wxPrinterDC (for
+printing under MSW and Mac), or a wxPostScriptDC (for printing under GTK or
+generating PostScript output).
+
+The @ref overview_docview "document/view framework" creates a default
+wxPrintout object for every view, calling wxView::OnDraw to achieve a
+prepackaged print/preview facility.
+
+If your window classes have a Draw(wxDC *dc) routine to do screen rendering,
+your wxPrintout subclass will typically call those routines to create portions
+of the image on your printout. Your wxPrintout subclass can also make its own
+calls to its wxDC to draw headers, footers, page numbers, etc.
+
+The scaling of the drawn image typically differs from the screen to the preview
+and printed images. This class provides a set of routines named
+FitThisSizeToXXX(), MapScreenSizeToXXX(), and GetLogicalXXXRect, which can be
+used to set the user scale and origin of the wxPrintout's DC so that your class
+can easily map your image to the printout withough getting into the details of
+screen and printer PPI and scaling. See the printing sample for examples of how
+these routines are used.
+
+
+@section overview_printing_printer wxPrinter
+
+Class wxPrinter encapsulates the platform-dependent print function with a common
+interface. In most cases, you will not need to derive a class from wxPrinter;
+simply create a wxPrinter object in your Print function as in the example above.
+
+
+@section overview_printing_printpreview wxPrintPreview
+
+Class wxPrintPreview manages the print preview process. Among other things, it
+constructs the wxDCs that get passed to your wxPrintout subclass for printing
+and manages the display of multiple pages, a zoomable preview image, and so
+forth. In most cases you will use this class as-is, but you can create your own
+subclass, for example, to change the layout or contents of the preview window.
+
+
+@section overview_printing_printerdc wxPrinterDC
+
+Class wxPrinterDC is the wxDC that represents the actual printed page under MSW
+and Mac. During printing, an object of this class will be passed to your derived
+wxPrintout object to draw upon. The size of the wxPrinterDC will depend on the
+paper orientation and the resolution of the printer.
+
+There are two important rectangles in printing: the <em>page rectangle</em>
+defines the printable area seen by the application, and under MSW and Mac, it
+is the printable area specified by the printer. (For PostScript printing, the
+page rectangle is the entire page.) The inherited function
+wxDC::GetSize returns the page size in device pixels. The
+point (0,0) on the wxPrinterDC represents the top left corner of the page
+rectangle; that is, the page rect is given by wxRect(0, 0, w, h), where (w,h)
+are the values returned by GetSize.
+
+The <em>paper rectangle</em>, on the other hand, represents the entire paper
+area including the non-printable border. Thus, the coordinates of the top left
+corner of the paper rectangle will have small negative values, while the width
+and height will be somewhat larger than that of the page rectangle. The
+wxPrinterDC-specific function wxPrinterDC::GetPaperRect returns the paper
+rectangle of the given wxPrinterDC.
+
+
+@section overview_printing_postscriptdc wxPostScriptDC
+
+Class wxPostScriptDC is the wxDC that represents the actual printed page under
+GTK and other PostScript printing. During printing, an object of this class
+will be passed to your derived wxPrintout object to draw upon. The size of the
+wxPostScriptDC will depend upon the wxPrintData used to construct it.
+
+Unlike a wxPrinterDC, there is no distinction between the page rectangle and
+the paper rectangle in a wxPostScriptDC; both rectangles are taken to represent
+the entire sheet of paper.
+
+
+@section overview_printing_printdialog wxPrintDialog
+
+Class wxPrintDialog puts up the standard print dialog, which allows you to
+select the page range for printing (as well as many other print settings, which
+may vary from platform to platform). You provide an object of type
+wxPrintDialogData to the wxPrintDialog at construction, which is used to
+populate the dialog.
+
+
+@section overview_printing_printdata wxPrintData
+Class wxPrintData is a subset of wxPrintDialogData that is used (internally) to
+initialize a wxPrinterDC or wxPostScriptDC. (In fact, a wxPrintData is a data
+member of a wxPrintDialogData and a wxPageSetupDialogData). Essentially,
+wxPrintData contains those bits of information from the two dialogs necessary
+to configure the wxPrinterDC or wxPostScriptDC (e.g., size, orientation, etc.).
+You might wish to create a global instance of this object to provide
+call-to-call persistence to your application's print settings.
+
+
+@section overview_printing_printdialogdata wxPrintDialogData
+
+Class wxPrintDialogData contains the settings entered by the user in the print
+dialog. It contains such things as page range, number of copies, and so forth.
+In most cases, you won't need to access this information; the framework takes
+care of asking your wxPrintout derived object for the pages requested by the
+user.
+
+
+@section overview_printing_pagesetupdialog wxPageSetupDialog
+
+Class wxPageSetupDialog puts up the standard page setup dialog, which allows
+you to specify the orientation, paper size, and related settings. You provide
+it with a wxPageSetupDialogData object at intialization, which is used to
+populate the dialog; when the dialog is dismissed, this object contains the
+settings chosen by the user, including orientation and/or page margins.
+
+Note that on Macintosh, the native page setup dialog does not contain entries
+that allow you to change the page margins. You can use the Mac-specific class
+wxMacPageMarginsDialog (which, like wxPageSetupDialog, takes a
+wxPageSetupDialogData object in its constructor) to provide this capability;
+see the printing sample for an example.
+
+
+@section overview_printing_pagesetupdialogdata wxPageSetupDialogData
+
+Class wxPageSetupDialogData contains settings affecting the page size (paper
+size), orientation, margins, and so forth. Note that not all platforms populate
+all fields; for example, the MSW page setup dialog lets you set the page
+margins while the Mac setup dialog does not.
+
+You will typically create a global instance of each of a wxPrintData and
+wxPageSetupDialogData at program initiation, which will contain the default
+settings provided by the system. Each time the user calls up either the
+wxPrintDialog or the wxPageSetupDialog, you pass these data structures to
+initialize the dialog values and to be updated by the dialog. The framework
+then queries these data structures to get information like the printed page
+range (from the wxPrintDialogData) or the paper size and/or page orientation
+(from the wxPageSetupDialogData).
+
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: python
+// Name: python.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page python_overview wxPython overview
-
- This topic was written by Robin Dunn, author of the wxPython wrapper.
- @ref pwhat_overview
- @ref pwhy_overview
- @ref pother_overview
- @ref pusing_overview
- @ref pclasses_overview
- @ref phelp_overview
-
-
- @section wxpwhat What is wxPython?
-
- wxPython is a blending of the wxWidgets GUI classes and the
- #Python programming language.
- @b Python
- So what is Python? Go to
- #http://www.python.org to learn more,
- but in a nutshell Python is an interpreted,
- interactive, object-oriented programming language. It is often
- compared to Tcl, Perl, Scheme or Java.
- Python combines remarkable power with very clear syntax. It has
- modules, classes, exceptions, very high level dynamic data types, and
- dynamic typing. There are interfaces to many system calls and
- libraries, and new built-in modules are easily written in C or
- C++. Python is also usable as an extension language for applications
- that need a programmable interface.
- Python is copyrighted but freely usable and distributable, even for
- commercial use.
- @b wxPython
- wxPython is a Python package that can be imported at runtime that
- includes a collection of Python modules and an extension module
- (native code). It provides a series of Python classes that mirror (or
- shadow) many of the wxWidgets GUI classes. This extension module
- attempts to mirror the class hierarchy of wxWidgets as closely as
- possible. This means that there is a wxFrame class in wxPython that
- looks, smells, tastes and acts almost the same as the wxFrame class in
- the C++ version.
- wxPython is very versatile. It can be used to create standalone GUI
- applications, or in situations where Python is embedded in a C++
- application as an internal scripting or macro language.
- Currently wxPython is available for Win32 platforms and the GTK
- toolkit (wxGTK) on most Unix/X-windows platforms. See the wxPython
- website #http://wxPython.org/ for
- details about getting wxPython working for you.
-
- @section wxpwhy Why use wxPython?
-
- So why would you want to use wxPython over just C++ and wxWidgets?
- Personally I prefer using Python for everything. I only use C++ when I
- absolutely have to eke more performance out of an algorithm, and even
- then I usually code it as an extension module and leave the majority
- of the program in Python.
- Another good thing to use wxPython for is quick prototyping of your
- wxWidgets apps. With C++ you have to continuously go though the
- edit-compile-link-run cycle, which can be quite time consuming. With
- Python it is only an edit-run cycle. You can easily build an
- application in a few hours with Python that would normally take a few
- days or longer with C++. Converting a wxPython app to a C++/wxWidgets app
- should be a straight forward task.
-
- @section wxpother Other Python GUIs
-
- There are other GUI solutions out there for Python.
- @b Tkinter
- Tkinter is the de facto standard GUI for Python. It is available
- on nearly every platform that Python and Tcl/TK are. Why Tcl/Tk?
- Well because Tkinter is just a wrapper around Tcl's GUI toolkit, Tk.
- This has its upsides and its downsides...
- The upside is that Tk is a pretty versatile toolkit. It can be made
- to do a lot of things in a lot of different environments. It is fairly
- easy to create new widgets and use them interchangeably in your
- programs.
- The downside is Tcl. When using Tkinter you actually have two
- separate language interpreters running, the Python interpreter and the
- Tcl interpreter for the GUI. Since the guts of Tcl is mostly about
- string processing, it is fairly slow as well. (Not too bad on a fast
- Pentium II, but you really notice the difference on slower machines.)
- It wasn't until the latest version of Tcl/Tk that native Look and
- Feel was possible on non-Motif platforms. This is because Tk
- usually implements its own widgets (controls) even when there are
- native controls available.
- Tkinter is a pretty low-level toolkit. You have to do a lot of work
- (verbose program code) to do things that would be much simpler with a higher
- level of abstraction.
- @b PythonWin
- PythonWin is an add-on package for Python for the Win32 platform. It
- includes wrappers for MFC as well as much of the Win32 API. Because
- of its foundation, it is very familiar for programmers who have
- experience with MFC and the Win32 API. It is obviously not compatible
- with other platforms and toolkits. PythonWin is organized as separate
- packages and modules so you can use the pieces you need without having
- to use the GUI portions.
- @b Others
- There are quite a few other GUI modules available for Python, some in
- active use, some that haven't been updated for ages. Most are simple
- wrappers around some C or C++ toolkit or another, and most are not
- cross-platform compatible. See @ref Graphics_overview
- for a listing of a few of them.
-
- @section wxpusing Using wxPython
-
- @b First things first...
- I'm not going to try and teach the Python language here. You can do
- that at the http://www.python.org/doc/tut/tut.html.
- I'm also going to assume that you know a bit about wxWidgets already,
- enough to notice the similarities in the classes used.
- Take a look at the following wxPython program. You can find a similar
- program in the @c wxPython/demo directory, named @c DialogUnits.py. If your
- Python and wxPython are properly installed, you should be able to run
- it by issuing this command:
-
-
- @b @c python DialogUnits.py
-
-
-
-
-
- @code
- 001: ## import all of the wxPython GUI package
- 002: from wxPython.wx import *
- 003:
- 004: ## Create a new frame class, derived from the wxPython Frame.
- 005: class MyFrame(wxFrame):
- 006:
- 007: def __init__(self, parent, id, title):
- 008: # First, call the base class' __init__ method to create the frame
- 009: wxFrame.__init__(self, parent, id, title,
- 010: wxPoint(100, 100), wxSize(160, 100))
- 011:
- 012: # Associate some events with methods of this class
- 013: EVT_SIZE(self, self.OnSize)
- 014: EVT_MOVE(self, self.OnMove)
- 015:
- 016: # Add a panel and some controls to display the size and position
- 017: panel = wxPanel(self, -1)
- 018: wxStaticText(panel, -1, "Size:",
- 019: wxDLG_PNT(panel, wxPoint(4, 4)), wxDefaultSize)
- 020: wxStaticText(panel, -1, "Pos:",
- 021: wxDLG_PNT(panel, wxPoint(4, 14)), wxDefaultSize)
- 022: self.sizeCtrl = wxTextCtrl(panel, -1, "",
- 023: wxDLG_PNT(panel, wxPoint(24, 4)),
- 024: wxDLG_SZE(panel, wxSize(36, -1)),
- 025: wxTE_READONLY)
- 026: self.posCtrl = wxTextCtrl(panel, -1, "",
- 027: wxDLG_PNT(panel, wxPoint(24, 14)),
- 028: wxDLG_SZE(panel, wxSize(36, -1)),
- 029: wxTE_READONLY)
- 030:
- 031:
- 032: # This method is called automatically when the CLOSE event is
- 033: # sent to this window
- 034: def OnCloseWindow(self, event):
- 035: # tell the window to kill itself
- 036: self.Destroy()
- 037:
- 038: # This method is called by the system when the window is resized,
- 039: # because of the association above.
- 040: def OnSize(self, event):
- 041: size = event.GetSize()
- 042: self.sizeCtrl.SetValue("%s, %s" % (size.width, size.height))
- 043:
- 044: # tell the event system to continue looking for an event handler,
- 045: # so the default handler will get called.
- 046: event.Skip()
- 047:
- 048: # This method is called by the system when the window is moved,
- 049: # because of the association above.
- 050: def OnMove(self, event):
- 051: pos = event.GetPosition()
- 052: self.posCtrl.SetValue("%s, %s" % (pos.x, pos.y))
- 053:
- 054:
- 055: # Every wxWidgets application must have a class derived from wxApp
- 056: class MyApp(wxApp):
- 057:
- 058: # wxWidgets calls this method to initialize the application
- 059: def OnInit(self):
- 060:
- 061: # Create an instance of our customized Frame class
- 062: frame = MyFrame(@NULL, -1, "This is a test")
- 063: frame.Show(@true)
- 064:
- 065: # Tell wxWidgets that this is our main window
- 066: self.SetTopWindow(frame)
- 067:
- 068: # Return a success flag
- 069: return @true
- 070:
- 071:
- 072: app = MyApp(0) # Create an instance of the application class
- 073: app.MainLoop() # Tell it to start processing events
- 074:
- @endcode
-
-
-
- @b Things to notice
-
-
- At line 2 the wxPython classes, constants, and etc. are imported
- into the current module's namespace. If you prefer to reduce
- namespace pollution you can use "@c from wxPython import wx" and
- then access all the wxPython identifiers through the wx module, for
- example, "@c wx.wxFrame".
- At line 13 the frame's sizing and moving events are connected to
- methods of the class. These helper functions are intended to be like
- the event table macros that wxWidgets employs. But since static event
- tables are impossible with wxPython, we use helpers that are named the
- same to dynamically build the table. The only real difference is
- that the first argument to the event helpers is always the window that
- the event table entry should be added to.
- Notice the use of @c wxDLG_PNT and @c wxDLG_SZE in lines 19
- - 29 to convert from dialog units to pixels. These helpers are unique
- to wxPython since Python can't do method overloading like C++.
- There is an @c OnCloseWindow method at line 34 but no call to
- EVT_CLOSE to attach the event to the method. Does it really get
- called? The answer is, yes it does. This is because many of the
- standard events are attached to windows that have the associated
- standard method names. I have tried to follow the lead of the
- C++ classes in this area to determine what is standard but since
- that changes from time to time I can make no guarantees, nor will it
- be fully documented. When in doubt, use an EVT_*** function.
- At lines 17 to 21 notice that there are no saved references to
- the panel or the static text items that are created. Those of you
- who know Python might be wondering what happens when Python deletes
- these objects when they go out of scope. Do they disappear from the GUI? They
- don't. Remember that in wxPython the Python objects are just shadows of the
- corresponding C++ objects. Once the C++ windows and controls are
- attached to their parents, the parents manage them and delete them
- when necessary. For this reason, most wxPython objects do not need to
- have a __del__ method that explicitly causes the C++ object to be
- deleted. If you ever have the need to forcibly delete a window, use
- the Destroy() method as shown on line 36.
- Just like wxWidgets in C++, wxPython apps need to create a class
- derived from @c wxApp (line 56) that implements a method named
- @c OnInit, (line 59.) This method should create the application's
- main window (line 62) and use @c wxApp.SetTopWindow() (line 66) to
- inform wxWidgets about it.
- And finally, at line 72 an instance of the application class is
- created. At this point wxPython finishes initializing itself, and calls
- the @c OnInit method to get things started. (The zero parameter here is
- a flag for functionality that isn't quite implemented yet. Just
- ignore it for now.) The call to @c MainLoop at line 73 starts the event
- loop which continues until the application terminates or all the top
- level windows are closed.
-
-
-
- @section wxpclasses wxWidgets classes implemented in wxPython
-
- The following classes are supported in wxPython. Most provide nearly
- full implementations of the public interfaces specified in the C++
- documentation, others are less so. They will all be brought as close
- as possible to the C++ spec over time.
-
-
- #wxAcceleratorEntry
- #wxAcceleratorTable
- #wxActivateEvent
- #wxBitmap
- #wxBitmapButton
- #wxBitmapDataObject
- wxBMPHandler
- #wxBoxSizer
- #wxBrush
- #wxBusyInfo
- #wxBusyCursor
- #wxButton
- #wxCalculateLayoutEvent
- #wxCalendarCtrl
- #wxCaret
- #wxCheckBox
- #wxCheckListBox
- #wxChoice
- #wxClientDC
- #wxClipboard
- #wxCloseEvent
- #wxColourData
- #wxColourDialog
- #wxColour
- #wxComboBox
- #wxCommandEvent
- #wxConfig
- #wxControl
- #wxCursor
- #wxCustomDataObject
- #wxDataFormat
- #wxDataObject
- #wxDataObjectComposite
- #wxDataObjectSimple
- #wxDateTime
- #wxDateSpan
- #wxDC
- #wxDialog
- #wxDirDialog
- #wxDragImage
- #wxDropFilesEvent
- #wxDropSource
- #wxDropTarget
- #wxEraseEvent
- #wxEvent
- #wxEvtHandler
- #wxFileConfig
- #wxFileDataObject
- #wxFileDialog
- #wxFileDropTarget
- #wxFileSystem
- #wxFileSystemHandler
- #wxFocusEvent
- #wxFontData
- #wxFontDialog
- #wxFont
- #wxFrame
- #wxFSFile
- #wxGauge
- wxGIFHandler
- #wxGLCanvas
- #wxHtmlCell
- #wxHtmlContainerCell
- #wxHtmlDCRenderer
- #wxHtmlEasyPrinting
- #wxHtmlParser
- #wxHtmlTagHandler
- #wxHtmlTag
- #wxHtmlWinParser
- #wxHtmlPrintout
- #wxHtmlWinTagHandler
- #wxHtmlWindow
- #wxIconizeEvent
- #wxIcon
- #wxIdleEvent
- #wxImage
- #wxImageHandler
- #wxImageList
- #wxIndividualLayoutConstraint
- #wxInitDialogEvent
- #wxInputStream
- #wxInternetFSHandler
- #wxJoystickEvent
- wxJPEGHandler
- #wxKeyEvent
- #wxLayoutAlgorithm
- #wxLayoutConstraints
- #wxListBox
- #wxListCtrl
- #wxListEvent
- #wxListItem
- #wxMask
- #wxMaximizeEvent
- #wxMDIChildFrame
- #wxMDIClientWindow
- #wxMDIParentFrame
- #wxMemoryDC
- #wxMemoryFSHandler
- #wxMenuBar
- #wxMenuEvent
- #wxMenuItem
- #wxMenu
- #wxMessageDialog
- #wxMetaFileDC
- #wxMiniFrame
- #wxMouseEvent
- #wxMoveEvent
- #wxNotebookEvent
- #wxNotebook
- #wxPageSetupDialogData
- #wxPageSetupDialog
- #wxPaintDC
- #wxPaintEvent
- #wxPalette
- #wxPanel
- #wxPen
- wxPNGHandler
- #wxPoint
- #wxPostScriptDC
- #wxPreviewFrame
- #wxPrintData
- #wxPrintDialogData
- #wxPrintDialog
- #wxPrinter
- #wxPrintPreview
- #wxPrinterDC
- #wxPrintout
- #wxProcess
- #wxQueryLayoutInfoEvent
- #wxRadioBox
- #wxRadioButton
- #wxRealPoint
- #wxRect
- #wxRegionIterator
- #wxRegion
- #wxSashEvent
- #wxSashLayoutWindow
- #wxSashWindow
- #wxScreenDC
- #wxScrollBar
- #wxScrollEvent
- #wxScrolledWindow
- #wxScrollWinEvent
- wxShowEvent
- #wxSingleChoiceDialog
- #wxSizeEvent
- #wxSize
- #wxSizer
- #wxSizerItem
- #wxSlider
- #wxSpinButton
- #wxSpinEvent
- #wxSplitterWindow
- #wxStaticBitmap
- #wxStaticBox
- #wxStaticBoxSizer
- #wxStaticLine
- #wxStaticText
- #wxStatusBar
- #wxSysColourChangedEvent
- #wxTaskBarIcon
- #wxTextCtrl
- #wxTextDataObject
- #wxTextDropTarget
- #wxTextEntryDialog
- #wxTimer
- #wxTimerEvent
- #wxTimeSpan
- #wxTipProvider
- wxToolBarTool
- #wxToolBar
- #wxToolTip
- #wxTreeCtrl
- #wxTreeEvent
- #wxTreeItemData
- wxTreeItemId
- #wxUpdateUIEvent
- #wxValidator
- #wxWindowDC
- #wxWindow
- #wxZipFSHandler
-
-
-
- @section wxphelp Where to go for help
-
- Since wxPython is a blending of multiple technologies, help comes from
- multiple sources. See
- #http://wxpython.org/ for details on
- various sources of help, but probably the best source is the
- wxPython-users mail list. You can view the archive or subscribe by
- going to
- #http://lists.wxwindows.org/mailman/listinfo/wxpython-users
- Or you can send mail directly to the list using this address:
- wxpython-users@lists.wxwindows.org
-
- */
+@page overview_python wxPython Overview
+This topic was written by Robin Dunn, author of the wxPython wrapper.
+
+@li @ref overview_python_what
+@li @ref overview_python_why
+@li @ref overview_python_othergui
+@li @ref overview_python_using
+@li @ref overview_python_classes
+@li @ref overview_python_help
+
+
+<hr>
+
+
+@section overview_python_what What is wxPython?
+
+wxPython is a blending of the wxWidgets GUI classes and the Python programming
+language.
+
+@subsection overview_python_what_py Python
+
+So what is Python? Go to http://www.python.org to learn more, but in a
+nutshell Python is an interpreted, interactive, object-oriented programming
+language. It is often compared to Tcl, Perl, Scheme or Java.
+
+Python combines remarkable power with very clear syntax. It has modules,
+classes, exceptions, very high level dynamic data types, and dynamic typing.
+There are interfaces to many system calls and libraries, and new built-in
+modules are easily written in C or C++. Python is also usable as an extension
+language for applications that need a programmable interface.
+
+Python is copyrighted but freely usable and distributable, even for commercial
+use.
+
+@subsection overview_python_what_wxpy wxPython
+
+wxPython is a Python package that can be imported at runtime that includes a
+collection of Python modules and an extension module (native code). It provides
+a series of Python classes that mirror (or shadow) many of the wxWidgets GUI
+classes. This extension module attempts to mirror the class hierarchy of
+wxWidgets as closely as possible. This means that there is a wxFrame class in
+wxPython that looks, smells, tastes and acts almost the same as the wxFrame
+class in the C++ version.
+
+wxPython is very versatile. It can be used to create standalone GUI
+applications, or in situations where Python is embedded in a C++ application as
+an internal scripting or macro language.
+
+Currently wxPython is available for Win32 platforms and the GTK toolkit (wxGTK)
+on most Unix/X-windows platforms. See the wxPython website http://wxPython.org/
+for details about getting wxPython working for you.
+
+
+@section overview_python_why Why Use wxPython?
+
+So why would you want to use wxPython over just C++ and wxWidgets? Personally I
+prefer using Python for everything. I only use C++ when I absolutely have to
+eke more performance out of an algorithm, and even then I usually code it as an
+extension module and leave the majority of the program in Python.
+
+Another good thing to use wxPython for is quick prototyping of your wxWidgets
+apps. With C++ you have to continuously go though the edit-compile-link-run
+cycle, which can be quite time consuming. With Python it is only an edit-run
+cycle. You can easily build an application in a few hours with Python that
+would normally take a few days or longer with C++. Converting a wxPython app to
+a C++/wxWidgets app should be a straight forward task.
+
+
+@section overview_python_othergui Other Python GUIs
+
+There are other GUI solutions out there for Python.
+
+@subsection overview_python_othergui_tkinter Tkinter
+
+Tkinter is the de facto standard GUI for Python. It is available on nearly
+every platform that Python and Tcl/TK are. Why Tcl/Tk? Well because Tkinter is
+just a wrapper around Tcl's GUI toolkit, Tk. This has it's upsides and it's
+downsides...
+
+The upside is that Tk is a pretty versatile toolkit. It can be made to do a lot
+of things in a lot of different environments. It is fairly easy to create new
+widgets and use them interchangeably in your programs.
+
+The downside is Tcl. When using Tkinter you actually have two separate language
+interpreters running, the Python interpreter and the Tcl interpreter for the
+GUI. Since the guts of Tcl is mostly about string processing, it is fairly slow
+as well. (Not too bad on a fast Pentium II, but you really notice the
+difference on slower machines.)
+
+It wasn't until the latest version of Tcl/Tk that native Look and Feel was
+possible on non-Motif platforms. This is because Tk usually implements its own
+widgets (controls) even when there are native controls available.
+
+Tkinter is a pretty low-level toolkit. You have to do a lot of work (verbose
+program code) to do things that would be much simpler with a higher level of
+abstraction.
+
+@subsection overview_python_othergui_pythonwin PythonWin
+
+PythonWin is an add-on package for Python for the Win32 platform. It includes
+wrappers for MFC as well as much of the Win32 API. Because of its foundation,
+it is very familiar for programmers who have experience with MFC and the Win32
+API. It is obviously not compatible with other platforms and toolkits.
+PythonWin is organized as separate packages and modules so you can use the
+pieces you need without having to use the GUI portions.
+
+@subsection overview_python_othergui_others Others
+
+There are quite a few other GUI modules available for Python, some in active
+use, some that haven't been updated for ages. Most are simple wrappers around
+some C or C++ toolkit or another, and most are not cross-platform compatible.
+See http://pypi.python.org/pypi?:action=browse&show=all&c=433 for a listing of
+a few of them.
+
+
+@section overview_python_using Using wxPython
+
+I'm not going to try and teach the Python language here. You can do that at the
+<http://www.python.org/doc/tut/tut.html>. I'm also going to assume that you
+know a bit about wxWidgets already, enough to notice the similarities in the
+classes used.
+
+Take a look at the following wxPython program. You can find a similar program
+in the wxPython/demo directory, named "DialogUnits.py". If your Python and
+wxPython are properly installed, you should be able to run it by issuing this
+command:
+
+@code
+python DialogUnits.py
+@endcode
+
+@code
+01: ## import all of the wxPython GUI package
+02: from wxPython.wx import *
+03:
+04: ## Create a new frame class, derived from the wxPython Frame.
+05: class MyFrame(wxFrame):
+06:
+07: def __init__(self, parent, id, title):
+08: # First, call the base class' __init__ method to create the frame
+09: wxFrame.__init__(self, parent, id, title,
+10: wxPoint(100, 100), wxSize(160, 100))
+11:
+12: # Associate some events with methods of this class
+13: EVT_SIZE(self, self.OnSize)
+14: EVT_MOVE(self, self.OnMove)
+15:
+16: # Add a panel and some controls to display the size and position
+17: panel = wxPanel(self, -1)
+18: wxStaticText(panel, -1, "Size:",
+19: wxDLG_PNT(panel, wxPoint(4, 4)), wxDefaultSize)
+20: wxStaticText(panel, -1, "Pos:",
+21: wxDLG_PNT(panel, wxPoint(4, 14)), wxDefaultSize)
+22: self.sizeCtrl = wxTextCtrl(panel, -1, "",
+23: wxDLG_PNT(panel, wxPoint(24, 4)),
+24: wxDLG_SZE(panel, wxSize(36, -1)),
+25: wxTE_READONLY)
+26: self.posCtrl = wxTextCtrl(panel, -1, "",
+27: wxDLG_PNT(panel, wxPoint(24, 14)),
+28: wxDLG_SZE(panel, wxSize(36, -1)),
+29: wxTE_READONLY)
+30:
+31:
+32: # This method is called automatically when the CLOSE event is
+33: # sent to this window
+34: def OnCloseWindow(self, event):
+35: # tell the window to kill itself
+36: self.Destroy()
+37:
+38: # This method is called by the system when the window is resized,
+39: # because of the association above.
+40: def OnSize(self, event):
+41: size = event.GetSize()
+42: self.sizeCtrl.SetValue("%s, %s" % (size.width, size.height))
+43:
+44: # tell the event system to continue looking for an event handler,
+45: # so the default handler will get called.
+46: event.Skip()
+47:
+48: # This method is called by the system when the window is moved,
+49: # because of the association above.
+50: def OnMove(self, event):
+51: pos = event.GetPosition()
+52: self.posCtrl.SetValue("%s, %s" % (pos.x, pos.y))
+53:
+54:
+55: # Every wxWidgets application must have a class derived from wxApp
+56: class MyApp(wxApp):
+57:
+58: # wxWidgets calls this method to initialize the application
+59: def OnInit(self):
+60:
+61: # Create an instance of our customized Frame class
+62: frame = MyFrame(NULL, -1, "This is a test")
+63: frame.Show(true)
+64:
+65: # Tell wxWidgets that this is our main window
+66: self.SetTopWindow(frame)
+67:
+68: # Return a success flag
+69: return true
+70:
+71:
+72: app = MyApp(0) # Create an instance of the application class
+73: app.MainLoop() # Tell it to start processing events
+74:
+@endcode
+
+@subsection overview_python_using_notice Things to Notice
+
+At line 2 the wxPython classes, constants, and etc. are imported into the
+current module's namespace. If you prefer to reduce namespace pollution you can
+use "from wxPython import wx" and then access all the wxPython identifiers
+through the wx module, for example, "wx.wxFrame".
+
+At line 13 the frame's sizing and moving events are connected to methods of the
+class. These helper functions are intended to be like the event table macros
+that wxWidgets employs. But since static event tables are impossible with
+wxPython, we use helpers that are named the same to dynamically build the
+table. The only real difference is that the first argument to the event helpers
+is always the window that the event table entry should be added to.
+
+Notice the use of @c wxDLG_PNT and @c wxDLG_SZE in lines 19-29 to convert from
+dialog units to pixels. These helpers are unique to wxPython since Python can't
+do method overloading like C++.
+
+There is an @c OnCloseWindow method at line 34 but no call to EVT_CLOSE to
+attach the event to the method. Does it really get called? The answer is, yes
+it does. This is because many of the standard events are attached to windows
+that have the associated standard method names. I have tried to follow the lead
+of the C++ classes in this area to determine what is standard but since that
+changes from time to time I can make no guarantees, nor will it be fully
+documented. When in doubt, use an EVT_*** function.
+
+At lines 17 to 21 notice that there are no saved references to the panel or the
+static text items that are created. Those of you who know Python might be
+wondering what happens when Python deletes these objects when they go out of
+scope. Do they disappear from the GUI? They don't. Remember that in wxPython
+the Python objects are just shadows of the corresponding C++ objects. Once the
+C++ windows and controls are attached to their parents, the parents manage them
+and delete them when necessary. For this reason, most wxPython objects do not
+need to have a __del__ method that explicitly causes the C++ object to be
+deleted. If you ever have the need to forcibly delete a window, use the
+Destroy() method as shown on line 36.
+
+Just like wxWidgets in C++, wxPython apps need to create a class derived from
+@c wxApp (line 56) that implements a method named @c OnInit, (line 59.) This
+method should create the application's main window (line 62) and use
+wxApp.SetTopWindow() (line 66) to inform wxWidgets about it.
+
+And finally, at line 72 an instance of the application class is created. At
+this point wxPython finishes initializing itself, and calls the @c OnInit
+method to get things started. (The zero parameter here is a flag for
+functionality that isn't quite implemented yet. Just ignore it for now.) The
+call to @c MainLoop at line 73 starts the event loop which continues until the
+application terminates or all the top level windows are closed.
+
+
+@section overview_python_classes Classes Implemented in wxPython
+
+The following classes are supported in wxPython. Most provide nearly full
+implementations of the public interfaces specified in the C++ documentation,
+others are less so. They will all be brought as close as possible to the C++
+spec over time.
+
+@li wxAcceleratorEntry
+@li wxAcceleratorTable
+@li wxActivateEvent
+@li wxBitmap
+@li wxBitmapButton
+@li wxBitmapDataObject
+@li wxBMPHandler
+@li wxBoxSizer
+@li wxBrush
+@li wxBusyInfo
+@li wxBusyCursor
+@li wxButton
+@li wxCalculateLayoutEvent
+@li wxCalendarCtrl
+@li wxCaret
+@li wxCheckBox
+@li wxCheckListBox
+@li wxChoice
+@li wxClientDC
+@li wxClipboard
+@li wxCloseEvent
+@li wxColourData
+@li wxColourDialog
+@li wxColour
+@li wxComboBox
+@li wxCommandEvent
+@li wxConfig
+@li wxControl
+@li wxCursor
+@li wxCustomDataObject
+@li wxDataFormat
+@li wxDataObject
+@li wxDataObjectComposite
+@li wxDataObjectSimple
+@li wxDateTime
+@li wxDateSpan
+@li wxDC
+@li wxDialog
+@li wxDirDialog
+@li wxDragImage
+@li wxDropFilesEvent
+@li wxDropSource
+@li wxDropTarget
+@li wxEraseEvent
+@li wxEvent
+@li wxEvtHandler
+@li wxFileConfig
+@li wxFileDataObject
+@li wxFileDialog
+@li wxFileDropTarget
+@li wxFileSystem
+@li wxFileSystemHandler
+@li wxFocusEvent
+@li wxFontData
+@li wxFontDialog
+@li wxFont
+@li wxFrame
+@li wxFSFile
+@li wxGauge
+@li wxGIFHandler
+@li wxGLCanvas
+@li wxHtmlCell
+@li wxHtmlContainerCell
+@li wxHtmlDCRenderer
+@li wxHtmlEasyPrinting
+@li wxHtmlParser
+@li wxHtmlTagHandler
+@li wxHtmlTag
+@li wxHtmlWinParser
+@li wxHtmlPrintout
+@li wxHtmlWinTagHandler
+@li wxHtmlWindow
+@li wxIconizeEvent
+@li wxIcon
+@li wxIdleEvent
+@li wxImage
+@li wxImageHandler
+@li wxImageList
+@li wxIndividualLayoutConstraint
+@li wxInitDialogEvent
+@li wxInputStream
+@li wxInternetFSHandler
+@li wxJoystickEvent
+@li wxJPEGHandler
+@li wxKeyEvent
+@li wxLayoutAlgorithm
+@li wxLayoutConstraints
+@li wxListBox
+@li wxListCtrl
+@li wxListEvent
+@li wxListItem
+@li wxMask
+@li wxMaximizeEvent
+@li wxMDIChildFrame
+@li wxMDIClientWindow
+@li wxMDIParentFrame
+@li wxMemoryDC
+@li wxMemoryFSHandler
+@li wxMenuBar
+@li wxMenuEvent
+@li wxMenuItem
+@li wxMenu
+@li wxMessageDialog
+@li wxMetaFileDC
+@li wxMiniFrame
+@li wxMouseEvent
+@li wxMoveEvent
+@li wxNotebookEvent
+@li wxNotebook
+@li wxPageSetupDialogData
+@li wxPageSetupDialog
+@li wxPaintDC
+@li wxPaintEvent
+@li wxPalette
+@li wxPanel
+@li wxPen
+@li wxPNGHandler
+@li wxPoint
+@li wxPostScriptDC
+@li wxPreviewFrame
+@li wxPrintData
+@li wxPrintDialogData
+@li wxPrintDialog
+@li wxPrinter
+@li wxPrintPreview
+@li wxPrinterDC
+@li wxPrintout
+@li wxProcess
+@li wxQueryLayoutInfoEvent
+@li wxRadioBox
+@li wxRadioButton
+@li wxRealPoint
+@li wxRect
+@li wxRegionIterator
+@li wxRegion
+@li wxSashEvent
+@li wxSashLayoutWindow
+@li wxSashWindow
+@li wxScreenDC
+@li wxScrollBar
+@li wxScrollEvent
+@li wxScrolledWindow
+@li wxScrollWinEvent
+@li wxShowEvent
+@li wxSingleChoiceDialog
+@li wxSizeEvent
+@li wxSize
+@li wxSizer
+@li wxSizerItem
+@li wxSlider
+@li wxSpinButton
+@li wxSpinEvent
+@li wxSplitterWindow
+@li wxStaticBitmap
+@li wxStaticBox
+@li wxStaticBoxSizer
+@li wxStaticLine
+@li wxStaticText
+@li wxStatusBar
+@li wxSysColourChangedEvent
+@li wxTaskBarIcon
+@li wxTextCtrl
+@li wxTextDataObject
+@li wxTextDropTarget
+@li wxTextEntryDialog
+@li wxTimer
+@li wxTimerEvent
+@li wxTimeSpan
+@li wxTipProvider
+@li wxToolBarTool
+@li wxToolBar
+@li wxToolTip
+@li wxTreeCtrl
+@li wxTreeEvent
+@li wxTreeItemData
+@li wxTreeItemId
+@li wxUpdateUIEvent
+@li wxValidator
+@li wxWindowDC
+@li wxWindow
+@li wxZipFSHandler
+
+
+@section overview_python_help Where to Go for Help
+
+Since wxPython is a blending of multiple technologies, help comes from multiple
+sources. See http://wxpython.org/ for details on various sources of help, but
+probably the best source is the wxPython-users mail list. You can view the
+archive or subscribe by going to http://wxpython.org/maillist.php
+
+Or you can send mail directly to the list using this address:
+wxpython-users@lists.wxwidgets.org
+
+*/
CLASSINFO(wxFrame). You can get the wxClassInfo for an object using
wxObject::GetClassInfo.
-@seeaslso
+@seealso
@li wxObject
@li wxCreateDynamicObject
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.
/*!
- @page overview_thread Multithreading overview
-
- Classes: #wxThread, #wxMutex, #wxCriticalSection, #wxCondition
-
- wxWidgets provides a complete set of classes encapsulating objects necessary in
- multithreaded (MT) programs: the wxThread class itself and different
- synchronization objects: mutexes (see wxMutex) and critical sections (see
- wxCriticalSection) with conditions (see wxCondition). The thread API in wxWidgets
- resembles to POSIX1.c threads API (a.k.a. pthreads), although several functions have
- different names and some features inspired by Win32 thread API are there as well.
-
- These classes will hopefully make writing MT programs easier and they also
- provide some extra error checking (compared to the native (be it Win32 or Posix)
- thread API), however it is still a non-trivial undertaking especially for large
- projects. Before starting an MT application (or starting to add MT features to
- an existing one) it is worth asking oneself if there is no easier and safer way
- to implement the same functionality. Of course, in some situations threads
- really make sense (classical example is a server application which launches a
- new thread for each new client), but in others it might be a very poor choice
- (example: launching a separate thread when doing a long computation to show a
- progress dialog). Other implementation choices are available: for the progress
- dialog example it is far better to do the calculations in the idle handler
- (see @ref wxIdleEvent) or even simply do everything at once but call wxWindow::Update()
- periodically to update the screen.
-
- If you do decide to use threads in your application, it is strongly recommended
- that no more than one thread calls GUI functions. The thread sample shows that
- it @e is possible for many different threads to call GUI functions at once
- (all the threads created in the sample access GUI), but it is a very poor design
- choice for anything except an example. The design which uses one GUI thread and
- several worker threads which communicate with the main one using events is much
- more robust and will undoubtedly save you countless problems (example: under
- Win32 a thread can only access GDI objects such as pens, brushes, c created by
- itself and not by the other threads).
-
- For communication between secondary threads and the main thread, you may use
- wxEvtHandler::AddPendingEvent or its short version #wxPostEvent. These functions
- have a thread-safe implementation so that they can be used as they are for
- sending events from one thread to another. However there is no built in method
- to send messages to the worker threads and you will need to use the available
- synchronization classes to implement the solution which suits your needs
- yourself. In particular, please note that it is not enough to derive
- your class from #wxThread and #wxEvtHandler to send messages to it:
- in fact, this does not work at all.
+@page overview_thread Multithreading Overview
+
+Classes: wxThread, wxMutex, wxCriticalSection, wxCondition
+
+wxWidgets provides a complete set of classes encapsulating objects necessary in
+multithreaded (MT) programs: the wxThread class itself and different
+synchronization objects: mutexes (see wxMutex) and critical sections (see
+wxCriticalSection) with conditions (see wxCondition). The thread API i
+wxWidgets resembles to POSIX1.c threads API (a.k.a. pthreads), although several
+functions have different names and some features inspired by Win32 thread API
+are there as well.
+
+These classes will hopefully make writing MT programs easier and they also
+provide some extra error checking (compared to the native (be it Win32 or
+Posix) thread API), however it is still a non-trivial undertaking especially
+for large projects. Before starting an MT application (or starting to add MT
+features to an existing one) it is worth asking oneself if there is no easier
+and safer way to implement the same functionality. Of course, in some
+situations threads really make sense (classical example is a server application
+which launches a new thread for each new client), but in others it might be a
+very poor choice (example: launching a separate thread when doing a long
+computation to show a progress dialog). Other implementation choices are
+available: for the progress dialog example it is far better to do the
+calculations in the idle handler (see wxIdleEvent) or even simply do everything
+at once but call wxWindow::Update() periodically to update the screen.
+
+If you do decide to use threads in your application, it is strongly recommended
+that no more than one thread calls GUI functions. The thread sample shows that
+it @e is possible for many different threads to call GUI functions at once (all
+the threads created in the sample access GUI), but it is a very poor design
+choice for anything except an example. The design which uses one GUI thread and
+several worker threads which communicate with the main one using events is much
+more robust and will undoubtedly save you countless problems (example: under
+Win32 a thread can only access GDI objects such as pens, brushes, c created by
+itself and not by the other threads).
+
+For communication between secondary threads and the main thread, you may use
+wxEvtHandler::AddPendingEvent or its short version wxPostEvent. These functions
+have a thread-safe implementation so that they can be used as they are for
+sending events from one thread to another. However there is no built in method
+to send messages to the worker threads and you will need to use the available
+synchronization classes to implement the solution which suits your needs
+yourself. In particular, please note that it is not enough to derive
+your class from wxThread and wxEvtHandler to send messages to it: in fact, this
+does not work at all.
*/
/////////////////////////////////////////////////////////////////////////////
-// Name: tips
+// Name: tips.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page overview_tips wxTipProvider overview
-
- Many "modern" Windows programs have a feature (some would say annoyance) of
- presenting the user tips at program startup. While this is probably useless to
- the advanced users of the program, the experience shows that the tips may be
- quite helpful for the novices and so more and more programs now do this.
- For a wxWidgets programmer, implementing this feature is extremely easy. To
- show a tip, it is enough to just call #wxShowTip function
- like this:
-
- @code
- if ( ...show tips at startup?... )
- {
- wxTipProvider *tipProvider = wxCreateFileTipProvider("tips.txt", 0);
- wxShowTip(windowParent, tipProvider);
- delete tipProvider;
- }
- @endcode
-
- Of course, you need to get the text of the tips from somewhere - in the example
- above, the text is supposed to be in the file tips.txt from where it is read by
- the @e tip provider. The tip provider is just an object of a class deriving
- from #wxTipProvider. It has to implement one pure
- virtual function of the base class: #GetTip.
- In the case of the tip provider created by
- #wxCreateFileTipProvider, the tips are just
- the lines of the text file.
-
- If you want to implement your own tip provider (for example, if you wish to
- hardcode the tips inside your program), you just have to derive another class
- from wxTipProvider and pass a pointer to the object of this class to wxShowTip -
- then you don't need wxCreateFileTipProvider at all.
-
- You will probably want to save somewhere the index of the tip last
- shown - so that the program doesn't always show the same tip on startup. As you
- also need to remember whether to show tips or not (you shouldn't do it if the
- user unchecked "Show tips on startup" checkbox in the dialog), you will
- probably want to store both the index of the
- last shown tip (as returned by
- wxTipProvider::GetCurrentTip and the flag
- telling whether to show the tips at startup at all.
-
- In a tips.txt file, lines that begin with a # character are considered comments
- and are automatically skipped. Blank lines and lines only having spaces are also
- skipped.
-
- You can easily add runtime-translation capacity by placing each line of the
- tips.txt file inside the usual translation macro. For example, your tips.txt
- file would look like this:
-
- @code
- _("This is my first tip")
- _("This is my second tip")
- @endcode
-
- Now add your tips.txt file into the list of files that gettext searches
- for translatable strings. The tips will thus get included into your
- generated .po file catalog and be translated at runtime along with the rest of
- your application's translatable strings.
-
- Note1: Each line in the tips.txt file needs to strictly begin with exactly the
- 3 characters of underscore-parenthesis-doublequote, and end with
- doublequote-parenthesis, as shown above.
-
- Note2: Remember to escape any doublequote characters within the tip string with
- a backslash-doublequote.
-
- See the dialogs program in your samples folder for a working example inside a
- program.
-
- */
-
+@page overview_tips wxTipProvider Overview
+
+Many "modern" Windows programs have a feature (some would say annoyance) of
+presenting the user tips at program startup. While this is probably useless to
+the advanced users of the program, the experience shows that the tips may be
+quite helpful for the novices and so more and more programs now do this. For a
+wxWidgets programmer, implementing this feature is extremely easy. To show a
+tip, it is enough to just call wxShowTip function like this:
+
+@code
+if ( ...show tips at startup?... )
+{
+ wxTipProvider *tipProvider = wxCreateFileTipProvider("tips.txt", 0);
+ wxShowTip(windowParent, tipProvider);
+ delete tipProvider;
+}
+@endcode
+
+Of course, you need to get the text of the tips from somewhere - in the example
+above, the text is supposed to be in the file tips.txt from where it is read by
+the <em>tip provider</em>. The tip provider is just an object of a class
+deriving from wxTipProvider. It has to implement one pure virtual function of
+the base class: GetTip. In the case of the tip provider created by
+wxCreateFileTipProvider, the tips are just the lines of the text file.
+
+If you want to implement your own tip provider (for example, if you wish to
+hardcode the tips inside your program), you just have to derive another class
+from wxTipProvider and pass a pointer to the object of this class to
+wxShowTip - then you don't need wxCreateFileTipProvider at all.
+
+You will probably want to save somewhere the index of the tip last shown - so
+that the program doesn't always show the same tip on startup. As you also need
+to remember whether to show tips or not (you shouldn't do it if the user
+unchecked "Show tips on startup" checkbox in the dialog), you will probably
+want to store both the index of the last shown tip (as returned by
+wxTipProvider::GetCurrentTip and the flag telling whether to show the tips at
+startup at all.
+
+In a tips.txt file, lines that begin with a # character are considered comments
+and are automatically skipped. Blank lines and lines only having spaces are
+also skipped.
+
+You can easily add runtime-translation capacity by placing each line of the
+tips.txt file inside the usual translation macro. For example, your tips.txt
+file would look like this:
+
+@code
+_("This is my first tip")
+_("This is my second tip")
+@endcode
+
+Now add your tips.txt file into the list of files that gettext searches for
+translatable strings. The tips will thus get included into your generated .po
+file catalog and be translated at runtime along with the rest of your
+application's translatable strings.
+
+@note Each line in the tips.txt file needs to strictly begin with exactly the 3
+characters of underscore-parenthesis-doublequote, and end with
+doublequote-parenthesis, as shown above. Also, remember to escape any
+doublequote characters within the tip string with a backslash-doublequote.
+
+See the dialogs program in your samples folder for a working example inside a
+program.
+
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: toolbar
+// Name: toolbar.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page overview_toolbar Toolbar overview
-
- Classes: #wxToolBar
-
- The toolbar family of classes allows an application to use toolbars
- in a variety of configurations and styles.
-
- The toolbar is a popular user interface component and contains a set of bitmap
- buttons or toggles. A toolbar gives faster access to an application's facilities than
- menus, which have to be popped up and selected rather laboriously.
-
- Instead of supplying one toolbar class with a number
- of different implementations depending on platform, wxWidgets separates
- out the classes. This is because there are a number of different toolbar
- styles that you may wish to use simultaneously, and also, future
- toolbar implementations will emerge which
- cannot all be shoe-horned into the one class.
-
- For each platform, the symbol @b wxToolBar is defined to be one of the
- specific toolbar classes.
-
- The following is a summary of the toolbar classes and their differences.
-
- - @b wxToolBarBase. This is a base class with pure virtual functions,
- and should not be used directly.
- - @b wxToolBarSimple. A simple toolbar class written entirely with generic wxWidgets
- functionality. A simple 3D effect for buttons is possible, but it is not consistent
- with the Windows look and feel. This toolbar can scroll, and you can have arbitrary
- numbers of rows and columns.
- - @b wxToolBarMSW. This class implements an old-style Windows toolbar, only on
- Windows. There are small, three-dimensional buttons, which do not (currently) reflect
- the current Windows colour settings: the buttons are grey. This is the default wxToolBar
- on 16-bit windows.
- - @b wxToolBar95. Uses the native Windows 95 toolbar class. It dynamically adjusts its
- background and button colours according to user colour settings.
- CreateTools must be called after the tools have been added.
- No absolute positioning is supported but you can specify the number
- of rows, and add tool separators with @b AddSeparator.
- Tooltips are supported. @b OnRightClick is not supported. This is the default wxToolBar
- on Windows 95, Windows NT 4 and above. With the style wxTB_FLAT, the flat toolbar
- look is used, with a border that is highlighted when the cursor moves over the buttons.
-
- A toolbar might appear as a single row of images under
- the menubar, or it might be in a separate frame layout in several rows
- and columns. The class handles the layout of the images, unless explicit
- positioning is requested.
-
- A tool is a bitmap which can either be a button (there is no 'state',
- it just generates an event when clicked) or it can be a toggle. If a
- toggle, a second bitmap can be provided to depict the 'on' state; if
- the second bitmap is omitted, either the inverse of the first bitmap
- will be used (for monochrome displays) or a thick border is drawn
- around the bitmap (for colour displays where inverting will not have
- the desired result).
-
- The Windows-specific toolbar classes expect 16-colour bitmaps that are 16 pixels wide and 15 pixels
- high. If you want to use a different size, call @b SetToolBitmapSize
- as the demo shows, before adding tools to the button bar. Don't supply more than
- one bitmap for each tool, because the toolbar generates all three images (normal,
- depressed and checked) from the single bitmap you give it.
-
- @ref overview_usingtoolbarlibrary
-
-
- @section overview_usingtoolbarlibrary Using the toolbar library
-
- Include @c "wx/toolbar.h", or if using a class directly, one of:
-
- - @c "wx/msw/tbarmsw.h for wxToolBarMSW
- - @c "wx/msw/tbar95.h for wxToolBar95
- - @c "wx/tbarsmpl.h for wxToolBarSimple
-
-
- Example of toolbar use are given in the sample program "toolbar''. The
- source is given below. In fact it is out of date because recommended
- practise is to use event handlers (using EVT_MENU or EVT_TOOL) instead of
- overriding OnLeftClick.
-
-
- @code
- /////////////////////////////////////////////////////////////////////////////
- // Name: test.cpp
- // Purpose: wxToolBar sample
- // Author: Julian Smart
- // Modified by:
- // Created: 04/01/98
- // RCS-ID: $Id$
- // Copyright: (c) Julian Smart
- // License: wxWindows license
- /////////////////////////////////////////////////////////////////////////////
-
- // For compilers that support precompilation, includes "wx/wx.h".
- #include "wx/wxprec.h"
-
- #ifdef __BORLANDC__
- #pragma hdrstop
- #endif
-
- #ifndef WX_PRECOMP
- #include "wx/wx.h"
- #endif
-
- #include "wx/toolbar.h"
- #include wx/log.h
-
- #include "test.h"
-
- #if defined(__WXGTK__) || defined(__WXMOTIF__)
- #include "mondrian.xpm"
- #include "bitmaps/new.xpm"
- #include "bitmaps/open.xpm"
- #include "bitmaps/save.xpm"
- #include "bitmaps/copy.xpm"
- #include "bitmaps/cut.xpm"
- #include "bitmaps/print.xpm"
- #include "bitmaps/preview.xpm"
- #include "bitmaps/help.xpm"
- #endif
-
- IMPLEMENT_APP(MyApp)
-
- // The `main program' equivalent, creating the windows and returning the
- // main frame
- bool MyApp::OnInit(void)
- {
- // Create the main frame window
- MyFrame* frame = new MyFrame((wxFrame *) @NULL, -1, (const wxString) "wxToolBar Sample",
- wxPoint(100, 100), wxSize(450, 300));
-
- // Give it a status line
- frame-CreateStatusBar();
-
- // Give it an icon
- frame-SetIcon(wxICON(mondrian));
-
- // Make a menubar
- wxMenu *fileMenu = new wxMenu;
- fileMenu-Append(wxID_EXIT, "E", "Quit toolbar sample" );
-
- wxMenu *helpMenu = new wxMenu;
- helpMenu-Append(wxID_HELP, "", "About toolbar sample");
-
- wxMenuBar* menuBar = new wxMenuBar;
-
- menuBar-Append(fileMenu, "");
- menuBar-Append(helpMenu, "");
-
- // Associate the menu bar with the frame
- frame-SetMenuBar(menuBar);
-
- // Create the toolbar
- frame-CreateToolBar(wxBORDER\_NONE|wxHORIZONTAL|wxTB_FLAT, ID_TOOLBAR);
-
- frame-GetToolBar()-SetMargins( 2, 2 );
-
- InitToolbar(frame-GetToolBar());
-
- // Force a resize. This should probably be replaced by a call to a wxFrame
- // function that lays out default decorations and the remaining content window.
- wxSizeEvent event(wxSize(-1, -1), frame-GetId());
- frame-OnSize(event);
- frame-Show(@true);
-
- frame-SetStatusText("Hello, wxWidgets");
-
- SetTopWindow(frame);
-
- return @true;
- }
-
- bool MyApp::InitToolbar(wxToolBar* toolBar)
- {
- // Set up toolbar
- wxBitmap* toolBarBitmaps[8];
-
- #ifdef __WXMSW__
- toolBarBitmaps[0] = new wxBitmap("icon1");
- toolBarBitmaps[1] = new wxBitmap("icon2");
- toolBarBitmaps[2] = new wxBitmap("icon3");
- toolBarBitmaps[3] = new wxBitmap("icon4");
- toolBarBitmaps[4] = new wxBitmap("icon5");
- toolBarBitmaps[5] = new wxBitmap("icon6");
- toolBarBitmaps[6] = new wxBitmap("icon7");
- toolBarBitmaps[7] = new wxBitmap("icon8");
- #else
- toolBarBitmaps[0] = new wxBitmap( new_xpm );
- toolBarBitmaps[1] = new wxBitmap( open_xpm );
- toolBarBitmaps[2] = new wxBitmap( save_xpm );
- toolBarBitmaps[3] = new wxBitmap( copy_xpm );
- toolBarBitmaps[4] = new wxBitmap( cut_xpm );
- toolBarBitmaps[5] = new wxBitmap( preview_xpm );
- toolBarBitmaps[6] = new wxBitmap( print_xpm );
- toolBarBitmaps[7] = new wxBitmap( help_xpm );
- #endif
-
- #ifdef __WXMSW__
- int width = 24;
- #else
- int width = 16;
- #endif
- int currentX = 5;
-
- toolBar-AddTool(wxID_NEW, *(toolBarBitmaps[0]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "New file");
- currentX += width + 5;
- toolBar-AddTool(wxID_OPEN, *(toolBarBitmaps[1]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Open file");
- currentX += width + 5;
- toolBar-AddTool(wxID_SAVE, *(toolBarBitmaps[2]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Save file");
- currentX += width + 5;
- toolBar-AddSeparator();
- toolBar-AddTool(wxID_COPY, *(toolBarBitmaps[3]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Copy");
- currentX += width + 5;
- toolBar-AddTool(wxID_CUT, *(toolBarBitmaps[4]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Cut");
- currentX += width + 5;
- toolBar-AddTool(wxID_PASTE, *(toolBarBitmaps[5]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Paste");
- currentX += width + 5;
- toolBar-AddSeparator();
- toolBar-AddTool(wxID_PRINT, *(toolBarBitmaps[6]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Print");
- currentX += width + 5;
- toolBar-AddSeparator();
- toolBar-AddTool(wxID_HELP, *(toolBarBitmaps[7]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Help");
-
- toolBar-Realize();
-
- // Can delete the bitmaps since they're reference counted
- int i;
- for (i = 0; i 8; i++)
- delete toolBarBitmaps[i];
-
- return @true;
- }
-
- // wxID_HELP will be processed for the 'About' menu and the toolbar help button.
-
- BEGIN_EVENT_TABLE(MyFrame, wxFrame)
- EVT_MENU(wxID_EXIT, MyFrame::OnQuit)
- EVT_MENU(wxID_HELP, MyFrame::OnAbout)
- EVT_CLOSE(MyFrame::OnCloseWindow)
- EVT_TOOL_RANGE(wxID_OPEN, wxID_PASTE, MyFrame::OnToolLeftClick)
- EVT_TOOL_ENTER(wxID_OPEN, MyFrame::OnToolEnter)
- END_EVENT_TABLE()
-
- // Define my frame constructor
- MyFrame::MyFrame(wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos,
- const wxSize& size, long style):
- wxFrame(parent, id, title, pos, size, style)
- {
- m_textWindow = new wxTextCtrl(this, -1, "", wxPoint(0, 0), wxSize(-1, -1), wxTE_MULTILINE);
- }
-
- void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
- {
- Close(@true);
- }
-
- void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
- {
- (void)wxMessageBox("wxWidgets toolbar sample", "About wxToolBar");
- }
-
- // Define the behaviour for the frame closing
- // - must delete all frames except for the main one.
- void MyFrame::OnCloseWindow(wxCloseEvent& WXUNUSED(event))
- {
- Destroy();
- }
-
- void MyFrame::OnToolLeftClick(wxCommandEvent& event)
- {
- wxString str;
- str.Printf("Clicked on tool %d", event.GetId());
- SetStatusText(str);
- }
-
- void MyFrame::OnToolEnter(wxCommandEvent& event)
- {
- if (event.GetSelection() -1)
- {
- wxString str;
- str.Printf("This is tool number %d", event.GetSelection());
- SetStatusText(str);
- }
- else
- SetStatusText("");
- }
- @endcode
-
- */
-
+@page overview_toolbar Toolbar Overview
+
+Classes: wxToolBar
+
+The toolbar family of classes allows an application to use toolbars in a
+variety of configurations and styles.
+
+The toolbar is a popular user interface component and contains a set of bitmap
+buttons or toggles. A toolbar gives faster access to an application's
+facilities than menus, which have to be popped up and selected rather
+laboriously.
+
+Instead of supplying one toolbar class with a number of different
+implementations depending on platform, wxWidgets separates out the classes.
+This is because there are a number of different toolbar styles that you may
+wish to use simultaneously, and also, future toolbar implementations will
+emerge which cannot all be shoe-horned into the one class.
+
+For each platform, the symbol wxToolBar is defined to be one of the specific
+toolbar classes.
+
+The following is a summary of the toolbar classes and their differences:
+
+@li wxToolBarBase: This is a base class with pure virtual functions, and should
+ not be used directly.
+@li wxToolBarSimple: A simple toolbar class written entirely with generic
+ wxWidgets functionality. A simple 3D effect for buttons is possible, but it
+ is not consistent with the Windows look and feel. This toolbar can scroll,
+ and you can have arbitrary numbers of rows and columns.
+@li wxToolBarMSW: This class implements an old-style Windows toolbar, only on
+ Windows. There are small, three-dimensional buttons, which do not
+ (currently) reflect the current Windows colour settings: the buttons are
+ grey. This is the default wxToolBar on 16-bit windows.
+@li wxToolBar95: Uses the native Windows 95 toolbar class. It dynamically
+ adjusts it's background and button colours according to user colour
+ settings. CreateTools must be called after the tools have been added. No
+ absolute positioning is supported but you can specify the number of rows,
+ and add tool separators with @c AddSeparator. Tooltips are supported.
+ @c OnRightClick is not supported. This is the default wxToolBar on Windows
+ 95, Windows NT 4 and above. With the style wxTB_FLAT, the flat toolbar look
+ is used, with a border that is highlighted when the cursor moves over the
+ buttons.
+
+A toolbar might appear as a single row of images under the menubar, or it might
+be in a separate frame layout in several rows and columns. The class handles
+the layout of the images, unless explicit positioning is requested.
+
+A tool is a bitmap which can either be a button (there is no 'state', it just
+generates an event when clicked) or it can be a toggle. If a toggle, a second
+bitmap can be provided to depict the 'on' state; if the second bitmap is
+omitted, either the inverse of the first bitmap will be used (for monochrome
+displays) or a thick border is drawn around the bitmap (for colour displays
+where inverting will not have the desired result).
+
+The Windows-specific toolbar classes expect 16-colour bitmaps that are 16
+pixels wide and 15 pixels high. If you want to use a different size, call
+@c SetToolBitmapSize as the demo shows, before adding tools to the button bar.
+Don't supply more than one bitmap for each tool, because the toolbar generates
+all three images (normal, depressed, and checked) from the single bitmap you
+give it.
+
+
+@section overview_toolbar_library Using the Toolbar Library
+
+Include @c "wx/toolbar.h", or if using a class directly, one of:
+
+- @c "wx/msw/tbarmsw.h" for wxToolBarMSW
+- @c "wx/msw/tbar95.h" for wxToolBar95
+- @c "wx/tbarsmpl.h" for wxToolBarSimple
+
+An example of using a toolbar is given in the "toolbar" sample.
+
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: treectrl
+// Name: treectrl.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page overview_treectrl wxTreeCtrl overview
+@page overview_treectrl wxTreeCtrl Overview
- Classes: #wxTreeCtrl, #wxImageList
-
- The tree control displays its items in a tree like structure. Each item has its
- own (optional) icon and a label. An item may be either collapsed (meaning that
- its children are not visible) or expanded (meaning that its children are
- shown). Each item in the tree is identified by its @e itemId which is of
- opaque data type @e wxTreeItemId. You can test whether an item is valid
- by calling wxTreeItemId::IsOk.
+Classes: wxTreeCtrl, wxImageList
- The items text and image may be retrieved and changed with
- #GetItemText/#SetItemText
- and
- #GetItemImage/#SetItemImage.
- In fact, an item may even have two images associated with it: the normal one
- and another one for selected state which is set/retrieved with
- #SetItemSelectedImage/#GetItemSelectedImage
- functions, but this functionality might be unavailable on some platforms.
+The tree control displays its items in a tree like structure. Each item has
+its own (optional) icon and a label. An item may be either collapsed (meaning
+that its children are not visible) or expanded (meaning that its children are
+shown). Each item in the tree is identified by its @c itemId which is of opaque
+data type wxTreeItemId. You can test whether an item is valid by calling
+wxTreeItemId::IsOk.
- Tree items have several attributes: an item may be selected or not, visible or
- not, bold or not. It may also be expanded or collapsed. All these attributes
- may be retrieved with the corresponding functions:
- #IsSelected,
- #IsVisible, #IsBold
- and #IsExpanded. Only one item at a time may be
- selected, selecting another one (with
- #SelectItem) automatically unselects the
- previously selected one.
+The items text and image may be retrieved and changed with (Get|Set)ItemText
+and (Get|Set)ItemImage. In fact, an item may even have two images associated
+with it: the normal one and another one for selected state which is
+set/retrieved with (Get|Set)ItemSelectedImage functions, but this functionality
+might be unavailable on some platforms.
- In addition to its icon and label, a user-specific data structure may be associated
- with all tree items. If you wish to do it, you should derive a class from @e wxTreeItemData which is a very simple class having only one function @e GetId() which returns the id of the item this data is associated with. This
- data will be freed by the control itself when the associated item is deleted
- (all items are deleted when the control is destroyed), so you shouldn't delete
- it yourself (if you do it, you should call
- #SetItemData(@NULL) to prevent the tree from
- deleting the pointer second time). The associated data may be retrieved with
- #GetItemData() function.
+Tree items have several attributes: an item may be selected or not, visible or
+not, bold or not. It may also be expanded or collapsed. All these attributes
+may be retrieved with the corresponding functions: IsSelected, IsVisible,
+IsBold and IsExpanded. Only one item at a time may be selected, selecting
+another one (with SelectItem) automatically unselects the previously selected
+one.
- Working with trees is relatively straightforward if all the items are added to
- the tree at the moment of its creation. However, for large trees it may be
- very inefficient. To improve the performance you may want to delay adding the
- items to the tree until the branch containing the items is expanded: so, in the
- beginning, only the root item is created (with
- #AddRoot). Other items are added when
- EVT_TREE_ITEM_EXPANDING event is received: then all items lying immediately
- under the item being expanded should be added, but, of course, only when this
- event is received for the first time for this item - otherwise, the items would
- be added twice if the user expands/collapses/re-expands the branch.
+In addition to its icon and label, a user-specific data structure may be
+associated with all tree items. If you wish to do it, you should derive a class
+from wxTreeItemData which is a very simple class having only one function
+GetId() which returns the id of the item this data is associated with. This
+data will be freed by the control itself when the associated item is deleted
+(all items are deleted when the control is destroyed), so you shouldn't delete
+it yourself (if you do it, you should call SetItemData(@NULL) to prevent the
+tree from deleting the pointer second time). The associated data may be
+retrieved with GetItemData() function.
- The tree control provides functions for enumerating its items. There are 3
- groups of enumeration functions: for the children of a given item, for the
- sibling of the given item and for the visible items (those which are currently
- shown to the user: an item may be invisible either because its branch is
- collapsed or because it is scrolled out of view). Child enumeration functions
- require the caller to give them a @e cookie parameter: it is a number which
- is opaque to the caller but is used by the tree control itself to allow
- multiple enumerations to run simultaneously (this is explicitly allowed). The
- only thing to remember is that the @e cookie passed to
- #GetFirstChild and to
- #GetNextChild should be the same variable (and
- that nothing should be done with it by the user code).
+Working with trees is relatively straightforward if all the items are added to
+the tree at the moment of its creation. However, for large trees it may be
+very inefficient. To improve the performance you may want to delay adding the
+items to the tree until the branch containing the items is expanded: so, in the
+beginning, only the root item is created (with AddRoot). Other items are added
+when EVT_TREE_ITEM_EXPANDING event is received: then all items lying
+immediately under the item being expanded should be added, but, of course, only
+when this event is received for the first time for this item - otherwise, the
+items would be added twice if the user expands/collapses/re-expands the branch.
- Among other features of the tree control are: item sorting with
- #SortChildren which uses the user-defined comparison
- function #OnCompareItems (by default the
- comparison is the alphabetic comparison of tree labels), hit testing
- (determining to which portion of the control the given point belongs, useful
- for implementing drag-and-drop in the tree) with
- #HitTest and editing of the tree item labels in
- place (see #EditLabel).
+The tree control provides functions for enumerating its items. There are 3
+groups of enumeration functions: for the children of a given item, for the
+sibling of the given item and for the visible items (those which are currently
+shown to the user: an item may be invisible either because its branch is
+collapsed or because it is scrolled out of view). Child enumeration functions
+require the caller to give them a @e cookie parameter: it is a number which
+is opaque to the caller but is used by the tree control itself to allow
+multiple enumerations to run simultaneously (this is explicitly allowed). The
+only thing to remember is that the @e cookie passed to GetFirstChild and to
+GetNextChild should be the same variable (and that nothing should be done with
+it by the user code).
- Finally, the tree control has a keyboard interface: the cursor navigation (arrow) keys
- may be used to change the current selection. HOME and END are used to go to
- the first/last sibling of the current item. '+', '-' and '*' expand, collapse
- and toggle the current branch. Note, however, that DEL and INS keys do
- nothing by default, but it is common to associate them with deleting an item from
- a tree and inserting a new one into it.
+Among other features of the tree control are: item sorting with SortChildren
+which uses the user-defined comparison function OnCompareItems (by default the
+comparison is the alphabetic comparison of tree labels), hit testing
+(determining to which portion of the control the given point belongs, useful
+for implementing drag-and-drop in the tree) with HitTest and editing of the
+tree item labels in place (see EditLabel).
- */
+Finally, the tree control has a keyboard interface: the cursor navigation
+(arrow) keys may be used to change the current selection. HOME and END are used
+to go to the first/last sibling of the current item. '+', '-' and '*' expand,
+collapse and toggle the current branch. Note, however, that DEL and INS keys do
+nothing by default, but it is common to associate them with deleting an item
+from a tree and inserting a new one into it.
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: unicode
+// Name: unicode.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page overview_unicode Unicode support in wxWidgets
-
- This section briefly describes the state of the Unicode support in wxWidgets.
- Read it if you want to know more about how to write programs able to work with
- characters from languages other than English.
-
- @li @ref overview_whatisunicode
- @li @ref overview_unicodeandansi
- @li @ref overview_unicodeinsidewxw
- @li @ref overview_unicodeoutsidewxw
- @li @ref overview_unicodesettings
- @li @ref overview_topic8
-
-
- @section overview_whatisunicode What is Unicode?
-
- wxWidgets has support for compiling in Unicode mode
- on the platforms which support it. Unicode is a standard for character
- encoding which addresses the shortcomings of the previous, 8 bit standards, by
- using at least 16 (and possibly 32) bits for encoding each character. This
- allows to have at least 65536 characters (what is called the BMP, or basic
- multilingual plane) and possible 2^32 of them instead of the usual 256 and
- is sufficient to encode all of the world languages at once. More details about
- Unicode may be found at #http://www.unicode.org.
-
- As this solution is obviously preferable to the previous ones (think of
- incompatible encodings for the same language, locale chaos and so on), many
- modern operating systems support it. The probably first example is Windows NT
- which uses only Unicode internally since its very first version.
-
- Writing internationalized programs is much easier with Unicode and, as the
- support for it improves, it should become more and more so. Moreover, in the
- Windows NT/2000 case, even the program which uses only standard ASCII can profit
- from using Unicode because they will work more efficiently - there will be no
- need for the system to convert all strings the program uses to/from Unicode
- each time a system call is made.
-
- @section overview_unicodeandansi Unicode and ANSI modes
-
- As not all platforms supported by wxWidgets support Unicode (fully) yet, in
- many cases it is unwise to write a program which can only work in Unicode
- environment. A better solution is to write programs in such way that they may
- be compiled either in ANSI (traditional) mode or in the Unicode one.
-
- This can be achieved quite simply by using the means provided by wxWidgets.
- Basically, there are only a few things to watch out for:
-
-
- - Character type (@c char or @c wchar_t)
- - Literal strings (i.e. @c "Hello, world!" or @c '*')
- - String functions (@c strlen(), @c strcpy(), ...)
- - Special preprocessor tokens (@c __FILE__, @c __DATE__
- and @c __TIME__)
-
-
- Let's look at them in order. First of all, each character in an Unicode
- program takes 2 bytes instead of usual one, so another type should be used to
- store the characters (@c char only holds 1 byte usually). This type is
- called @c wchar_t which stands for @e wide-character type.
-
- Also, the string and character constants should be encoded using wide
- characters (@c wchar_t type) which typically take 2 or 4 bytes instead
- of @c char which only takes one. This is achieved by using the standard C
- (and C++) way: just put the letter @c 'L' after any string constant and it
- becomes a @e long constant, i.e. a wide character one. To make things a bit
- more readable, you are also allowed to prefix the constant with @c 'L'
- instead of putting it after it.
-
- Of course, the usual standard C functions don't work with @c wchar_t
- strings, so another set of functions exists which do the same thing but accept
- @c wchar_t * instead of @c char *. For example, a function to get the
- length of a wide-character string is called @c wcslen() (compare with
- @c strlen() - you see that the only difference is that the "str" prefix
- standing for "string" has been replaced with "wcs" standing for "wide-character
- string").
-
- And finally, the standard preprocessor tokens enumerated above expand to ANSI
- strings but it is more likely that Unicode strings are wanted in the Unicode
- build. wxWidgets provides the macros @c __TFILE__, @c __TDATE__
- and @c __TTIME__ which behave exactly as the standard ones except that
- they produce ANSI strings in ANSI build and Unicode ones in the Unicode build.
-
- To summarize, here is a brief example of how a program which can be compiled
- in both ANSI and Unicode modes could look like:
-
- @code
- #ifdef __UNICODE__
- wchar_t wch = L'*';
- const wchar_t *ws = L"Hello, world!";
- int len = wcslen(ws);
-
- wprintf(L"Compiled at %s\n", __TDATE__);
- #else // ANSI
- char ch = '*';
- const char *s = "Hello, world!";
- int len = strlen(s);
-
- printf("Compiled at %s\n", __DATE__);
- #endif // Unicode/ANSI
- @endcode
-
- Of course, it would be nearly impossibly to write such programs if it had to
- be done this way (try to imagine the number of @c #ifdef UNICODE an average
- program would have had!). Luckily, there is another way - see the next
- section.
-
- @section overview_unicodeinsidewxw Unicode support in wxWidgets
-
- In wxWidgets, the code fragment from above should be written instead:
-
- @code
- wxChar ch = wxT('*');
- wxString s = wxT("Hello, world!");
- int len = s.Len();
- @endcode
-
- What happens here? First of all, you see that there are no more @c #ifdefs
- at all. Instead, we define some types and macros which behave differently in
- the Unicode and ANSI builds and allow us to avoid using conditional
- compilation in the program itself.
-
- We have a @c wxChar type which maps either on @c char or @c wchar_t
- depending on the mode in which program is being compiled. There is no need for
- a separate type for strings though, because the standard
- #wxString supports Unicode, i.e. it stores either ANSI or
- Unicode strings depending on the compile mode.
-
- Finally, there is a special #wxT() macro which should enclose all
- literal strings in the program. As it is easy to see comparing the last
- fragment with the one above, this macro expands to nothing in the (usual) ANSI
- mode and prefixes @c 'L' to its argument in the Unicode mode.
-
- The important conclusion is that if you use @c wxChar instead of
- @c char, avoid using C style strings and use @c wxString instead and
- don't forget to enclose all string literals inside #wxT() macro, your
- program automatically becomes (almost) Unicode compliant!
-
- Just let us state once again the rules:
-
- - Always use @c wxChar instead of @c char
- - Always enclose literal string constants in #wxT() macro
- unless they're already converted to the right representation (another standard
- wxWidgets macro #_() does it, for example, so there is no
- need for @c wxT() in this case) or you intend to pass the constant directly
- to an external function which doesn't accept wide-character strings.
- - Use @c wxString instead of C style strings.
-
- @section overview_unicodeoutsidewxw Unicode and the outside world
-
- We have seen that it was easy to write Unicode programs using wxWidgets types
- and macros, but it has been also mentioned that it isn't quite enough.
- Although everything works fine inside the program, things can get nasty when
- it tries to communicate with the outside world which, sadly, often expects
- ANSI strings (a notable exception is the entire Win32 API which accepts either
- Unicode or ANSI strings and which thus makes it unnecessary to ever perform
- any conversions in the program). GTK 2.0 only accepts UTF-8 strings.
-
- To get an ANSI string from a wxString, you may use the
- mb_str() function which always returns an ANSI
- string (independently of the mode - while the usual
- #c_str() returns a pointer to the internal
- representation which is either ASCII or Unicode). More rarely used, but still
- useful, is wc_str() function which always returns
- the Unicode string.
-
- Sometimes it is also necessary to go from ANSI strings to wxStrings.
- In this case, you can use the converter-constructor, as follows:
-
-
- @code
- const char* ascii_str = "Some text";
- wxString str(ascii_str, wxConvUTF8);
- @endcode
-
- This code also compiles fine under a non-Unicode build of wxWidgets,
- but in that case the converter is ignored.
-
- For more information about converters and Unicode see
- the @ref overview_mbconvclasses.
-
- @section overview_unicodesettings Unicode-related compilation settings
+@page overview_unicode Unicode Support in wxWidgets
+
+This section briefly describes the state of the Unicode support in wxWidgets.
+Read it if you want to know more about how to write programs able to work with
+characters from languages other than English.
- You should define @c wxUSE_UNICODE to 1 to compile your program in
- Unicode mode. This currently works for wxMSW, wxGTK, wxMac and wxX11. If you
- compile your program in ANSI mode you can still define @c wxUSE_WCHAR_T
- to get some limited support for @c wchar_t type.
-
- This will allow your program to perform conversions between Unicode strings and
- ANSI ones (using @ref overview_mbconvclasses)
- and construct wxString objects from Unicode strings (presumably read
- from some external file or elsewhere).
-
- @section overview_topic8 Traps for the unwary
+@li @ref overview_unicode_what
+@li @ref overview_unicode_ansi
+@li @ref overview_unicode_supportin
+@li @ref overview_unicode_supportout
+@li @ref overview_unicode_settings
+@li @ref overview_unicode_traps
- - Casting c_str() to void* is now char*, not wxChar*
- - Passing c_str(), mb_str() or wc_str() to variadic functions
- doesn't work
- */
+<hr>
+@section overview_unicode_what What is Unicode?
+
+wxWidgets has support for compiling in Unicode mode on the platforms which
+support it. Unicode is a standard for character encoding which addresses the
+shortcomings of the previous, 8 bit standards, by using at least 16 (and
+possibly 32) bits for encoding each character. This allows to have at least
+65536 characters (what is called the BMP, or basic multilingual plane) and
+possible 2^32 of them instead of the usual 256 and is sufficient to encode all
+of the world languages at once. More details about Unicode may be found at
+<http://www.unicode.org/>.
+
+As this solution is obviously preferable to the previous ones (think of
+incompatible encodings for the same language, locale chaos and so on), many
+modern operating systems support it. The probably first example is Windows NT
+which uses only Unicode internally since its very first version.
+
+Writing internationalized programs is much easier with Unicode and, as the
+support for it improves, it should become more and more so. Moreover, in the
+Windows NT/2000 case, even the program which uses only standard ASCII can
+profit from using Unicode because they will work more efficiently - there will
+be no need for the system to convert all strings the program uses to/from
+Unicode each time a system call is made.
+
+
+@section overview_unicode_ansi Unicode and ANSI Modes
+
+As not all platforms supported by wxWidgets support Unicode (fully) yet, in
+many cases it is unwise to write a program which can only work in Unicode
+environment. A better solution is to write programs in such way that they may
+be compiled either in ANSI (traditional) mode or in the Unicode one.
+
+This can be achieved quite simply by using the means provided by wxWidgets.
+Basically, there are only a few things to watch out for:
+
+- Character type (@c char or @c wchar_t)
+- Literal strings (i.e. @c "Hello, world!" or @c '*')
+- String functions (@c strlen(), @c strcpy(), ...)
+- Special preprocessor tokens (@c __FILE__, @c __DATE__ and @c __TIME__)
+
+Let's look at them in order. First of all, each character in an Unicode program
+takes 2 bytes instead of usual one, so another type should be used to store the
+characters (@c char only holds 1 byte usually). This type is called @c wchar_t
+which stands for @e wide-character type.
+
+Also, the string and character constants should be encoded using wide
+characters (@c wchar_t type) which typically take 2 or 4 bytes instead of
+@c char which only takes one. This is achieved by using the standard C (and
+C++) way: just put the letter @c 'L' after any string constant and it becomes a
+@e long constant, i.e. a wide character one. To make things a bit more
+readable, you are also allowed to prefix the constant with @c 'L' instead of
+putting it after it.
+
+Of course, the usual standard C functions don't work with @c wchar_t strings,
+so another set of functions exists which do the same thing but accept
+@c wchar_t* instead of @c char*. For example, a function to get the length of a
+wide-character string is called @c wcslen() (compare with @c strlen() - you see
+that the only difference is that the "str" prefix standing for "string" has
+been replaced with "wcs" standing for "wide-character string").
+
+And finally, the standard preprocessor tokens enumerated above expand to ANSI
+strings but it is more likely that Unicode strings are wanted in the Unicode
+build. wxWidgets provides the macros @c __TFILE__, @c __TDATE__ and
+@c __TTIME__ which behave exactly as the standard ones except that they produce
+ANSI strings in ANSI build and Unicode ones in the Unicode build.
+
+To summarize, here is a brief example of how a program which can be compiled
+in both ANSI and Unicode modes could look like:
+
+@code
+#ifdef __UNICODE__
+ wchar_t wch = L'*';
+ const wchar_t *ws = L"Hello, world!";
+ int len = wcslen(ws);
+
+ wprintf(L"Compiled at %s\n", __TDATE__);
+#else // ANSI
+ char ch = '*';
+ const char *s = "Hello, world!";
+ int len = strlen(s);
+
+ printf("Compiled at %s\n", __DATE__);
+#endif // Unicode/ANSI
+@endcode
+
+Of course, it would be nearly impossibly to write such programs if it had to
+be done this way (try to imagine the number of @ifdef UNICODE an average
+program would have had!). Luckily, there is another way - see the next section.
+
+
+@section overview_unicode_supportin Unicode Support in wxWidgets
+
+In wxWidgets, the code fragment from above should be written instead:
+
+@code
+wxChar ch = wxT('*');
+wxString s = wxT("Hello, world!");
+int len = s.Len();
+@endcode
+
+What happens here? First of all, you see that there are no more UNICODE checks
+at all. Instead, we define some types and macros which behave differently in
+the Unicode and ANSI builds and allow us to avoid using conditional compilation
+in the program itself.
+
+We have a @c wxChar type which maps either on @c char or @c wchar_t depending
+on the mode in which program is being compiled. There is no need for a separate
+type for strings though, because the standard wxString supports Unicode, i.e.
+it stores either ANSI or Unicode strings depending on the compile mode.
+
+Finally, there is a special wxT() macro which should enclose all literal
+strings in the program. As it is easy to see comparing the last fragment with
+the one above, this macro expands to nothing in the (usual) ANSI mode and
+prefixes @c 'L' to its argument in the Unicode mode.
+
+The important conclusion is that if you use @c wxChar instead of @c char, avoid
+using C style strings and use @c wxString instead and don't forget to enclose
+all string literals inside wxT() macro, your program automatically becomes
+(almost) Unicode compliant!
+
+Just let us state once again the rules:
+
+@li Always use wxChar instead of @c char
+@li Always enclose literal string constants in wxT() macro unless they're
+ already converted to the right representation (another standard wxWidgets
+ macro _() does it, for example, so there is no need for wxT() in this case)
+ or you intend to pass the constant directly to an external function which
+ doesn't accept wide-character strings.
+@li Use wxString instead of C style strings.
+
+
+@section overview_unicode_supportout Unicode and the Outside World
+
+We have seen that it was easy to write Unicode programs using wxWidgets types
+and macros, but it has been also mentioned that it isn't quite enough. Although
+everything works fine inside the program, things can get nasty when it tries to
+communicate with the outside world which, sadly, often expects ANSI strings (a
+notable exception is the entire Win32 API which accepts either Unicode or ANSI
+strings and which thus makes it unnecessary to ever perform any conversions in
+the program). GTK 2.0 only accepts UTF-8 strings.
+
+To get an ANSI string from a wxString, you may use the mb_str() function which
+always returns an ANSI string (independently of the mode - while the usual
+c_str() returns a pointer to the internal representation which is either ASCII
+or Unicode). More rarely used, but still useful, is wc_str() function which
+always returns the Unicode string.
+
+Sometimes it is also necessary to go from ANSI strings to wxStrings. In this
+case, you can use the converter-constructor, as follows:
+
+@code
+const char* ascii_str = "Some text";
+wxString str(ascii_str, wxConvUTF8);
+@endcode
+
+This code also compiles fine under a non-Unicode build of wxWidgets, but in
+that case the converter is ignored.
+
+For more information about converters and Unicode see the @ref overview_mbconv.
+
+
+@section overview_unicode_settings Unicode Related Compilation Settings
+
+You should define @c wxUSE_UNICODE to 1 to compile your program in Unicode
+mode. This currently works for wxMSW, wxGTK, wxMac and wxX11. If you compile
+your program in ANSI mode you can still define @c wxUSE_WCHAR_T to get some
+limited support for @c wchar_t type.
+
+This will allow your program to perform conversions between Unicode strings and
+ANSI ones (using @ref overview_mbconv "wxMBConv") and construct wxString
+objects from Unicode strings (presumably read from some external file or
+elsewhere).
+
+
+@section overview_unicode_traps Traps for the Unwary
+
+@li Casting c_str() to void* is now char*, not wxChar*
+@li Passing c_str(), mb_str() or wc_str() to variadic functions doesn't work.
+
+*/
+
/////////////////////////////////////////////////////////////////////////////
-// Name: unixprinting
+// Name: unixprinting.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page overview_unixprinting Printing under Unix (GTK+)
-
- Printing under Unix has always been a cause of problems as Unix
- does not provide a standard way to display text and graphics
- on screen and print it to a printer using the same application
- programming interface - instead, displaying on screen is done
- via the X11 library while printing has to be done with using
- PostScript commands. This was particularly difficult to handle
- for the case of fonts with the result that only a selected
- number of application could offer WYSIWYG under Unix. Equally,
- wxWidgets offered its own printing implementation using PostScript
- which never really matched the screen display.
-
- Starting with version 2.8.X, the GNOME project provides printing
- support through the libgnomeprint and libgnomeprintui libraries
- by which especially the font problem is mostly solved. Beginning
- with version 2.5.4, the GTK+ port of wxWidgets can make use of
- these libraries if wxWidgets is configured accordingly and if the
- libraries are present. You need to configure wxWidgets with the
- @e configure --with-gnomeprint switch and your application will
- then search for the GNOME print libraries at runtime. If they
- are found, printing will be done through these, otherwise the
- application will fall back to the old PostScript printing code.
- Note that the application will not require the GNOME print libraries
- to be installed in order to run (there will be no dependency on
- these libraries).
-
- In version GTK+ 2.10, support for printing has been added to GTK+
- itself. Beginning with version wxWidgets 2.9.X, the GTK+ port of
- wxWidgets can make use of this feature
- if wxWidgets is configured accordingly and if the GTK+ version is = 2.10.
- You need to configure wxWidgets with the @e configure --with-gtkprint
- switch and your application will then search for the GTK+ print support
- at runtime. If it is found, printing will be done through GTK+, otherwise the
- application will fall back to GNOME printing support if it is available or,
- if it isn't, to the old PostScript printing code.
- Note that the application will not require a GTK+ version = 2.10
- to be installed in order to run (there will be no dependency on
- this version).
-
- */
-
+@page overview_unixprinting Printing Under Unix (GTK+)
+
+Printing under Unix has always been a cause of problems as Unix does not
+provide a standard way to display text and graphics on screen and print it to a
+printer using the same application programming interface - instead, displaying
+on screen is done via the X11 library while printing has to be done with using
+PostScript commands. This was particularly difficult to handle for the case of
+fonts with the result that only a selected number of application could offer
+WYSIWYG under Unix. Equally, wxWidgets offered its own printing implementation
+using PostScript which never really matched the screen display.
+
+Starting with version 2.8.X, the GNOME project provides printing support
+through the libgnomeprint and libgnomeprintui libraries by which especially the
+font problem is mostly solved. Beginning with version 2.5.4, the GTK+ port of
+wxWidgets can make use of these libraries if wxWidgets is configured
+accordingly and if the libraries are present. You need to configure wxWidgets
+with the <tt>configure --with-gnomeprint</tt> switch and your application will
+then search for the GNOME print libraries at runtime. If they are found,
+printing will be done through these, otherwise the application will fall back
+to the old PostScript printing code. Note that the application will not require
+the GNOME print libraries to be installed in order to run (there will be no
+dependency on these libraries).
+
+In version GTK+ 2.10, support for printing has been added to GTK+ itself.
+Beginning with version wxWidgets 2.9.X, the GTK+ port of wxWidgets can make use
+of this feature if wxWidgets is configured accordingly and if the GTK+ version
+is = 2.10. You need to configure wxWidgets with the
+<tt>configure --with-gtkprint</tt> switch and your application will then search
+for the GTK+ print support at runtime. If it is found, printing will be done
+through GTK+, otherwise the application will fall back to GNOME printing
+support if it is available or, if it isn't, to the old PostScript printing
+code. Note that the application will not require a GTK+ version = 2.10 to be
+installed in order to run (there will be no dependency on this version).
+
+*/
projects / wxWidgets.git / commitdiff
