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