From 36c9828f702fb504b07968703bcd82f04196070a Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Tue, 19 Feb 2008 13:28:24 +0000 Subject: [PATCH] removed useless spaces git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@51911 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/categories.h | 354 +- docs/doxygen/constants.h | 2 +- docs/doxygen/copyright.h | 212 +- docs/doxygen/devtips.h | 216 +- docs/doxygen/introduction.h | 110 +- docs/doxygen/libs.h | 88 +- docs/doxygen/manual.h | 4 +- docs/doxygen/overviews/app.h | 56 +- docs/doxygen/overviews/arc.h | 338 +- docs/doxygen/overviews/aui.h | 10 +- .../doxygen/overviews/backwardcompatibility.h | 188 +- docs/doxygen/overviews/bitmap.h | 112 +- docs/doxygen/overviews/bookctrl.h | 244 +- docs/doxygen/overviews/bufferclasses.h | 16 +- docs/doxygen/overviews/commondialogs.h | 70 +- docs/doxygen/overviews/config.h | 22 +- docs/doxygen/overviews/constraints.h | 74 +- docs/doxygen/overviews/container.h | 14 +- docs/doxygen/overviews/dataobject.h | 40 +- docs/doxygen/overviews/datetime.h | 240 +- docs/doxygen/overviews/dc.h | 22 +- docs/doxygen/overviews/debugging.h | 44 +- docs/doxygen/overviews/dialog.h | 48 +- docs/doxygen/overviews/dnd.h | 106 +- docs/doxygen/overviews/docview.h | 86 +- docs/doxygen/overviews/envvars.h | 82 +- docs/doxygen/overviews/eventhandling.h | 1196 +++--- docs/doxygen/overviews/exceptions.h | 38 +- docs/doxygen/overviews/file.h | 12 +- docs/doxygen/overviews/font.h | 160 +- docs/doxygen/overviews/fontencoding.h | 160 +- docs/doxygen/overviews/fs.h | 128 +- docs/doxygen/overviews/grid.h | 58 +- docs/doxygen/overviews/helloworld.h | 82 +- docs/doxygen/overviews/html.h | 222 +- docs/doxygen/overviews/imagelist.h | 12 +- docs/doxygen/overviews/internationalization.h | 26 +- docs/doxygen/overviews/ipc.h | 76 +- docs/doxygen/overviews/listctrl.h | 10 +- docs/doxygen/overviews/log.h | 80 +- docs/doxygen/overviews/mbconvclasses.h | 82 +- docs/doxygen/overviews/nonenglish.h | 60 +- docs/doxygen/overviews/printing.h | 76 +- docs/doxygen/overviews/python.h | 72 +- docs/doxygen/overviews/referencenotes.h | 10 +- docs/doxygen/overviews/resyn.h | 3318 ++++++++--------- docs/doxygen/overviews/richtextctrl.h | 192 +- docs/doxygen/overviews/roughguide.h | 10 +- docs/doxygen/overviews/runtimeclass.h | 40 +- docs/doxygen/overviews/samples.h | 608 +-- docs/doxygen/overviews/scrolling.h | 116 +- docs/doxygen/overviews/sizer.h | 184 +- docs/doxygen/overviews/splitterwindow.h | 42 +- docs/doxygen/overviews/stream.h | 36 +- docs/doxygen/overviews/string.h | 116 +- docs/doxygen/overviews/thread.h | 24 +- docs/doxygen/overviews/tipprovider.h | 42 +- docs/doxygen/overviews/tips.h | 46 +- docs/doxygen/overviews/toolbar.h | 112 +- docs/doxygen/overviews/treectrl.h | 42 +- docs/doxygen/overviews/trefcount.h | 68 +- docs/doxygen/overviews/unicode.h | 96 +- docs/doxygen/overviews/unixprinting.h | 14 +- docs/doxygen/overviews/validator.h | 34 +- docs/doxygen/overviews/windowdeletion.h | 20 +- docs/doxygen/overviews/windowids.h | 26 +- docs/doxygen/overviews/windowsizing.h | 18 +- docs/doxygen/overviews/windowstyles.h | 14 +- docs/doxygen/overviews/xrc.h | 230 +- docs/doxygen/platdetails.h | 8 +- docs/doxygen/topics.h | 22 +- 71 files changed, 5422 insertions(+), 5414 deletions(-) diff --git a/docs/doxygen/categories.h b/docs/doxygen/categories.h index f0575d49c5..3ea1ce9e47 100644 --- a/docs/doxygen/categories.h +++ b/docs/doxygen/categories.h @@ -12,7 +12,7 @@ @page categories_page Classes by category A classification of wxWidgets classes by category. - + @li @ref cat_manwnd @li @ref cat_miscwnd @li @ref cat_cmndlg @@ -57,11 +57,11 @@ @section cat_manwnd Managed windows - + There are several types of window that are directly controlled by the window manager (such as MS Windows, or the Motif Window Manager). Frames and dialogs are similar in wxWidgets, but only dialogs may be modal. - + @li wxTopLevelWindow: Any top level window, dialog or frame @li wxDialog: Dialog box @li wxFrame: Normal frame @@ -72,14 +72,14 @@ @li wxSplashScreen: Splash screen class @li wxTipWindow: Shows text in a small window @li wxWizard: A wizard dialog - + See also the @ref commondialogs_overview. - + @section cat_miscwnd Miscellaneous windows - + The following are a variety of classes that are derived from wxWindow. - + @li wxPanel: A window whose colour changes according to current user settings @li wxScrolledWindow: Window with automatically managed scrollbars @li wxGrid: A grid (table) window @@ -95,15 +95,15 @@ @li wxVScrolledWindow: As wxScrolledWindow but supports lines of variable height @li wxWizardPage: A base class for the page in wizard dialog. @li wxWizardPageSimple: A page in wizard dialog. - - + + @section cat_cmndlg Common dialogs - + @ref commondialogs_overview - + Common dialogs are ready-made dialog classes which are frequently used in an application. - + @li wxDialog: Base class for common dialogs @li wxColourDialog: Colour chooser dialog @li wxDirDialog: Directory selector dialog @@ -121,13 +121,13 @@ @li wxSymbolPickerDialog: Symbol selector dialog @li wxRichTextFormattingDialog: A dialog for formatting the content of a wxRichTextCtrl @li wxWizard: A wizard dialog. - - + + @section cat_ctrl Controls - + Typically, these are small windows which provide interaction with the user. Controls that are not static can have wxValidator associated with them. - + @li wxAnimationCtrl: A control to display an animation @li wxControl: The base class for controls @li wxButton: Push button control, displaying text @@ -166,55 +166,55 @@ @li wxRadioButton: A round button to be used with others in a mutually exclusive way @li wxSlider: A slider that can be dragged by the user @li wxVListBox: A listbox supporting variable height rows - - - + + + @section cat_miscpickers Miscellaneous pickers - + A picker control is a control whose appearance and behaviour is highly platform-dependent. - + @li wxColourPickerCtrl: A control which allows the user to choose a colour @li wxDirPickerCtrl: A control which allows the user to choose a directory @li wxFilePickerCtrl: A control which allows the user to choose a file @li wxFontPickerCtrl: A control which allows the user to choose a font @li wxDatePickerCtrl: Small date picker control - - - + + + @section cat_menus Menus - + @li wxMenu: Displays a series of menu items for selection @li wxMenuBar: Contains a series of menus for use with a frame @li wxMenuItem: Represents a single menu item - - + + @section cat_wxaui wxAUI - advanced user interface - + This is a new set of classes for writing a customizable application interface with built-in docking, floatable panes and a flexible MDI-like interface. Further classes for custom notebooks with draggable tabs etc. are in progress. See also @ref wxaui_overview. - + @li wxAuiManager: The central class for managing the interface @li wxAuiNotebook: A replacement notebook class with extra features @li wxAuiPaneInfo: Describes a single pane @li wxAuiDockArt: Art and metrics provider for customizing the docking user interface @li wxAuiTabArt: Art and metrics provider for customizing the notebook user interface - - - + + + @section cat_winlayout Window layout - + There are two different systems for laying out windows (and dialogs in particular). One is based upon so-called sizers and it requires less typing, thinking and calculating and will in almost all cases produce dialogs looking equally well on all platforms, the other is based on so-called constraints and is deprecated, though still available. - + @ref sizer_overview describes sizer-based layout. - + These are the classes relevant to sizer-based layout. - + @li wxSizer: Abstract base class @li wxGridSizer: A sizer for laying out windows in a grid with all fields having the same size @li wxFlexGridSizer: A sizer for laying out windows in a flexible grid @@ -222,27 +222,27 @@ @li wxBoxSizer: A sizer for laying out windows in a row or column @li wxStaticBoxSizer: Same as wxBoxSizer, but with a surrounding static box @li wxWrapSizer: A sizer which wraps its child controls as size permits - + @ref constraints_overview describes constraints-based layout. - + These are the classes relevant to constraints-based window layout. - + @li wxIndividualLayoutConstraint: Represents a single constraint dimension @li wxLayoutConstraints: Represents the constraints for a window class - + Other layouting classes: - + @li wxLayoutAlgorithm: An alternative window layout facility - - + + @section cat_dc Device contexts - + @ref dc_overview - + Device contexts are surfaces that may be drawn on, and provide an abstraction that allows parameterisation of your drawing code by passing different device contexts. - + @li wxAutoBufferedPaintDC: A helper device context for double buffered drawing inside @b OnPaint. @li wxBufferedDC: A helper device context for double buffered drawing. @li wxBufferedPaintDC: A helper device context for double buffered drawing inside @b OnPaint. @@ -256,14 +256,14 @@ @li wxMirrorDC: A proxy device context allowing for simple mirroring. @li wxPostScriptDC: A device context for drawing into PostScript files @li wxPrinterDC: A device context for drawing to printers - - + + @section cat_gdi Graphics device interface - + @ref bitmap_overview - + These classes are related to drawing on device contexts and windows. - + @li wxColour: Represents the red, blue and green elements of a colour @li wxDCClipper: Wraps the operations of setting and destroying the clipping region @li wxBitmap: Represents a bitmap @@ -281,15 +281,15 @@ @li wxPalette: Represents a table of indices into RGB values @li wxRegion: Represents a simple or complex region on a window or device context @li wxRendererNative: Abstracts high-level drawing primitives - - + + @section cat_events Events - + @ref eventhandling_overview - + An event object contains information about a specific event. Event handlers - (usually member functions) have a single, event argument. - + (usually member functions) have a single, event argument. + @li wxActivateEvent: A window or application activation event @li wxCalendarEvent: Used with wxCalendarCtrl @li wxCalculateLayoutEvent: Used to calculate window layout @@ -338,24 +338,24 @@ @li wxWindowCreateEvent: A window creation event @li wxWindowDestroyEvent: A window destruction event @li wxWizardEvent: A wizard event - - + + @section cat_val Validators - + @ref validator_overview - + These are the window validators, used for filtering and validating - user input. - + user input. + @li wxValidator: Base validator class @li wxTextValidator: Text control validator class @li wxGenericValidator: Generic control validator class - - + + @section cat_data Data structures - - These are the data structure classes supported by wxWidgets. - + + These are the data structure classes supported by wxWidgets. + @li wxCmdLineParser: Command line parser class @li wxDateSpan: A logical time interval. @li wxDateTime: A class for date/time manipulations @@ -373,15 +373,15 @@ @li wxTimeSpan: A time interval. @li wxURI: Represents a Uniform Resource Identifier @li wxVariant: A class for storing arbitrary types that may change at run-time - - + + @section cat_containers Container classes - + @ref container_overview - + These are classes, templates and class macros are used by wxWidgets. Most of these classes provide a subset or almost complete STL API. - + @li wxArray: A type-safe dynamic array implementation (macro based) @li wxArrayString: An efficient container for storing wxString objects @li wxHashMap: A type-safe hash map implementation (macro based) @@ -389,37 +389,37 @@ @li wxHashTable: A simple hash table implementation (deprecated, use wxHashMap) @li wxList: A type-safe linked list implementation (macro based) @li wxVector: Template base vector implementation identical to std::vector - - + + @section cat_smartpointers Smart pointers - + wxWidgets provides a few smart pointer class templates. - + @li wxObjectDataPtr: A shared pointer (using intrusive reference counting) @li wxScopedPtr: A scoped pointer @li wxSharedPtr: A shared pointer (using non-intrusive reference counting) @li wxWeakRef: A weak reference - - + + @section cat_rtti Run-time class information system - + @ref runtimeclass_overview - + wxWidgets supports run-time manipulation of class information, and dynamic - creation of objects given class names. - + creation of objects given class names. + @li wxClassInfo: Holds run-time class information @li wxObject: Root class for classes with run-time information @li RTTI macros: Macros for manipulating run-time information - - + + @section cat_logging Logging features - + @ref log_overview - + wxWidgets provides several classes and functions for message logging. - Please see the @ref log_overview for more details. - + Please see the @ref log_overview for more details. + @li wxLog: The base log class @li wxLogStderr: Log messages to a C STDIO stream @li wxLogStream: Log messages to a C++ iostream @@ -432,15 +432,15 @@ @li wxLogInterposerTemp: Allows to filter the log messages @li wxStreamToTextRedirector: Allows to redirect output sent to @c cout to a wxTextCtrl @li Log functions: Error and warning logging functions - - + + @section cat_debugging Debugging features - + @ref debugging_overview - + wxWidgets supports some aspects of debugging an application through - classes, functions and macros. - + classes, functions and macros. + @li wxDebugContext: Provides memory-checking facilities @li Debugging macros: Debug macros for assertion and checking @li WXDEBUG\_NEW: Use this macro to give further debugging information @@ -449,12 +449,12 @@ @li wxDebugReportUpload: Class for uploading compressed debug reports via HTTP. @li wxDebugReportPreview: Abstract base class for previewing the contents of a debug report. @li wxDebugReportPreviewStd: Standard implementation of wxDebugReportPreview. - - + + @section cat_net Networking classes - - wxWidgets provides its own classes for socket based networking. - + + wxWidgets provides its own classes for socket based networking. + @li wxDialUpManager: Provides functions to check the status of network connection and to establish one @li wxIPV4address: Represents an Internet address @li wxIPaddress: Represents an Internet address @@ -465,29 +465,29 @@ @li wxFTP: FTP protocol class @li wxHTTP: HTTP protocol class @li wxURL: Represents a Universal Resource Locator - - - + + + @section cat_ipc Interprocess communication - + @ref ipc_overview - + wxWidgets provides simple interprocess communications facilities - based on Windows DDE, but available on most platforms using TCP. - + based on Windows DDE, but available on most platforms using TCP. + @li wxClient, wxDDEClient: Represents a client @li wxConnection, wxDDEConnection: Represents the connection between a client and a server @li wxServer, wxDDEServer: Represents a server - - + + @section cat_dvf Document-view framework - + @ref docview_overview - + wxWidgets supports a document/view framework which provides - housekeeping for a document-centric application. - + housekeeping for a document-centric application. + @li wxDocument: Represents a document @li wxView: Represents a view @li wxDocTemplate: Manages the relationship between a document class and a view class @@ -496,16 +496,16 @@ @li wxDocParentFrame: A parent frame to contain views %@li wxMDIDocChildFrame: An MDI child frame for showing a document view %@li wxMDIDocParentFrame: An MDI parent frame to contain views - - + + @section cat_printing Printing framework - + @ref printing_overview - + A printing and previewing framework is implemented to make it relatively straightforward to provide document printing - facilities. - + facilities. + @li wxPreviewFrame: Frame for displaying a print preview @li wxPreviewCanvas: Canvas for displaying a print preview @li wxPreviewControlBar: Standard control bar for a print preview @@ -518,13 +518,13 @@ @li wxPrintData: Represents information about the document being printed @li wxPrintDialogData: Represents information about the print dialog @li wxPageSetupDialogData: Represents information about the page setup dialog - - - + + + @section cat_dd Drag and drop and clipboard classes - - @ref dnd_overview - + + @ref dnd_overview + @li wxDataObject: Data object class @li wxDataFormat: Represents a data format @li wxTextDataObject: Text data object class @@ -537,12 +537,12 @@ @li wxFileDropTarget: File drop target class @li wxTextDropTarget: Text drop target class @li wxDropSource: Drop source class - - + + @section cat_file File related classes - + wxWidgets has several small classes to work with disk files, see wxfileoverview for more details. - + @li wxFileName: Operations with the file name and attributes @li wxDir: Class for enumerating files/subdirectories. @li wxDirTraverser: Class used together with wxDir for recursively enumerating the files/subdirectories @@ -552,13 +552,13 @@ @li wxTextFile: Class for working with text files as with arrays of lines @li wxStandardPaths: Paths for standard directories @li wxPathList: A class to help search multiple paths - - + + @section cat_streams Stream classes - + wxWidgets has its own set of stream classes, as an alternative to often buggy standard stream libraries, and to provide enhanced functionality. - + @li wxStreamBase: Stream base class @li wxStreamBuffer: Stream buffer class @li wxInputStream: Input stream class @@ -589,15 +589,15 @@ @li wxTarOutputStream: Output stream for writing from tar archives @li wxSocketInputStream: Socket input stream class @li wxSocketOutputStream: Socket output stream class - - + + @section cat_threading Threading classes - + @ref thread_overview - + wxWidgets provides a set of classes to make use of the native thread capabilities of the various platforms. - + @li wxThread: Thread class @li wxThreadHelper: Manages background threads easily @li wxMutex: Mutex class @@ -606,13 +606,13 @@ @li wxCriticalSectionLocker: Critical section locker utility class @li wxCondition: Condition class @li wxSemaphore: Semaphore class - - + + @section cat_html HTML classes - + wxWidgets provides a set of classes to display text in HTML format. These class include a help system based on the HTML widget. - + @li wxHtmlHelpController: HTML help controller class @li wxHtmlWindow: HTML window class @li wxHtmlEasyPrinting: Simple class for printing HTML @@ -621,13 +621,13 @@ @li wxHtmlTagHandler: HTML tag handler, pluginable into wxHtmlParser @li wxHtmlWinParser: HTML parser class for wxHtmlWindow @li wxHtmlWinTagHandler: HTML tag handler, pluginable into wxHtmlWinParser - - + + @section cat_rich Rich text classes - + wxWidgets provides a set of generic classes to edit and print simple rich text with character and paragraph formatting. - + @li wxTextAttr: Attributes specifying text styling. @li wxRichTextCtrl: A rich text control. @li wxRichTextBuffer: The content of a rich text control. @@ -647,46 +647,46 @@ @li wxRichTextPrinting: A class for easy printing of rich text buffers. @li wxRichTextPrintout: A class used by wxRichTextPrinting. @li wxRichTextHeaderFooterData: Header and footer data specification. - - + + @section cat_stc Scintilla text editor classes - + wxWidgets also provides a wrapper around the Scintilla text editor control, which is a control for plain-text editing with support for highlighting, smart indentation, etc. - + @li wxStyledTextCtrl: A wxWidgets implementation of the Scintilla source code editing component. - - + + @section cat_vfs Virtual file system classes - + wxWidgets provides a set of classes that implement an extensible virtual file system, used internally by the HTML classes. - + @li wxFSFile: Represents a file in the virtual file system @li wxFileSystem: Main interface for the virtual file system @li wxFileSystemHandler: Class used to announce file system type - - + + @section cat_xml XML classes - + @li wxXmlDocument: A class to parse XML files @li wxXmlNode: A class which represents XML nodes @li wxXmlAttribute: A class which represent an XML attribute - - + + @section cat_xrc XML-based resource system classes - + @ref xrc_overview - + Resources allow your application to create controls and other user interface elements from specifications stored in an XML format. - + @li wxXmlResource: The main class for working with resources @li wxXmlResourceHandler: The base class for XML resource handlers - - + + @section cat_help Online help - + @li wxHelpController: Family of classes for controlling help windows @li wxHtmlHelpController: HTML help controller class @li wxContextHelp: Class to put application into context-sensitive help mode @@ -695,29 +695,29 @@ @li wxSimpleHelpProvider: Class for simple context-sensitive help provision @li wxHelpControllerHelpProvider: Class for context-sensitive help provision via a help controller @li wxToolTip: Class implementing tooltips - - + + @section cat_media Multimedia classes - + @li wxMediaCtrl: Display multimedia contents. - - + + @section cat_gl OpenGL classes - + @li wxGLCanvas: Canvas that you can render OpenGL calls to. @li wxGLContext: Class to ease sharing of OpenGL data resources. - - + + @section cat_appmanagement Application and process-management classes - + @li wxApp: Application class @li wxCmdLineParser: Command line parser class @li wxDllLoader: Class to work with shared libraries. @li wxProcess: Process class - - + + @section cat_misc Miscellaneous - + @li wxCaret: A caret (cursor) object @li wxConfig: Classes for configuration reading/writing (using either INI files or registry) @li wxTimer: Timer class diff --git a/docs/doxygen/constants.h b/docs/doxygen/constants.h index 25b82ed1c7..cf7595481b 100644 --- a/docs/doxygen/constants.h +++ b/docs/doxygen/constants.h @@ -18,6 +18,6 @@ @section cppconst Preprocessor symbols defined by wxWidgets - + */ diff --git a/docs/doxygen/copyright.h b/docs/doxygen/copyright.h index 0095cbfc76..86d8c5a619 100644 --- a/docs/doxygen/copyright.h +++ b/docs/doxygen/copyright.h @@ -17,8 +17,8 @@ Portions (c) 1996 Artificial Intelligence Applications Institute - - Please also see the wxWindows license files (preamble.txt, lgpl.txt, gpl.txt, + + Please also see the wxWindows license files (preamble.txt, lgpl.txt, gpl.txt, licence.txt, licendoc.txt) for conditions of software and documentation use. Note that we use the old name wxWindows in the license, pending recognition of the new name by OSI. @@ -26,61 +26,61 @@ @ref wxlicense @ref gnulicense - + */ /*! @page wxlicense wxWindows Library License, Version 3.1 - + - + Copyright (c) 1998-2008 Julian Smart, Robert Roebling et al - + Everyone is permitted to copy and distribute verbatim copies of this licence document, but changing it is not allowed. - +
WXWINDOWS LIBRARY LICENCE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
- + This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public Licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version. - + This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public Licence for more details. - + You should have received a copy of the GNU Library General Public Licence along with this software, usually in a file named COPYING.LIB. If not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. - + EXCEPTION NOTICE - + 1. As a special exception, the copyright holders of this library give permission for additional uses of the text contained in this release of the library as licenced under the wxWindows Library Licence, applying either version 3.1 of the Licence, or (at your option) any later version of the Licence as published by the copyright holders of version 3.1 of the Licence document. - + 2. The exception is that you may use, copy, link, modify and distribute under your own terms, binary object code versions of works based on the Library. - + 3. If you copy code from files distributed under the terms of the GNU General Public Licence or the GNU Library General Public Licence into a copy of this library, as this licence permits, the exception does not @@ -88,52 +88,52 @@ to the status of such modified files, you must delete this exception notice from such code and/or adjust the licensing conditions notice accordingly. - + 4. If you write modifications of your own for this library, it is your - choice whether to permit this exception to apply to your modifications. + choice whether to permit this exception to apply to your modifications. If you do not wish that, you must delete the exception notice from such code and/or adjust the licensing conditions notice accordingly. - + */ /*! @page gnulicense GNU Library General Public License, Version 2 - + Copyright (C) 1991 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA - + Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. - + [This is the first released version of the library GPL. It is numbered 2 because it goes with version 2 of the ordinary GPL.] - + @subsection Preamble - + The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software -- to make sure the software is free for all its users. - + This license, the Library General Public License, applies to some specially designated Free Software Foundation software, and to any other libraries whose authors decide to use it. You can use it for your libraries, too. - + When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. - + To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library, or if you modify it. - + For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source @@ -141,32 +141,32 @@ complete object files to the recipients so that they can relink them with the library, after making changes to the library and recompiling it. And you must show them these terms so they know their rights. - + Our method of protecting your rights has two steps: (1) copyright the library, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the library. - + Also, for each distributor's protection, we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on, we want its recipients to know that what they have is not the original version, so that any problems introduced by others will not reflect on the original authors' reputations. - + Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses, thus in effect transforming the program into proprietary software. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. - + Most GNU software, including some libraries, is covered by the ordinary GNU General Public License, which was designed for utility programs. This license, the GNU Library General Public License, applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full, and don't assume that anything in it is the same as in the ordinary license. - + The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library, without @@ -175,12 +175,12 @@ a textual and legal sense, the linked executable is a combined work, a derivative of the original library, and the ordinary General Public License treats it as such. - + Because of this blurred distinction, using the ordinary General Public License for libraries did not effectively promote software sharing, because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better. - + However, unrestricted linking of non-free programs would deprive the users of those programs of all benefit from the free status of the libraries themselves. This Library General Public License is intended to @@ -190,32 +190,32 @@ this as regards changes in header files, but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries. - + The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, while the latter only works together with the library. - + Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one. - +
GNU LIBRARY GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
- + 0. This License Agreement applies to any software library which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Library General Public License (also called "this License"). Each licensee is addressed as "you". - + A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables. - + The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under @@ -223,13 +223,13 @@ portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".) - + "Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library. - + Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from @@ -237,7 +237,7 @@ on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. - + 1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an @@ -245,25 +245,25 @@ all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library. - + You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. - + 2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: - + \begin{indented}{1cm} a) The modified work must itself be a software library. - + b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change. - + c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License. - + d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility @@ -271,15 +271,15 @@ in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. - + (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square - root function must still compute square roots.) + root function must still compute square roots.) \end{indented} - + These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in @@ -290,17 +290,17 @@ this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. - + Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. - + In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. - + 3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so @@ -309,65 +309,65 @@ ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices. - + Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy. - + This option is useful when you wish to copy part of the code of the Library into a program that is not a library. - + 4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. - + If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code. - + 5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License. - + However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables. - + When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law. - + If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) - + Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself. - + 6. As an exception to the Sections above, you may also compile or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications. - + You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work @@ -375,7 +375,7 @@ copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things: - + \begin{indented}{1cm} a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever @@ -388,20 +388,20 @@ that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.) - + b) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution. - + c) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place. - + d) Verify that the user has already received a copy of these materials or that you have already sent this user a copy. \end{indented} - + For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, @@ -410,31 +410,31 @@ components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. - + It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute. - + 7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things: - + \begin{indented}{1cm} a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above. - + b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. \end{indented} - + 8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or @@ -442,7 +442,7 @@ rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. - + 9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are @@ -451,7 +451,7 @@ Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it. - + 10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library @@ -459,7 +459,7 @@ restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. - + 11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or @@ -472,11 +472,11 @@ all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. - + If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances. - + It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the @@ -487,10 +487,10 @@ system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. - + This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. - + 12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add @@ -498,12 +498,12 @@ so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. - + 13. The Free Software Foundation may publish revised and/or new versions of the Library General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. - + Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and @@ -511,7 +511,7 @@ the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. - + 14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is @@ -520,11 +520,11 @@ decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. - + \begin{center} NO WARRANTY \end{center} - + 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR @@ -534,7 +534,7 @@ PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - + 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU @@ -545,59 +545,59 @@ FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - - + +
END OF TERMS AND CONDITIONS
- + @subsection Appendix: How to Apply These Terms to Your New Libraries - + If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License). - + To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. - + @verbatim Copyright (C) - + This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. - + This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. - + You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. @endverbatim - - + + Also add information on how to contact you by electronic and paper mail. - + You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names: - + @verbatim Yoyodyne, Inc., hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker. - + , 1 April 1990 Ty Coon, President of Vice @endverbatim - - + + That's all there is to it! */ diff --git a/docs/doxygen/devtips.h b/docs/doxygen/devtips.h index 67603e8fc9..515c7840ff 100644 --- a/docs/doxygen/devtips.h +++ b/docs/doxygen/devtips.h @@ -28,32 +28,32 @@
- + @section includefiles Include files - + The main include file is {\tt "wx/wx.h"}; this includes the most commonly used modules of wxWidgets. - + To save on compilation time, include only those header files relevant to the source file. If you are using precompiled headers, you should include the following section before any other includes: - + @verbatim // For compilers that support precompilation, includes "wx.h". #include - + #ifdef __BORLANDC__ #pragma hdrstop #endif - + #ifndef WX_PRECOMP // Include your minimal set of headers here, or wx.h #include #endif - + ... now your other include files ... @endverbatim - + The file {\tt "wx/wxprec.h"} includes {\tt "wx/wx.h"}. Although this incantation may seem quirky, it is in fact the end result of a lot of experimentation, and several Windows compilers to use precompilation which is largely automatic for @@ -62,195 +62,195 @@ and newer versions of GCC. Some compilers might need extra work from the application developer to set the build environment up as necessary for the support. - + @section libraries Libraries - + Most ports of wxWidgets can create either a static library or a shared library. wxWidgets can also be built in multilib and monolithic variants. See the \helpref{libraries list}{librarieslist} for more information on these. - + @section configuration Configuration - + When using project files and makefiles directly to build wxWidgets, options are configurable in the file - \rtfsp{\tt "wx/XXX/setup.h"} where XXX is the required platform (such as msw, motif, gtk, mac). Some + \rtfsp{\tt "wx/XXX/setup.h"} where XXX is the required platform (such as msw, motif, gtk, mac). Some settings are a matter of taste, some help with platform-specific problems, and others can be set to minimize the size of the library. Please see the setup.h file and {\tt install.txt} files for details on configuration. - + When using the 'configure' script to configure wxWidgets (on Unix and other platforms where configure is available), the corresponding setup.h files are generated automatically along with suitable makefiles. When using the RPM packages for installing wxWidgets on Linux, a correct setup.h is shipped in the package and this must not be changed. - + @section makefiles Makefiles - + On Microsoft Windows, wxWidgets has a different set of makefiles for each compiler, because each compiler's 'make' tool is slightly different. Popular Windows compilers that we cater for, and the corresponding makefile extensions, include: Microsoft Visual C++ (.vc), Borland C++ (.bcc), OpenWatcom C++ (.wat) and MinGW/Cygwin (.gcc). Makefiles are provided for the wxWidgets library itself, samples, demos, and utilities. - + On Linux, Mac and OS/2, you use the 'configure' command to generate the necessary makefiles. You should also use this method when building with MinGW/Cygwin on Windows. - + We also provide project files for some compilers, such as Microsoft VC++. However, we recommend using makefiles to build the wxWidgets library itself, because makefiles can be more powerful and less manual intervention is required. - + On Windows using a compiler other than MinGW/Cygwin, you would build the wxWidgets library from the build/msw directory which contains the relevant makefiles. - + On Windows using MinGW/Cygwin, and on Unix, MacOS X and OS/2, you invoke 'configure' (found in the top-level of the wxWidgets source hierarchy), from within a suitable empty directory for containing makefiles, object files and libraries. - + For details on using makefiles, configure, and project files, please see docs/xxx/install.txt in your distribution, where xxx is the platform of interest, such as msw, gtk, x11, mac. - + @section windowsfiles Windows-specific files - + wxWidgets application compilation under MS Windows requires at least one extra file: a resource file. - + @subsection resources Resource file - + The least that must be defined in the Windows resource file (extension RC) is the following statement: - + @verbatim #include "wx/msw/wx.rc" @endverbatim - + which includes essential internal wxWidgets definitions. The resource script may also contain references to icons, cursors, etc., for example: - + @verbatim wxicon icon wx.ico @endverbatim - + The icon can then be referenced by name when creating a frame icon. See the MS Windows SDK documentation. - + \normalbox{Note: include wx.rc {\it after} any ICON statements so programs that search your executable for icons (such as the Program Manager) find your application icon first.} - + @section allocatingobjects Allocating and deleting wxWidgets objects - + In general, classes derived from wxWindow must dynamically allocated with {\it new} and deleted with {\it delete}. If you delete a window, all of its children and descendants will be automatically deleted, so you don't need to delete these descendants explicitly. - + When deleting a frame or dialog, use {\bf Destroy} rather than {\bf delete} so that the wxWidgets delayed deletion can take effect. This waits until idle time (when all messages have been processed) to actually delete the window, to avoid problems associated with the GUI sending events to deleted windows. - + Don't create a window on the stack, because this will interfere with delayed deletion. - + If you decide to allocate a C++ array of objects (such as wxBitmap) that may be cleaned up by wxWidgets, make sure you delete the array explicitly before wxWidgets has a chance to do so on exit, since calling {\it delete} on array members will cause memory problems. - + wxColour can be created statically: it is not automatically cleaned up and is unlikely to be shared between other objects; it is lightweight enough for copies to be made. - + Beware of deleting objects such as a wxPen or wxBitmap if they are still in use. Windows is particularly sensitive to this: so make sure you make calls like wxDC::SetPen(wxNullPen) or wxDC::SelectObject(wxNullBitmap) before deleting a drawing object that may be in use. Code that doesn't do this will probably work fine on some platforms, and then fail under Windows. - + @section architecturedependency Architecture dependency - + A problem which sometimes arises from writing multi-platform programs is that the basic C types are not defined the same on all platforms. This holds true - for both the length in bits of the standard types (such as int and long) as + for both the length in bits of the standard types (such as int and long) as well as their byte order, which might be little endian (typically on Intel computers) or big endian (typically on some Unix workstations). wxWidgets defines types and macros that make it easy to write architecture independent code. The types are: - + wxInt32, wxInt16, wxInt8, wxUint32, wxUint16 = wxWord, wxUint8 = wxByte - + where wxInt32 stands for a 32-bit signed integer type etc. You can also check which architecture the program is compiled on using the wxBYTE\_ORDER define which is either wxBIG\_ENDIAN or wxLITTLE\_ENDIAN (in the future maybe wxPDP\_ENDIAN as well). - + The macros handling bit-swapping with respect to the applications endianness are described in the \helpref{Byte order macros}{byteordermacros} section. - + @section conditionalcompilation Conditional compilation - + One of the purposes of wxWidgets is to reduce the need for conditional compilation in source code, which can be messy and confusing to follow. However, sometimes it is necessary to incorporate platform-specific - features (such as metafile use under MS Windows). The \helpref{wxUSE\_*}{wxusedef} + features (such as metafile use under MS Windows). The \helpref{wxUSE\_*}{wxusedef} symbols listed in the file {\tt setup.h} may be used for this purpose, along with any user-supplied ones. - + @section cpp C++ issues - + The following documents some miscellaneous C++ issues. - + @subsection templates Templates - + wxWidgets does not use templates (except for some advanced features that are switched off by default) since it is a notoriously unportable feature. - + @subsection rtti RTTI - + wxWidgets does not use C++ run-time type information since wxWidgets provides its own run-time type information system, implemented using macros. - + @subsection null Type of NULL - + Some compilers (e.g. the native IRIX cc) define NULL to be 0L so that no conversion to pointers is allowed. Because of that, all these - occurrences of NULL in the GTK+ port use an explicit conversion such + occurrences of NULL in the GTK+ port use an explicit conversion such as - + {\small @verbatim wxWindow *my_window = (wxWindow*) NULL; @endverbatim }% - + It is recommended to adhere to this in all code using wxWidgets as this make the code (a bit) more portable. - + @subsection precompiledheaders Precompiled headers - + Some compilers, such as Borland C++ and Microsoft C++, support precompiled headers. This can save a great deal of compiling time. The recommended approach is to precompile {\tt "wx.h"}, using this @@ -258,13 +258,13 @@ wxWidgets applications. For Windows compilers, two dummy source files are provided (one for normal applications and one for creating DLLs) to allow initial creation of the precompiled header. - + However, there are several downsides to using precompiled headers. One is that to take advantage of the facility, you often need to include more header files than would normally be the case. This means that changing a header file will cause more recompilations (in the case of wxWidgets, everything needs to be recompiled since everything includes {\tt "wx.h"}!) - + A related problem is that for compilers that don't have precompiled headers, including a lot of header files slows down compilation considerably. For this reason, you will find (in the common @@ -274,56 +274,56 @@ the optimal compilation for each compiler, although it is biased towards the precompiled headers facility available in Microsoft C++. - + @section filehandling File handling - + When building an application which may be used under different environments, one difficulty is coping with documents which may be moved to different directories on other machines. Saving a file which has pointers to full pathnames is going to be inherently unportable. - + One approach is to store filenames on their own, with no directory information. The application then searches into a list of standard paths (platform-specific) through the use of \helpref{wxStandardPaths}{wxstandardpaths}. - + Eventually you may want to use also the \helpref{wxPathList}{wxpathlist} class. - + Nowadays the limitations of DOS 8+3 filenames doesn't apply anymore. Most modern operating systems allow at least 255 characters in the filename; - the exact maximum length, as well as the characters allowed in the filenames, + the exact maximum length, as well as the characters allowed in the filenames, are OS-specific so you should try to avoid extremely long (> 255 chars) filenames and/or filenames with non-ANSI characters. - + Another thing you need to keep in mind is that all Windows operating systems are case-insensitive, while Unix operating systems (Linux, Mac, etc) are case-sensitive. - + Also, for text files, different OSes use different End Of Lines (EOL). Windows uses CR+LF convention, Linux uses LF only, Mac CR only. - + The \helpref{wxTextFile}{wxtextfile},\helpref{wxTextInputStream}{wxtextinputstream}, \helpref{wxTextOutputStream}{wxtextoutputstream} classes help to abstract from these differences. Of course, there are also 3rd party utilities such as \tt{dos2unix} and \tt{unix2dos} which do the EOL conversions. - - See also the \helpref{File Functions}{filefunctions} section of the reference + + See also the \helpref{File Functions}{filefunctions} section of the reference manual for the description of miscellaneous file handling functions. - + */ /*! @page utilities_page Utilities and libraries supplied with wxWidgets - + In addition to the \helpref{wxWidgets libraries}{librarieslist}, some additional utilities are supplied in the \tt{utils} hierarchy. - + For other user-contributed packages, please see the Contributions page on the \urlref{wxWidgets Web site}{http://www.wxwidgets.org}. - + \begin{description}\itemsep=0pt \item[{\bf Helpview}] Helpview is a program for displaying wxWidgets HTML @@ -354,7 +354,7 @@ /*! @page strategies_page Programming strategies - + This chapter is intended to list strategies that may be useful when writing and debugging wxWidgets programs. If you have any good tips, please submit them for inclusion here. @@ -367,102 +367,102 @@
@section reducingerrors Strategies for reducing programming errors - + @subsection useassert Use ASSERT - - It is good practice to use ASSERT statements liberally, that check for conditions + + It is good practice to use ASSERT statements liberally, that check for conditions that should or should not hold, and print out appropriate error messages. - + These can be compiled out of a non-debugging version of wxWidgets and your application. Using ASSERT is an example of `defensive programming': it can alert you to problems later on. - + See \helpref{wxASSERT}{wxassert} for more info. - + @subsection usewxstring Use wxString in preference to character arrays - + Using \helpref{wxString}{wxstring} can be much safer and more convenient than using wxChar *. - + You can reduce the possibility of memory leaks substantially, and it is much more convenient to use the overloaded operators than functions such as \tt{strcmp}. - wxString won't add a significant overhead to your program; the overhead is compensated + wxString won't add a significant overhead to your program; the overhead is compensated for by easier manipulation (which means less code). - + The same goes for other data types: use classes wherever possible. - + @section portability Strategies for portability - + @subsection usesizers Use sizers - + Don't use absolute panel item positioning if you can avoid it. Different GUIs have very differently sized panel items. Consider using the \helpref{sizers}{sizeroverview} instead. - + @subsection useresources Use wxWidgets resource files - + Use .xrc (wxWidgets resource files) where possible, because they can be easily changed independently of source code. See the \helpref{XRC overview}{xrcoverview} for more info. - + @section debugstrategies Strategies for debugging - + @subsection positivethinking Positive thinking - + It is common to blow up the problem in one's imagination, so that it seems to threaten weeks, months or even years of work. The problem you face may seem insurmountable: but almost never is. Once you have been programming for some time, you will be able to remember similar incidents that threw you into the depths of despair. But remember, you always solved the problem, somehow! - + Perseverance is often the key, even though a seemingly trivial problem can take an apparently inordinate amount of time to solve. In the end, you will probably wonder why you worried so much. That's not to say it isn't painful at the time. Try not to worry -- there are many more important things in life. - + @subsection simplifyproblem Simplify the problem - + Reduce the code exhibiting the problem to the smallest program possible that exhibits the problem. If it is not possible to reduce a large and complex program to a very small program, then try to ensure your code doesn't hide the problem (you may have attempted to minimize the problem in some way: but now you want to expose it). - + With luck, you can add a small amount of code that causes the program to go from functioning to non-functioning state. This should give a clue to the problem. In some cases though, such as memory leaks or wrong deallocation, this can still give totally spurious results! - + @subsection usedebugger Use a debugger - + This sounds like facetious advice, but it is surprising how often people don't use a debugger. Often it is an overhead to install or learn how to use a debugger, but it really is essential for anything but the most trivial programs. - + @subsection uselogging Use logging functions - + There is a variety of logging functions that you can use in your program: see \helpref{Logging functions}{logfunctions}. - + Using tracing statements may be more convenient than using the debugger in some circumstances (such as when your debugger doesn't support a lot of debugging code, or you wish to print a bunch of variables). - + @subsection usedebuggingfacilities Use the wxWidgets debugging facilities - + You can use \helpref{wxDebugContext}{wxdebugcontext} to check for memory leaks and corrupt memory: in fact in debugging mode, wxWidgets will automatically check for memory leaks at the end of the program if wxWidgets is suitably configured. Depending on the operating system and compiler, more or less specific information about the problem will be logged. - + You should also use \helpref{debug macros}{debugmacros} as part of a `defensive programming' strategy, scattering wxASSERTs liberally to test for problems in your code as early as possible. Forward thinking will save a surprising amount of time in the long run. - + See the \helpref{debugging overview}{debuggingoverview} for further information. */ diff --git a/docs/doxygen/introduction.h b/docs/doxygen/introduction.h index feac6189da..264796a2d6 100644 --- a/docs/doxygen/introduction.h +++ b/docs/doxygen/introduction.h @@ -22,44 +22,44 @@ @section whatis What is wxWidgets? - + wxWidgets is a C++ framework providing GUI (Graphical User Interface) and other facilities on more than one platform. Version 2 and higher currently support all desktop versions of MS Windows, Unix with GTK+ 1.x or 2.x, Unix with Motif, Unix with just X11, Unix with DirectFB, Mac OS X, OS/2. - + wxWidgets was originally developed at the Artificial Intelligence Applications Institute, University of Edinburgh, for internal use, and was first made publicly available in 1992. Version 2 is a vastly improved version written and maintained by Julian Smart, Robert Roebling, Vadim Zeitlin, Vaclav Slavik and many others. - + This manual contains a class reference and topic overviews. For a selection of wxWidgets tutorials, please see the documentation page on the \urlref{wxWidgets web site}{http://www.wxwidgets.org}. - + Please note that in the following, ``MS Windows" often refers to all platforms related to Microsoft Windows, including 32-bit and 64-bit variants, unless otherwise stated. All trademarks are acknowledged. - + @section why Why another cross-platform development tool? - + wxWidgets was developed to provide a cheap and flexible way to maximize investment in GUI application development. While a number of commercial class libraries already existed for cross-platform development, none met all of the following criteria: - + \begin{enumerate}\itemsep=0pt \item low price; \item source availability; \item simplicity of programming; \item support for a wide range of compilers. \end{enumerate} - + Since wxWidgets was started, several other free or almost-free GUI frameworks have emerged. However, none has the range of features, flexibility, documentation and the well-established development team that wxWidgets has. - + As open source software, wxWidgets has benefited from comments, ideas, bug fixes, enhancements and the sheer enthusiasm of users. This gives wxWidgets a certain advantage over its @@ -69,12 +69,12 @@ availability of source code is especially important when the future of thousands of lines of application code may depend upon the longevity of the underlying class library. - + Version 2 goes much further than previous versions in terms of generality and features, allowing applications to be produced that are often indistinguishable from those produced using single-platform toolkits such as Motif, GTK+ and MFC. - + The importance of using a platform-independent class library cannot be overstated, since GUI application development is very time-consuming, and sustained popularity of particular GUIs @@ -90,10 +90,10 @@ interface than the native APIs. Programmers may find it worthwhile to use wxWidgets even if they are developing on only one platform. - + It is impossible to sum up the functionality of wxWidgets in a few paragraphs, but here are some of the benefits: - + \begin{itemize}\itemsep=0pt \item Low cost (free, in fact!) \item You get the source. @@ -121,23 +121,23 @@ \item Includes Tex2RTF, to allow you to produce your own documentation in Windows Help, HTML and Word RTF formats. \end{itemize} - + @section requirements wxWidgets requirements - + To make use of wxWidgets, you currently need one of the following setups. - + (a) MS-Windows: - + \begin{enumerate}\itemsep=0pt \item A 32-bit or 64-bit PC running MS Windows. \item A Windows compiler: MS Visual C++ (embedded Visual C++ for wxWinCE port), Borland C++, Watcom C++, Cygwin, MinGW, Metrowerks CodeWarrior, - Digital Mars C++. See {\tt install.txt} for details about compiler + Digital Mars C++. See {\tt install.txt} for details about compiler version supported. \end{enumerate} - + (b) Unix: - + \begin{enumerate}\itemsep=0pt \item Almost any C++ compiler, including GNU C++ and many Unix vendors compilers such as Sun CC, HP-UX aCC or SGI mipsPro. @@ -146,36 +146,36 @@ many features of wxGTK2), Motif 1.2 or higher or Lesstif. If using the wxX11 port, no such widget set is required. \end{enumerate} - + (c) Mac OS/Mac OS X: - + \begin{enumerate}\itemsep=0pt \item A PowerPC or Intel Mac running Mac OS X 10.3 or higher \item The Apple Developer Tools (eg. GNU C++) or MetroWerks CodeWarrior (not actively supported) \end{enumerate} - + Under all platforms it's recommended to have large amounts of free hard disk space. The exact amount needed depends on the port, compiler and build configurations but to give an example, a debug build of the library may take up to 500MB. - + @section where Availability and location of wxWidgets - + \winhelponly{wxWidgets is available by anonymous FTP and World Wide Web from ftp://biolpc22.york.ac.uk/pub and/or http://www.wxwidgets.org.} \winhelpignore{wxWidgets is available by anonymous FTP and World Wide Web - from \urlref{ftp://biolpc22.york.ac.uk/pub}{ftp://biolpc22.york.ac.uk/pub} + from \urlref{ftp://biolpc22.york.ac.uk/pub}{ftp://biolpc22.york.ac.uk/pub} and/or \urlref{http://www.wxwidgets.org}{http://www.wxwidgets.org}.} - + You can also buy a CD-ROM using the form on the Web site. - + @section acknowledgements Acknowledgements - + The following is the list of the core, active developers of wxWidgets which keep it running and have provided an invaluable, extensive and high-quality amount of changes over the many of years of wxWidgets' life: - + \begin{description}\itemsep=0pt \item Julian Smart \item Vadim Zeitlin @@ -191,40 +191,40 @@ \item Stefan Neis \item Michael Wetherell \end{description} - - We would particularly like to thank the following peoples for their contributions - to wxWidgets, and the many others who have been involved in the project over the years. + + We would particularly like to thank the following peoples for their contributions + to wxWidgets, and the many others who have been involved in the project over the years. Apologies for any unintentional omissions from this alphabetic list: - - Yiorgos Adamopoulos, Jamshid Afshar, Alejandro Aguilar-Sierra, AIAI, - Patrick Albert, Karsten Ballueder, Mattia Barbon, Michael Bedward, - Kai Bendorf, Yura Bidus, Keith Gary Boyce, Chris Breeze, Pete Britton, - Ian Brown, C. Buckley, Marco Cavallini, Dmitri Chubraev, Robin Corbet, Cecil Coupe, - Andrew Davison, Gilles Depeyrot, Neil Dudman, Hermann Dunkel, Jos van Eijndhoven, - Tom Felici, Thomas Fettig, Matthew Flatt, Pasquale Foggia, Josep Fortiana, Todd Fries, - Dominic Gallagher, Guillermo Rodriguez Garcia, Wolfram Gloger, Norbert Grotz, - Stefan Gunter, Bill Hale, Patrick Halke, Stefan Hammes, Guillaume Helle, - Harco de Hilster, Cord Hockemeyer, Markus Holzem, Olaf Klein, Leif Jensen, - Bart Jourquin, Guilhem Lavaux, Ron Lee, Jan Lessner, Nicholas Liebmann, - Torsten Liermann, Per Lindqvist, Francesco Montorsi, Thomas Runge, Tatu M\"{a}nnist\"{o}, - Scott Maxwell, Thomas Myers, Oliver Niedung, Ryan Norton, Hernan Otero, - Ian Perrigo, Timothy Peters, Giordano Pezzoli, Harri Pasanen, Thomaso Paoletti, - Garrett Potts, Marcel Rasche, Dino Scaringella, Jobst Schmalenbach, Arthur Seaton, - Paul Shirley, Stein Somers, Petr Smilauer, Neil Smith, Kari Syst\"{a}, George Tasker, - Arthur Tetzlaff-Deas, Jonathan Tonberg, Jyrki Tuomi, Janos Vegh, Andrea Venturoli, + + Yiorgos Adamopoulos, Jamshid Afshar, Alejandro Aguilar-Sierra, AIAI, + Patrick Albert, Karsten Ballueder, Mattia Barbon, Michael Bedward, + Kai Bendorf, Yura Bidus, Keith Gary Boyce, Chris Breeze, Pete Britton, + Ian Brown, C. Buckley, Marco Cavallini, Dmitri Chubraev, Robin Corbet, Cecil Coupe, + Andrew Davison, Gilles Depeyrot, Neil Dudman, Hermann Dunkel, Jos van Eijndhoven, + Tom Felici, Thomas Fettig, Matthew Flatt, Pasquale Foggia, Josep Fortiana, Todd Fries, + Dominic Gallagher, Guillermo Rodriguez Garcia, Wolfram Gloger, Norbert Grotz, + Stefan Gunter, Bill Hale, Patrick Halke, Stefan Hammes, Guillaume Helle, + Harco de Hilster, Cord Hockemeyer, Markus Holzem, Olaf Klein, Leif Jensen, + Bart Jourquin, Guilhem Lavaux, Ron Lee, Jan Lessner, Nicholas Liebmann, + Torsten Liermann, Per Lindqvist, Francesco Montorsi, Thomas Runge, Tatu M\"{a}nnist\"{o}, + Scott Maxwell, Thomas Myers, Oliver Niedung, Ryan Norton, Hernan Otero, + Ian Perrigo, Timothy Peters, Giordano Pezzoli, Harri Pasanen, Thomaso Paoletti, + Garrett Potts, Marcel Rasche, Dino Scaringella, Jobst Schmalenbach, Arthur Seaton, + Paul Shirley, Stein Somers, Petr Smilauer, Neil Smith, Kari Syst\"{a}, George Tasker, + Arthur Tetzlaff-Deas, Jonathan Tonberg, Jyrki Tuomi, Janos Vegh, Andrea Venturoli, David Webster, Otto Wyss, Xiaokun Zhu, Edward Zimmermann. - + Many thanks also to AIAI for being willing to release the original version of wxWidgets into the public domain, and to our patient partners. - + `Graphplace', the basis for the wxGraphLayout library, is copyright Dr. Jos T.J. van Eijndhoven of Eindhoven University of Technology. The code has been used in wxGraphLayout (not in wxWidgets anymore) with his permission. - + We also acknowledge the author of XFIG, the excellent Unix drawing tool, from the source of which we have borrowed some spline drawing code. His copyright is included below. - + {\it XFig2.1 is copyright (c) 1985 by Supoj Sutanthavibul. Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided @@ -235,5 +235,5 @@ written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided ``as is'' without express or implied warranty.} - + */ diff --git a/docs/doxygen/libs.h b/docs/doxygen/libs.h index 3ac4ce1a84..cd761b084f 100644 --- a/docs/doxygen/libs.h +++ b/docs/doxygen/libs.h @@ -14,43 +14,43 @@ wxWidgets can be built either as a single large library (this is called the {\it monolithic build}) or as several smaller libraries ({\it multilib build}). Multilib build is the default. - + wxWidgets library is divided into libraries briefly described below. This diagram show dependencies between them: - + @image html libs.gif - + Please note that arrows indicate the "depends from" relation and that all blue boxes depend from wxBase library (i.e. they are non-GUI libraries), and all green boxes depend from wxCore library (i.e. they are GUI libraries). - + @section wxBase wxBase - + Every wxWidgets application must link against this library. It contains mandatory classes that any wxWidgets code depends on (e.g. \helpref{wxString}{wxstring}) and portability classes that abstract differences between platforms. wxBase can be used to develop console mode applications, it does not require any GUI libraries or running X Window System on Unix. - + @section wxCore wxCore - + Basic GUI classes such as GDI classes or controls are in this library. All wxWidgets GUI applications must link against this library, only console mode applications don't. - + Requires wxBase. - + @section wxAui wxAui - + This contains the Advanced User Interface docking library. - + Requires wxAdvanced, wxHTML, wxXML, wxCore, wxBase. - + @section wxNet wxNet - + Classes for network access: - + \begin{itemize} \item{ wxSocket classes (\helpref{wxSocketClient}{wxsocketclient}, \helpref{wxSocketServer}{wxsocketserver} and related classes) } @@ -62,25 +62,25 @@ \item{ \helpref{wxURL}{wxurl} } \item{ wxInternetFSHandler (a \helpref{wxFileSystem handler}{fs}) } \end{itemize} - + Requires wxBase. - + @section wxRichText wxRichText - + This contains generic rich text control functionality. - + Requires wxAdvanced, wxHTML, wxXML, wxCore, wxBase. - + @section wxXML wxXML - + This library contains simple classes for parsing XML documents. - + Requires wxBase. - + @section wxAdvanced wxAdvanced - + Advanced or rarely used GUI classes: - + \begin{itemize}\itemsep=0pt \item{ \helpref{wxCalendarCtrl}{wxcalendarctrl} } \item{ \helpref{wxGrid classes}{gridoverview} } @@ -94,54 +94,54 @@ \item{ \helpref{wxSashWindow}{wxsashwindow} } \item{ ...others } \end{itemize} - + Requires wxCore and wxBase. - + @section wxMedia wxMedia - + Miscellaneous classes related to multimedia. Currently this library only contains \helpref{wxMediaCtrl}{wxmediactrl} but more classes will be added in the future. - + Requires wxCore and wxBase. - + @section wxGL wxGL - + This library contains \helpref{wxGLCanvas}{wxglcanvas} class for integrating OpenGL library with wxWidgets. Unlike all others, this library is {\em not} part of the monolithic library, it is always built as separate library. - + Requires wxCore and wxBase. - + @section wxHTML wxHTML - + Simple HTML renderer and other \helpref{HTML rendering classes}{wxhtml} are contained in this library, as well as \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}, \helpref{wxBestHelpController}{wxhelpcontroller} and \helpref{wxHtmlListBox}{wxhtmllistbox}. - + Requires wxCore and wxBase. - + @section wxQA wxQA - + This is the library containing extra classes for quality assurance. Currently it only contains \helpref{wxDebugReport}{wxdebugreport} and related classes, but more will be added to it in the future. - + Requires wxXML, wxCore, wxBase. - + @section wxXRC wxXRC - + This library contains \helpref{wxXmlResource}{wxxmlresource} class that provides access to XML resource files in XRC format - + Requires wxAdvanced, wxHTML, wxXML, wxCore, wxBase. - + @section wxSTC wxSTC - + STC (Styled Text Control) is a wrapper around Scintilla, a syntax-highlighting text editor. - + Requires wxCore, wxBase. - + */ diff --git a/docs/doxygen/manual.h b/docs/doxygen/manual.h index 54aa016176..015777e87e 100644 --- a/docs/doxygen/manual.h +++ b/docs/doxygen/manual.h @@ -8,7 +8,7 @@ /*! - + @mainpage wxWidgets 2.9.0: A portable C++ and Python GUI toolkit @author Julian Smart, Robert Roebling, Vadim Zeitlin, Robin Dunn, et al @date February, 2008 @@ -27,7 +27,7 @@ @li @ref topic_page @li @ref platformdetails_page - */ diff --git a/docs/doxygen/overviews/app.h b/docs/doxygen/overviews/app.h index 25f0594076..931fd297e9 100644 --- a/docs/doxygen/overviews/app.h +++ b/docs/doxygen/overviews/app.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page app_overview wxApp overview - + Classes: #wxApp A wxWidgets application does not have a @e main procedure; the equivalent is the #OnInit member defined for a class derived from wxApp. @@ -18,7 +18,7 @@ returns a boolean value which indicates whether processing should continue (@true) or not (@false). You call wxApp::SetTopWindow to let wxWidgets know about the top window. - Note that the program's command line arguments, represented by @e argc + Note that the program's command line arguments, represented by @e argc and @e argv, are available from within wxApp member functions. An application closes by destroying all windows. Because all frames must be destroyed for the application to exit, it is advisable to use parent @@ -27,44 +27,44 @@ is to explicitly delete child frames in the top-level frame's #wxCloseEvent handler. In emergencies the #wxExit function can be called to kill the - application however normally the application shuts down automatically, + application however normally the application shuts down automatically, @ref appshutdown_overview. An example of defining an application follows: - + @code class DerivedApp : public wxApp { public: virtual bool OnInit(); }; - + IMPLEMENT_APP(DerivedApp) - + bool DerivedApp::OnInit() { wxFrame *the_frame = new wxFrame(@NULL, ID_MYFRAME, argv[0]); ... the_frame-Show(@true); SetTopWindow(the_frame); - + return @true; } @endcode - + Note the use of IMPLEMENT_APP(appClass), which allows wxWidgets to dynamically create an instance of the application object at the appropriate point in wxWidgets initialization. Previous versions of wxWidgets used to rely on the creation of a global application object, but this is no longer recommended, because required global initialization may not have been performed at application object construction time. You can also use DECLARE_APP(appClass) in a header file to declare the wxGetApp function which returns - a reference to the application object. Otherwise you can only use the global + a reference to the application object. Otherwise you can only use the global @c wxTheApp pointer which is of type @c wxApp *. - + @ref appshutdown_overview - - + + @section wxappshutdownoverview Application shutdown - + The application normally shuts down when the last of its top level windows is closed. This is normally the expected behaviour and means that it is enough to call #Close() in response to the @c "Exit" menu @@ -72,18 +72,18 @@ desirable wxApp::SetExitOnFrameDelete can be called to change it. Note that starting from wxWidgets 2.3.3 such logic doesn't apply for the windows shown before the program enters the main loop: in - other words, you can safely show a dialog from + other words, you can safely show a dialog from wxApp::OnInit and not be afraid that your application terminates when this dialog -- which is the last top level window for the moment -- is closed. - - Another aspect of the application shutdown is #OnExit + + Another aspect of the application shutdown is #OnExit which is called when the application exits but @e before wxWidgets cleans up its internal structures. You should delete all wxWidgets object that you created by the time OnExit finishes. In particular, do @b not destroy them from application class' destructor! For example, this code may crash: - + @code class MyApp : public wxApp { @@ -92,12 +92,12 @@ ... }; @endcode - - The reason for that is that @c m_helpCtrl is a member object and is - thus destroyed from MyApp destructor. But MyApp object is deleted after - wxWidgets structures that wxCHMHelpController depends on were + + The reason for that is that @c m_helpCtrl is a member object and is + thus destroyed from MyApp destructor. But MyApp object is deleted after + wxWidgets structures that wxCHMHelpController depends on were uninitialized! The solution is to destroy HelpCtrl in @e OnExit: - + @code class MyApp : public wxApp { @@ -105,21 +105,21 @@ wxCHMHelpController *m_helpCtrl; ... }; - + bool MyApp::OnInit() { ... m_helpCtrl = new wxCHMHelpController; ... } - + int MyApp::OnExit() { delete m_helpCtrl; return 0; } @endcode - + */ - - + + diff --git a/docs/doxygen/overviews/arc.h b/docs/doxygen/overviews/arc.h index 02be708864..6d5b162e58 100644 --- a/docs/doxygen/overviews/arc.h +++ b/docs/doxygen/overviews/arc.h @@ -7,54 +7,54 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page arc_overview Archive formats such as zip - + The archive classes handle archive formats such as zip, tar, rar and cab. Currently #wxZip and #wxTar classes are included. For each archive type, there are the following classes (using zip here as an example): - - - - - - + + + + + + #wxZipInputStream - - - - + + + + Input stream - - - - - + + + + + #wxZipOutputStream - - - - + + + + Output stream - - - - - + + + + + #wxZipEntry - - - - + + + + Holds the meta-data for an entry (e.g. filename, timestamp, etc.) - - - - - + + + + + There are also abstract wxArchive classes that can be used to write code that can handle any of the archive types, see '@ref arcgeneric_overview'. @@ -65,42 +65,42 @@ (see '@ref arcnoseek_overview'). @b See also #wxFileSystem - + @ref arccreate_overview @ref arcextract_overview @ref arcmodify_overview @ref arcbyname_overview @ref arcgeneric_overview @ref arcnoseek_overview - - + + @section wxarccreate Creating an archive - + @ref arc_overview Call #PutNextEntry() to create each new entry in the archive, then write the entry's data. Another call to PutNextEntry() closes the current entry and begins the next. For example: - + @code wxFFileOutputStream out(_T("test.zip")); wxZipOutputStream zip(out); wxTextOutputStream txt(zip); wxString sep(wxFileName::GetPathSeparator()); - + zip.PutNextEntry(_T("entry1.txt")); txt _T("Some text for entry1.txt\n"); - + zip.PutNextEntry(_T("subdir") + sep + _T("entry2.txt")); txt _T("Some text for subdir/entry2.txt\n"); @endcode - + The name of each entry can be a full path, which makes it possible to store entries in subdirectories. - - + + @section wxarcextract Extracting an archive - + @ref arc_overview #GetNextEntry() returns a pointer to entry object containing the meta-data for the next entry in the archive @@ -108,13 +108,13 @@ entry's data. Eof() becomes @true after an attempt has been made to read past the end of the entry's data. When there are no more entries, GetNextEntry() returns @NULL and sets Eof(). - + @code auto_ptrwxZipEntry entry; - + wxFFileInputStream in(_T("test.zip")); wxZipInputStream zip(in); - + while (entry.reset(zip.GetNextEntry()), entry.get() != @NULL) { // access meta-data @@ -122,11 +122,11 @@ // read 'zip' to access the entry's data } @endcode - - - + + + @section wxarcmodify Modifying an archive - + @ref arc_overview To modify an existing archive, write a new copy of the archive to a new file, making any necessary changes along the way and transferring any unchanged @@ -141,38 +141,38 @@ archive. #wxTempFileOutputStream can be helpful to do this. For example to delete all entries matching the pattern "*.txt": - + @code auto_ptrwxFFileInputStream in(new wxFFileInputStream(_T("test.zip"))); wxTempFileOutputStream out(_T("test.zip")); - + wxZipInputStream inzip(*in); wxZipOutputStream outzip(out); - + auto_ptrwxZipEntry entry; - + // transfer any meta-data for the archive as a whole (the zip comment // in the case of zip) outzip.CopyArchiveMetaData(inzip); - + // call CopyEntry for each entry except those matching the pattern while (entry.reset(inzip.GetNextEntry()), entry.get() != @NULL) if (!entry-GetName().Matches(_T("*.txt"))) if (!outzip.CopyEntry(entry.release(), inzip)) break; - + // close the input stream by releasing the pointer to it, do this // before closing the output stream so that the file can be replaced in.reset(); - + // you can check for success as follows bool success = inzip.Eof() && outzip.Close() && out.Commit(); @endcode - - - + + + @section wxarcbyname Looking up an archive entry by name - + @ref arc_overview Also see #wxFileSystem for a higher level interface that is more convenient for accessing archive entries by name. @@ -192,43 +192,43 @@ So to avoid ambiguity when searching for an entry matching a local name, it is better to convert the local name to the archive's internal format and search for that: - + @code auto_ptrwxZipEntry entry; - + // convert the local name we are looking for into the internal format wxString name = wxZipEntry::GetInternalName(localname); - + // open the zip wxFFileInputStream in(_T("test.zip")); wxZipInputStream zip(in); - + // call GetNextEntry() until the required internal name is found do { entry.reset(zip.GetNextEntry()); } while (entry.get() != @NULL && entry-GetInternalName() != name); - + if (entry.get() != @NULL) { // read the entry's data... } @endcode - + To access several entries randomly, it is most efficient to transfer the entire catalogue of entries to a container such as a std::map or a #wxHashMap then entries looked up by name can be opened using the #OpenEntry() method. - + @code WX_DECLARE_STRING_HASH_MAP(wxZipEntry*, ZipCatalog); ZipCatalog::iterator it; wxZipEntry *entry; ZipCatalog cat; - + // open the zip wxFFileInputStream in(_T("test.zip")); wxZipInputStream zip(in); - + // load the zip catalog while ((entry = zip.GetNextEntry()) != @NULL) { wxZipEntry*& current = cat[entry-GetInternalName()]; @@ -237,17 +237,17 @@ delete current; current = entry; } - + // open an entry by name if ((it = cat.find(wxZipEntry::GetInternalName(localname))) != cat.end()) { zip.OpenEntry(*it-second); // ... now read entry's data } @endcode - + To open more than one entry simultaneously you need more than one underlying stream on the same archive: - + @code // opening another entry without closing the first requires another // input stream for the same file @@ -256,57 +256,57 @@ if ((it = cat.find(wxZipEntry::GetInternalName(local2))) != cat.end()) zip2.OpenEntry(*it-second); @endcode - - - + + + @section wxarcgeneric Generic archive programming - + @ref arc_overview Also see #wxFileSystem for a higher level interface that can handle archive files in a generic way. The specific archive classes, such as the wxZip classes, inherit from the following abstract classes which can be used to write code that can handle any of the archive types: - - - - - - + + + + + + #wxArchiveInputStream - - - - + + + + Input stream - - - - - + + + + + #wxArchiveOutputStream - - - - + + + + Output stream - - - - - + + + + + #wxArchiveEntry - - - - + + + + Holds the meta-data for an entry (e.g. filename) - - - - - + + + + + In order to able to write generic code it's necessary to be able to create instances of the classes without knowing which archive type is being used. To allow this there is a class factory for each archive type, derived from @@ -314,29 +314,29 @@ the other classes. For example, given @e wxArchiveClassFactory* factory, streams and entries can be created like this: - + @code // create streams without knowing their type auto_ptrwxArchiveInputStream inarc(factory-NewStream(in)); auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out)); - + // create an empty entry object auto_ptrwxArchiveEntry entry(factory-NewEntry()); @endcode - + For the factory itself, the static member wxArchiveClassFactory::Find(). can be used to find a class factory that can handle a given file extension or mime type. For example, given @e filename: - + @code const wxArchiveClassFactory *factory; factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT); - + if (factory) stream = factory-NewStream(new wxFFileInputStream(filename)); @endcode - + @e Find does not give away ownership of the returned pointer, so it does not need to be deleted. There are similar class factories for the filter streams that handle the @@ -344,10 +344,10 @@ These can be found using wxFilterClassFactory::Find(). For example, to list the contents of archive @e filename: - + @code auto_ptrwxInputStream in(new wxFFileInputStream(filename)); - + if (in-IsOk()) { // look for a filter handler, e.g. for '.gz' @@ -358,14 +358,14 @@ // pop the extension, so if it was '.tar.gz' it is now just '.tar' filename = fcf-PopExtension(filename); } - + // look for a archive handler, e.g. for '.zip' or '.tar' const wxArchiveClassFactory *acf; acf = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT); if (acf) { auto_ptrwxArchiveInputStream arc(acf-NewStream(in.release())); auto_ptrwxArchiveEntry entry; - + // list the contents of the archive while ((entry.reset(arc-GetNextEntry())), entry.get() != @NULL) std::wcout entry-GetName().c_str() "\n"; @@ -375,17 +375,17 @@ } } @endcode - - - + + + @section wxarcnoseek Archives on non-seekable streams - + @ref arc_overview In general, handling archives on non-seekable streams is done in the same way as for seekable streams, with a few caveats. The main limitation is that accessing entries randomly using - #OpenEntry() - is not possible, the entries can only be accessed sequentially in the order + #OpenEntry() + is not possible, the entries can only be accessed sequentially in the order they are stored within the archive. For each archive type, there will also be other limitations which will depend on the order the entries' meta-data is stored within the archive. @@ -405,7 +405,7 @@ @b GetNextEntry and the weak reference mechanism Some archive formats do not store all an entry's meta-data before the entry's data (zip is an example). In this case, when reading from a - non-seekable stream, #GetNextEntry() + non-seekable stream, #GetNextEntry() can only return a partially populated #wxArchiveEntry object - not all the fields are set. The input stream then keeps a weak reference to the entry object and @@ -417,38 +417,38 @@ when the worst case must be assumed, you can rely on all the fields of wxArchiveEntry being fully populated when GetNextEntry() returns, with the the following exceptions: - - - - - - + + + + + + #GetSize() - - - - + + + + Guaranteed to be available after the entry has been read to #Eof(), or #CloseEntry() has been called - - - - - + + + + + #IsReadOnly() - - - - + + + + Guaranteed to be available after the end of the archive has been reached, i.e. after GetNextEntry() returns @NULL and Eof() is @true - - - - - + + + + + This mechanism allows #CopyEntry() to always fully preserve entries' meta-data. No matter what order order the meta-data occurs within the archive, the input stream will always @@ -461,30 +461,30 @@ This is the usual way to modify an entry's meta-data, simply set the required field before writing it with #CopyEntry(): - + @code auto_ptrwxArchiveInputStream arc(factory-NewStream(in)); auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out)); auto_ptrwxArchiveEntry entry; - + outarc-CopyArchiveMetaData(*arc); - + while (entry.reset(arc-GetNextEntry()), entry.get() != @NULL) { if (entry-GetName() == from) entry-SetName(to); if (!outarc-CopyEntry(entry.release(), *arc)) break; } - + bool success = arc-Eof() && outarc-Close(); @endcode - + However, for non-seekable streams, this technique cannot be used for fields such as #IsReadOnly(), which are not necessarily set when #GetNextEntry() returns. In this case a #wxArchiveNotifier can be used: - + @code class MyNotifier : public wxArchiveNotifier { @@ -492,36 +492,36 @@ void OnEntryUpdated(wxArchiveEntry& entry) { entry.SetIsReadOnly(@false); } }; @endcode - + The meta-data changes are done in your notifier's #OnEntryUpdated() method, then #SetNotifier() is called before CopyEntry(): - + @code auto_ptrwxArchiveInputStream arc(factory-NewStream(in)); auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out)); auto_ptrwxArchiveEntry entry; MyNotifier notifier; - + outarc-CopyArchiveMetaData(*arc); - + while (entry.reset(arc-GetNextEntry()), entry.get() != @NULL) { entry-SetNotifier(notifier); if (!outarc-CopyEntry(entry.release(), *arc)) break; } - + bool success = arc-Eof() && outarc-Close(); @endcode - + SetNotifier() calls OnEntryUpdated() immediately, then the input stream calls it again whenever it sets more fields in the entry. Since OnEntryUpdated() will be called at least once, this technique always works even when it is not strictly necessary to use it. For example, changing the entry name can be done this way too and it works on seekable streams as well as non-seekable. - + */ - - + + diff --git a/docs/doxygen/overviews/aui.h b/docs/doxygen/overviews/aui.h index e0d90a5794..5f62a04b90 100644 --- a/docs/doxygen/overviews/aui.h +++ b/docs/doxygen/overviews/aui.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page aui_overview wxAUI overview - + Class: #wxAuiManager, #wxAuiPaneInfo wxAUI stands for Advanced User Interface and the wxAUI framework aims to give its user a cutting edge interface for use with the @@ -44,7 +44,7 @@ platforms. Use existing wxWidgets code where possible, such as sizer implementation for frame management. Use classes included in wxCore and wxBase only. Use standard wxWidgets coding conventions. - + */ - - + + diff --git a/docs/doxygen/overviews/backwardcompatibility.h b/docs/doxygen/overviews/backwardcompatibility.h index df594745e5..e9faddb2ea 100644 --- a/docs/doxygen/overviews/backwardcompatibility.h +++ b/docs/doxygen/overviews/backwardcompatibility.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page backwardcompatibility_overview Backward compatibility - + Many of the GUIs and platforms supported by wxWidgets are continuously evolving, and some of the new platforms wxWidgets now supports were quite unimaginable even a few years ago. In this environment wxWidgets must also @@ -22,17 +22,17 @@ @ref sourcecompatibility_overview @ref libbincompatibility_overview @ref appbincompatibility_overview - - + + @section versionnumbering The version numbering scheme - + wxWidgets version numbers can have up to four components, with trailing zeros sometimes omitted: - + @code major.minor.release.sub-release @endcode - + A stable release of wxWidgets will have an even number for @c minor, e.g. @c 2.6.0. Stable, in this context, means that the API is not changing. In truth, some changes are permitted, but only those that are backward compatible. For @@ -54,9 +54,9 @@ incompatibilities. Compatibility is not broken gratuitously however, so many applications will require no changes or only small changes to work with the new version. - + @section sourcecompatibility Source level compatibility - + Later releases from a stable branch are backward compatible with earlier releases from the same branch at the source level. This means that, for example, if you develop your application using @@ -68,90 +68,92 @@ binary compatibility' below. Between minor versions, for example between @c 2.2.x, @c 2.4.x and @c 2.6.x, there will be some incompatibilities. Wherever possible the old way of doing something is kept alongside the new for a time wrapped inside: - + @code #if WXWIN_COMPATIBILITY_2_4 /* deprecated feature */ - ... - #endif - @endcode - - By default the @c WXWIN_COMPATIBILITY@e _X_X macro is set - to 1 for the previous stable branch, for example - in @c 2.6.x @c WXWIN_COMPATIBILITY_2_4 = 1. For the next earlier - stable branch the default is 0, so @c WXWIN_COMPATIBILITY_2_2 = 0 - for @c 2.6.x. Earlier than that, obsolete features are removed. - These macros can be changed in @c setup.h. Or on UNIX-like systems you can - set them using the @c --disable-compat24 and @c --enable-compat22 - options to @c configure. - They can be useful in two ways: - - - Changing @c WXWIN_COMPATIBILITY_2_4 to 0 can be useful to - find uses of deprecated features in your program. - Changing @c WXWIN_COMPATIBILITY_2_2 to 1 can be useful to - compile a program developed using @c 2.2.x that no longer compiles - with @c 2.6.x. - - - A program requiring one of these macros to be 1 will become - incompatible with some future version of wxWidgets, and you should consider - updating it. - - @section libbincompatibility Library binary compatibility - - For some platforms, releases from a stable branch are not only source level - compatible but can also be binary compatible. - Binary compatibility makes it possible to get the maximum benefit from - using shared libraries, also known as dynamic link libraries (DLLs) on - Windows or dynamic shared libraries on OS X. - For example, suppose several applications are installed on a system requiring - wxWidgets @c 2.6.0, @c 2.6.1 and @c 2.6.2. Since @c 2.6.2 is - backward compatible with the earlier versions, it should be enough to - install just wxWidgets @c 2.6.2 shared libraries, and all the applications - should be able to use them. If binary compatibility is not supported, then all - the required versions @c 2.6.0, @c 2.6.1 and @c 2.6.2 must be - installed side by side. - Achieving this, without the user being required to have the source code - and recompile everything, places many extra constraints on the changes - that can be made within the stable branch. So it is not supported for all - platforms, and not for all versions of wxWidgets. To date it has mainly - been supported by wxGTK for UNIX-like platforms. - Another practical consideration is that for binary compatibility to work, - all the applications and libraries must have been compiled with compilers - that are capable of producing compatible code; that is, they must use the - same ABI (Application Binary Interface). Unfortunately most different C++ - compilers do not produce code compatible with each other, and often even - different versions of the same compiler are not compatible. - - @section appbincompatibility Application binary compatibility - - The most important aspect of binary compatibility is that applications - compiled with one version of wxWidgets, e.g. @c 2.6.1, continue to work - with shared libraries of a later binary compatible version, for example @c 2.6.2. - The converse can also be useful however. That is, it can be useful for a - developer using a later version, e.g. @c 2.6.2 to be able to create binary - application packages that will work with all binary compatible versions of - the shared library starting with, for example @c 2.6.0. - To do this the developer must, of course, avoid any features not available - in the earlier versions. However this is not necessarily enough; in some - cases an application compiled with a later version may depend on it even - though the same code would compile fine against an earlier version. - To help with this, a preprocessor symbol @c wxABI_VERSION can be defined - during the compilation of the application (this would usually be done in the - application's makefile or project settings). It should be set to the lowest - version that is being targeted, as a number with two decimal digits for each - component, for example @c wxABI_VERSION=20600 for @c 2.6.0. - Setting @c wxABI_VERSION should prevent the application from implicitly - depending on a later version of wxWidgets, and also disables any new features - in the API, giving a compile time check that the source is compatible with - the versions of wxWidgets being targeted. - Uses of @c wxABI_VERSION are stripped out of the wxWidgets sources when - each new development branch is created. Therefore it is only useful to help - achieve compatibility with earlier versions with the same major - and even minor version numbers. It won't, for example, help you write - code compatible with @c 2.4.x using wxWidgets @c 2.6.x. - - */ - - +... +#endif +@endcode + +By default the @c WXWIN_COMPATIBILITY@e _X_X macro is set + to 1 for the previous stable branch, for example + in @c 2.6.x @c WXWIN_COMPATIBILITY_2_4 = 1. For the next earlier + stable branch the default is 0, so @c WXWIN_COMPATIBILITY_2_2 = 0 + for @c 2.6.x. Earlier than that, obsolete features are removed. + These macros can be changed in @c setup.h. Or on UNIX-like systems you can + set them using the @c --disable-compat24 and @c --enable-compat22 + options to @c configure. + They can be useful in two ways: + + +Changing @c WXWIN_COMPATIBILITY_2_4 to 0 can be useful to +find uses of deprecated features in your program. +Changing @c WXWIN_COMPATIBILITY_2_2 to 1 can be useful to +compile a program developed using @c 2.2.x that no longer compiles +with @c 2.6.x. + + +A program requiring one of these macros to be 1 will become +incompatible with some future version of wxWidgets, and you should consider +updating it. + +@section libbincompatibility Library binary compatibility + +For some platforms, releases from a stable branch are not only source level +compatible but can also be binary compatible. +Binary compatibility makes it possible to get the maximum benefit from +using shared libraries, also known as dynamic link libraries (DLLs) on +Windows or dynamic shared libraries on OS X. +For example, suppose several applications are installed on a system requiring +wxWidgets @c 2.6.0, @c 2.6.1 and @c 2.6.2. Since @c 2.6.2 is +backward compatible with the earlier versions, it should be enough to +install just wxWidgets @c 2.6.2 shared libraries, and all the applications +should be able to use them. If binary compatibility is not supported, then all +the required versions @c 2.6.0, @c 2.6.1 and @c 2.6.2 must be +installed side by side. +Achieving this, without the user being required to have the source code +and recompile everything, places many extra constraints on the changes +that can be made within the stable branch. So it is not supported for all +platforms, and not for all versions of wxWidgets. To date it has mainly + been supported by wxGTK for UNIX-like platforms. + Another practical consideration is that for binary compatibility to work, + all the applications and libraries must have been compiled with compilers + that are capable of producing compatible code; +that is, they must use the +same ABI (Application Binary Interface). Unfortunately most different C++ +compilers do not produce code compatible with each other, and often even + different versions of the same compiler are not compatible. + + @section appbincompatibility Application binary compatibility + + The most important aspect of binary compatibility is that applications + compiled with one version of wxWidgets, e.g. @c 2.6.1, continue to work + with shared libraries of a later binary compatible version, for example @c 2.6.2. + The converse can also be useful however. That is, it can be useful for a + developer using a later version, e.g. @c 2.6.2 to be able to create binary + application packages that will work with all binary compatible versions of + the shared library starting with, for example @c 2.6.0. + To do this the developer must, of course, avoid any features not available + in the earlier versions. However this is not necessarily enough; +in some +cases an application compiled with a later version may depend on it even +though the same code would compile fine against an earlier version. +To help with this, a preprocessor symbol @c wxABI_VERSION can be defined +during the compilation of the application (this would usually be done in the + application's makefile or project settings). It should be set to the lowest + version that is being targeted, as a number with two decimal digits for each + component, for example @c wxABI_VERSION=20600 for @c 2.6.0. + Setting @c wxABI_VERSION should prevent the application from implicitly + depending on a later version of wxWidgets, and also disables any new features + in the API, giving a compile time check that the source is compatible with + the versions of wxWidgets being targeted. + Uses of @c wxABI_VERSION are stripped out of the wxWidgets sources when + each new development branch is created. Therefore it is only useful to help + achieve compatibility with earlier versions with the same major + and even minor version numbers. It won't, for example, help you write + code compatible with @c 2.4.x using wxWidgets @c 2.6.x. + + */ + + diff --git a/docs/doxygen/overviews/bitmap.h b/docs/doxygen/overviews/bitmap.h index c5ad8ae7bb..bdb0034aa9 100644 --- a/docs/doxygen/overviews/bitmap.h +++ b/docs/doxygen/overviews/bitmap.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page bitmap_overview Bitmaps and icons overview - + Classes: #wxBitmap, #wxBitmapHandler, #wxIcon, #wxCursor. The wxBitmap class encapsulates the concept of a platform-dependent bitmap, either monochrome or colour. Platform-specific methods for creating a @@ -24,30 +24,30 @@ All wxWidgets platforms support XPMs for small bitmaps and icons. You may include the XPM inline as below, since it's C code, or you can load it at run-time. - + @code #include "mondrian.xpm" @endcode - + Sometimes you wish to use a .ico resource on Windows, and XPMs on other platforms (for example to take advantage of Windows' support for multiple icon resolutions). A macro, #wxICON, is available which creates an icon using an XPM on the appropriate platform, or an icon resource on Windows. - + @code wxIcon icon(wxICON(mondrian)); - + // Equivalent to: - + #if defined(__WXGTK__) || defined(__WXMOTIF__) wxIcon icon(mondrian_xpm); #endif - + #if defined(__WXMSW__) wxIcon icon("mondrian"); #endif @endcode - + There is also a corresponding #wxBITMAP macro which allows to create the bitmaps in much the same way as #wxICON creates icons. It assumes that bitmaps live in resources under Windows or OS2 and XPM @@ -55,11 +55,11 @@ included before this macro is used, of course, and the name of the bitmap should be the same as the resource name under Windows with @c _xpm suffix). For example: - + @code // an easy and portable way to create a bitmap wxBitmap bmp(wxBITMAP(bmpname)); - + // which is roughly equivalent to the following #if defined(__WXMSW__) || defined(__WXPM__) wxBitmap bmp("bmpname", wxBITMAP_TYPE_RESOURCE); @@ -67,17 +67,17 @@ wxBitmap bmp(bmpname_xpm, wxBITMAP_TYPE_XPM); #endif @endcode - + You should always use wxICON and wxBITMAP macros because they work for any platform (unlike the code above which doesn't deal with wxMac, wxX11, ...) and are more short and clear than versions with @c #ifdefs. Even better, use the same XPMs on all platforms. @ref supportedbitmapformats_overview @ref bitmaphandlers_overview - - + + @section supportedbitmapformats Supported bitmap file formats - + The following lists the formats handled on different platforms. Note that missing or partially-implemented formats are automatically supplemented by the #wxImage to load the data, and then converting @@ -89,79 +89,79 @@ very differently, depending on colour depths and platform. @b wxBitmap Under Windows, wxBitmap may load the following formats: - - + + Windows bitmap resource (wxBITMAP_TYPE_BMP_RESOURCE) Windows bitmap file (wxBITMAP_TYPE_BMP) XPM data and file (wxBITMAP_TYPE_XPM) All formats that are supported by the #wxImage class. - - + + Under wxGTK, wxBitmap may load the following formats: - - + + XPM data and file (wxBITMAP_TYPE_XPM) All formats that are supported by the #wxImage class. - - + + Under wxMotif and wxX11, wxBitmap may load the following formats: - - + + XBM data and file (wxBITMAP_TYPE_XBM) XPM data and file (wxBITMAP_TYPE_XPM) All formats that are supported by the #wxImage class. - - + + @b wxIcon Under Windows, wxIcon may load the following formats: - - + + Windows icon resource (wxBITMAP_TYPE_ICO_RESOURCE) Windows icon file (wxBITMAP_TYPE_ICO) XPM data and file (wxBITMAP_TYPE_XPM) - - + + Under wxGTK, wxIcon may load the following formats: - - + + XPM data and file (wxBITMAP_TYPE_XPM) All formats that are supported by the #wxImage class. - - + + Under wxMotif and wxX11, wxIcon may load the following formats: - - + + XBM data and file (wxBITMAP_TYPE_XBM) XPM data and file (wxBITMAP_TYPE_XPM) All formats that are supported by the #wxImage class. - - + + @b wxCursor Under Windows, wxCursor may load the following formats: - - + + Windows cursor resource (wxBITMAP_TYPE_CUR_RESOURCE) Windows cursor file (wxBITMAP_TYPE_CUR) Windows icon file (wxBITMAP_TYPE_ICO) Windows bitmap file (wxBITMAP_TYPE_BMP) - - + + Under wxGTK, wxCursor may load the following formats (in additional to stock cursors): - - + + None (stock cursors only). - - + + Under wxMotif and wxX11, wxCursor may load the following formats: - - + + XBM data and file (wxBITMAP_TYPE_XBM) - - - + + + @section bitmaphandlers Bitmap format handlers - + To provide extensibility, the functionality for loading and saving bitmap formats is not implemented in the wxBitmap class, but in a number of handler classes, derived from wxBitmapHandler. There is a static list of handlers which wxBitmap @@ -172,7 +172,7 @@ then call the static function wxBitmap::AddHandler. @b Note: bitmap handlers are not implemented on all platforms, and new ones rarely need to be implemented since wxImage can be used for loading most formats, as noted earlier. - + */ - - + + diff --git a/docs/doxygen/overviews/bookctrl.h b/docs/doxygen/overviews/bookctrl.h index ae09664a99..e64942a278 100644 --- a/docs/doxygen/overviews/bookctrl.h +++ b/docs/doxygen/overviews/bookctrl.h @@ -7,167 +7,167 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page bookctrl_overview wxBookCtrl overview - + Classes: #wxNotebook, #wxListbook, #wxChoicebook, #wxTreebook, #wxToolbook #Introduction @ref bestbookctrl_overview - - + + @section wxbookctrlintro Introduction - + A book control is a convenient way of displaying multiple pages of information, displayed one page at a time. wxWidgets has five variants of this control: - - + + #wxNotebook: uses a row of tabs #wxListbook: controlled by a #wxListCtrl #wxChoicebook: controlled by a #wxChoice #wxTreebook: controlled by a #wxTreeCtrl #wxToolbook: controlled by a #wxToolBar - - + + See @ref samplenotebook_overview for an example of wxBookCtrl usage. - + @section wxbestbookctrl Best book - + wxBookCtrl is mapped to the class best suited for a given platform. Currently it provides #wxChoicebook for smartphones equipped with WinCE, and #wxNotebook for all other platforms. The mapping consists of: - - - - - - - + + + + + + + wxBookCtrl - - - - + + + + wxChoicebook or wxNotebook - - - - - + + + + + wxBookCtrlEvent - - - - + + + + wxChoicebookEvent or wxNotebookEvent - - - - - + + + + + wxEVT_COMMAND_BOOKCTRL_PAGE_CHANGED - - - - + + + + wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGED or wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGED - - - - - + + + + + wxEVT_COMMAND_BOOKCTRL_PAGE_CHANGING - - - - + + + + wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGING or wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING - - - - - + + + + + EVT_BOOKCTRL_PAGE_CHANGED(id, fn) - - - - + + + + EVT_CHOICEBOOK_PAGE_CHANGED(id, fn) or EVT_NOTEBOOK_PAGE_CHANGED(id, fn) - - - - - + + + + + EVT_BOOKCTRL_PAGE_CHANGING(id, fn) - - - - + + + + EVT_CHOICEBOOK_PAGE_CHANGING(id, fn) or EVT_NOTEBOOK_PAGE_CHANGING(id, fn) - - - - - + + + + + For orientation of the book controller, use following flags in style: - - - - - - - + + + + + + + @b wxBK_TOP - - - - + + + + controller above pages - - - - - + + + + + @b wxBK_BOTTOM - - - - + + + + controller below pages - - - - - + + + + + @b wxBK_LEFT - - - - + + + + controller on the left - - - - - + + + + + @b wxBK_RIGHT - - - - + + + + controller on the right - - - - - + + + + + @b wxBK_DEFAULT - - - - + + + + native controller placement - + */ - - + + diff --git a/docs/doxygen/overviews/bufferclasses.h b/docs/doxygen/overviews/bufferclasses.h index 3ac33b5351..b1728a2a3e 100644 --- a/docs/doxygen/overviews/bufferclasses.h +++ b/docs/doxygen/overviews/bufferclasses.h @@ -7,23 +7,23 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page bufferclasses_overview Buffer classes overview - + wxWidgets uses two classes of classes for dealing with buffers in memory. The first is one for dealing with character buffers, namely wxCharBuffer for char pointer or multi-byte c strings and wxWCharBuffer for wchar_t pointer or wide character c strings. Secondly, wxWidgets uses, although only rarely currently, wxMemoryBuffer for dealing with raw buffers in memory. @ref cbov_overview - - + + @section wxcbov wxXCharBuffer Overview - + @b General Usage As mentioned, wxCharBuffer and its wide character variant wxWCharBuffer deal with c strings in memory. They have two constructors, one in which you pass the c string you want them to have a copy of, and another where you specify the size of the buffer in memory in characters you want. wxCharBuffer and its variant only contain the c string as a member, so they can be used safely to c functions with variable arguments such as printf. They also contain standard assignment, character access operators and a copy constructor. @b Destruction It should be noted that on destruction wxCharBuffer and its wide character variant delete the c string that hold onto. If you want to get the pointer to the buffer and don't want wxCharBuffer to delete it on destruction, use the member function release to do so. - + */ - - + + diff --git a/docs/doxygen/overviews/commondialogs.h b/docs/doxygen/overviews/commondialogs.h index 1fac61bfb1..29366afc74 100644 --- a/docs/doxygen/overviews/commondialogs.h +++ b/docs/doxygen/overviews/commondialogs.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page commondialogs_overview Common dialogs overview - + Classes: #wxColourDialog, #wxFontDialog, #wxPrintDialog, #wxFileDialog, #wxDirDialog, #wxTextEntryDialog, @@ -36,10 +36,10 @@ @ref messagedialog_overview @ref singlechoicedialog_overview @ref multichoicedialog_overview - - + + @section wxcolourdialogoverview wxColourDialog overview - + Classes: #wxColourDialog, #wxColourData The wxColourDialog presents a colour selector to the user, and returns with colour information. @@ -69,7 +69,7 @@ a grey scale for the custom colours. If the user did not cancel the dialog, the application retrieves the selected colour and uses it to set the background of a window. - + @code wxColourData data; data.SetChooseFull(@true); @@ -78,7 +78,7 @@ wxColour colour(i*16, i*16, i*16); data.SetCustomColour(i, colour); } - + wxColourDialog dialog(this, ); if (dialog.ShowModal() == wxID_OK) { @@ -90,11 +90,11 @@ myWindow-Refresh(); } @endcode - - - + + + @section wxfontdialogoverview wxFontDialog overview - + Classes: #wxFontDialog, #wxFontData The wxFontDialog presents a font selector to the user, and returns with font and colour information. @@ -117,12 +117,12 @@ In the samples/dialogs directory, there is an example of using the wxFontDialog class. The application uses the returned font and colour for drawing text on a canvas. Here is an excerpt: - + @code wxFontData data; data.SetInitialFont(canvasFont); data.SetColour(canvasTextColour); - + wxFontDialog dialog(this, ); if (dialog.ShowModal() == wxID_OK) { @@ -132,19 +132,19 @@ myWindow-Refresh(); } @endcode - - + + @section wxprintdialogoverview wxPrintDialog overview - + Classes: #wxPrintDialog, #wxPrintData This class represents the print and print setup common dialogs. You may obtain a #wxPrinterDC device context from a successfully dismissed print dialog. The samples/printing example shows how to use it: see @ref printing_overview for an excerpt from this example. - + @section wxfiledialogoverview wxFileDialog overview - + Classes: #wxFileDialog Pops up a file selector box. In Windows and GTK2.4+, this is the common file selector dialog. In X, this is a file selector box with somewhat less @@ -163,51 +163,51 @@ ignored if a default name is supplied. The wildcard may be a specification for multiple types of file with a description for each, such as: - + @code "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" @endcode - - + + @section wxdirdialogoverview wxDirDialog overview - + Classes: #wxDirDialog This dialog shows a directory selector dialog, allowing the user to select a single directory. - + @section wxtextentrydialogoverview wxTextEntryDialog overview - + Classes: #wxTextEntryDialog This is a dialog with a text entry field. The value that the user entered is obtained using wxTextEntryDialog::GetValue. - + @section wxpasswordentrydialogoverview wxPasswordEntryDialog overview - + Classes: #wxPasswordEntryDialog This is a dialog with a password entry field. The value that the user entered is obtained using wxTextEntryDialog::GetValue. - + @section wxmessagedialogoverview wxMessageDialog overview - + Classes: #wxMessageDialog This dialog shows a message, plus buttons that can be chosen from OK, Cancel, Yes, and No. Under Windows, an optional icon can be shown, such as an exclamation mark or question mark. The return value of wxMessageDialog::ShowModal indicates which button the user pressed. - + @section wxsinglechoicedialogoverview wxSingleChoiceDialog overview - + Classes: #wxSingleChoiceDialog This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can select one of them. The selection can be obtained from the dialog as an index, a string or client data. - + @section wxmultichoicedialogoverview wxMultiChoiceDialog overview - + Classes: #wxMultiChoiceDialog This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can select one or more of them. - + */ - - + + diff --git a/docs/doxygen/overviews/config.h b/docs/doxygen/overviews/config.h index a5cf5d1888..2a3ab2c93d 100644 --- a/docs/doxygen/overviews/config.h +++ b/docs/doxygen/overviews/config.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page config_overview wxConfig classes overview - + Classes: #wxConfig This overview briefly describes what the config classes are and what they are for. All the details about how to use them may be found in the description of @@ -20,16 +20,16 @@ information. They were especially designed for this usage and, although may probably be used for many other things as well, should be limited to it. It means that this information should be: - - + + Typed, i.e. strings or numbers for the moment. You can not store binary data, for example. Small. For instance, it is not recommended to use the Windows registry for amounts of data more than a couple of kilobytes. Not performance critical, neither from speed nor from a memory consumption point of view. - - + + On the other hand, the features provided make them very useful for storing all kinds of small to medium volumes of hierarchically-organized, heterogeneous data. In short, this is a place where you can conveniently stuff all your data @@ -41,7 +41,7 @@ configuration files. Other (future) implementations of wxConfigBase might also understand GTK resource files or their analogues on the KDE side. In any case, each implementation of wxConfigBase does its best to - make the data look the same way everywhere. Due to limitations of the underlying + make the data look the same way everywhere. Due to limitations of the underlying physical storage, it may not implement 100% of the base class functionality. There are groups of entries and the entries themselves. Each entry contains either a string or a number (or a boolean value; support for other types of data such as dates or @@ -50,9 +50,9 @@ path are the group names, and each name may contain an arbitrary number of entries and subgroups. The path components are @b always separated with a slash, even though some implementations use the backslash internally. Further - details (including how to read/write these entries) may be found in + details (including how to read/write these entries) may be found in the documentation for #wxConfigBase. - + */ - - + + diff --git a/docs/doxygen/overviews/constraints.h b/docs/doxygen/overviews/constraints.h index 13edc09417..73c2a02ca6 100644 --- a/docs/doxygen/overviews/constraints.h +++ b/docs/doxygen/overviews/constraints.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page constraints_overview Constraints overview - + Classes: #wxLayoutConstraints, #wxIndividualLayoutConstraint. @b Note: constraints are now deprecated and you should use #sizers instead. Objects of class wxLayoutConstraint can be associated with a window to define @@ -17,8 +17,8 @@ The class consists of the following eight constraints of class wxIndividualLayoutConstraint, some or all of which should be accessed directly to set the appropriate constraints. - - + + @b left: represents the left hand edge of the window @b right: represents the right hand edge of the window @b top: represents the top edge of the window @@ -27,8 +27,8 @@ @b height: represents the height of the window @b centreX: represents the horizontal centre point of the window @b centreY: represents the vertical centre point of the window - - + + The constraints are initially set to have the relationship wxUnconstrained, which means that their values should be calculated by looking at known constraints. To calculate the position and size of the control, the layout algorithm needs to @@ -39,20 +39,20 @@ dimension will not be changed which is useful for the dialog controls which often have the default size (e.g. the buttons whose size is determined by their label). - The constrains calculation is done in wxWindow::Layout + The constrains calculation is done in wxWindow::Layout function which evaluates constraints. To call it you can either call wxWindow::SetAutoLayout if the parent window is a frame, panel or a dialog to tell default OnSize handlers to call Layout automatically whenever the window size changes, or override OnSize and call - Layout yourself (note that you do have to call + Layout yourself (note that you do have to call #Layout yourself if the parent window is not a frame, panel or dialog). @ref constraintlayoutdetails_overview @ref layoutexamples_overview - - + + @section constraintlayoutdetails Constraint layout: more details - + By default, windows do not have a wxLayoutConstraints object. In this case, much layout must be done explicitly, by performing calculations in OnSize members, except for the case of frames that have exactly one subwindow (not counting toolbar and @@ -83,7 +83,7 @@ an unconstrained @e width may be calculated from the @e left and @e right edges, if both are currently known. For edges and dimensions with user-supplied constraints, these constraints are evaluated if the inputs of the constraint are known. - The algorithm stops when all child edges and dimension are known (success), or + The algorithm stops when all child edges and dimension are known (success), or there are unknown edges or dimensions but there has been no change in this cycle (failure). It then sets all the window positions and sizes according to the values it has found. Because the algorithm is iterative, the order in which constraints are considered is @@ -95,82 +95,82 @@ right border IsSameAs(parent, wxRight) and then create the first one by specifying that it should be LeftOf() the second one than to do in a more natural left-to-right order. - + @section layoutexamples Window layout examples - - + + @section subwindowlayoutexample Example 1: subwindow layout - + This example specifies a panel and a window side by side, with a text subwindow below it. - + @code frame-panel = new wxPanel(frame, -1, wxPoint(0, 0), wxSize(1000, 500), 0); frame-scrollWindow = new MyScrolledWindow(frame, -1, wxPoint(0, 0), wxSize(400, 400), wxRETAINED); frame-text_window = new MyTextWindow(frame, -1, wxPoint(0, 250), wxSize(400, 250)); - + // Set constraints for panel subwindow wxLayoutConstraints *c1 = new wxLayoutConstraints; - + c1-left.SameAs (frame, wxLeft); c1-top.SameAs (frame, wxTop); c1-right.PercentOf (frame, wxWidth, 50); c1-height.PercentOf (frame, wxHeight, 50); - + frame-panel-SetConstraints(c1); - + // Set constraints for scrollWindow subwindow wxLayoutConstraints *c2 = new wxLayoutConstraints; - + c2-left.SameAs (frame-panel, wxRight); c2-top.SameAs (frame, wxTop); c2-right.SameAs (frame, wxRight); c2-height.PercentOf (frame, wxHeight, 50); - + frame-scrollWindow-SetConstraints(c2); - + // Set constraints for text subwindow wxLayoutConstraints *c3 = new wxLayoutConstraints; c3-left.SameAs (frame, wxLeft); c3-top.Below (frame-panel); c3-right.SameAs (frame, wxRight); c3-bottom.SameAs (frame, wxBottom); - + frame-text_window-SetConstraints(c3); @endcode - - + + @section panelitemlayoutexample Example 2: panel item layout - + This example sizes a button width to 80 percent of the panel width, and centres it horizontally. A listbox and multitext item are placed below it. The listbox takes up 40 percent of the panel width, and the multitext item takes up the remainder of the width. Margins of 5 pixels are used. - + @code // Create some panel items wxButton *btn1 = new wxButton(frame-panel, -1, "A button") ; - + wxLayoutConstraints *b1 = new wxLayoutConstraints; b1-centreX.SameAs (frame-panel, wxCentreX); b1-top.SameAs (frame-panel, wxTop, 5); b1-width.PercentOf (frame-panel, wxWidth, 80); b1-height.PercentOf (frame-panel, wxHeight, 10); btn1-SetConstraints(b1); - + wxListBox *list = new wxListBox(frame-panel, -1, "A list", wxPoint(-1, -1), wxSize(200, 100)); - + wxLayoutConstraints *b2 = new wxLayoutConstraints; b2-top.Below (btn1, 5); b2-left.SameAs (frame-panel, wxLeft, 5); b2-width.PercentOf (frame-panel, wxWidth, 40); b2-bottom.SameAs (frame-panel, wxBottom, 5); list-SetConstraints(b2); - + wxTextCtrl *mtext = new wxTextCtrl(frame-panel, -1, "Multiline text", "Some text", wxPoint(-1, -1), wxSize(150, 100), wxTE_MULTILINE); - + wxLayoutConstraints *b3 = new wxLayoutConstraints; b3-top.Below (btn1, 5); b3-left.RightOf (list, 5); @@ -178,7 +178,7 @@ b3-bottom.SameAs (frame-panel, wxBottom, 5); mtext-SetConstraints(b3); @endcode - + */ - - + + diff --git a/docs/doxygen/overviews/container.h b/docs/doxygen/overviews/container.h index 8093991a01..796af3f383 100644 --- a/docs/doxygen/overviews/container.h +++ b/docs/doxygen/overviews/container.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page container_overview Container classes overview - + Classes: #wxListT, #wxArrayT, #wxVectorT wxWidgets uses itself several container classes including doubly-linked lists and dynamic arrays (i.e. arrays which expand automatically when they become @@ -28,7 +28,7 @@ The list classes in wxWidgets are doubly-linked lists which may either own the objects they contain (meaning that the list deletes the object when it is removed from the list or the list itself is destroyed) or just store the - pointers depending on whether you called or not + pointers depending on whether you called or not wxList::DeleteContents method. Dynamic arrays resemble C arrays but with two important differences: they provide run-time range checking in debug builds and they automatically expand @@ -48,7 +48,7 @@ declaration), otherwise destructors of the container elements will not be called! As array classes never delete the items they contain anyhow, there is no WX_DEFINE_ARRAY macro for them. - Examples of usage of these macros may be found in #wxList and + Examples of usage of these macros may be found in #wxList and #wxArray documentation. Finally, wxWidgets predefines several commonly used container classes. wxList is defined for compatibility with previous versions as a list containing @@ -59,7 +59,7 @@ wxArrayString is somewhat special: it is an optimized version of wxArray which uses its knowledge about #wxString reference counting schema. - + */ - - + + diff --git a/docs/doxygen/overviews/dataobject.h b/docs/doxygen/overviews/dataobject.h index e40983245e..78cfe7f8d8 100644 --- a/docs/doxygen/overviews/dataobject.h +++ b/docs/doxygen/overviews/dataobject.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page dataobject_overview wxDataObject overview - + Classes: #wxDataObject, #wxClipboard, #wxDataFormat, @@ -22,7 +22,7 @@ implement both of them using almost the same code - or, in other words, if you implement drag and drop support for your application, you get clipboard support for free and vice versa. - At the heart of both clipboard and drag and drop operations lies the + At the heart of both clipboard and drag and drop operations lies the #wxDataObject class. The objects of this class (or, to be precise, classes derived from it) represent the data which is being carried by the mouse during drag and drop operation or copied to or pasted from the @@ -38,43 +38,43 @@ should do. #The data provider (source) duties #The data receiver (target) duties - - + + @section wxdataobjectsource The data provider (source) duties - - The data provider is responsible for creating a + + The data provider is responsible for creating a #wxDataObject containing the data to be - transferred. Then it should either pass it to the clipboard using - #SetData function or to - #wxDropSource and call + transferred. Then it should either pass it to the clipboard using + #SetData function or to + #wxDropSource and call #DoDragDrop function. The only (but important) difference is that the object for the clipboard transfer must always be created on the heap (i.e. using @c new) and it will be freed by the clipboard when it is no longer needed (indeed, it is not known in advance when, if ever, the data will be pasted from the clipboard). On the - other hand, the object for drag and drop operation must only exist while + other hand, the object for drag and drop operation must only exist while #DoDragDrop executes and may be safely deleted afterwards and so can be created either on heap or on stack (i.e. as a local variable). Another small difference is that in the case of clipboard operation, the application usually knows in advance whether it copies or cuts (i.e. copies and deletes) data - in fact, this usually depends on which menu item the user - chose. But for drag and drop it can only know it after + chose. But for drag and drop it can only know it after #DoDragDrop returns (from its return value). - + @section wxdataobjecttarget The data receiver (target) duties - + To receive (paste in usual terminology) data from the clipboard, you should create a #wxDataObject derived class which supports the - data formats you need and pass it as argument to + data formats you need and pass it as argument to wxClipboard::GetData. If it returns @false, no data in (any of) the supported format(s) is available. If it returns @true, the data has been successfully transferred to wxDataObject. - For drag and drop case, the wxDropTarget::OnData + For drag and drop case, the wxDropTarget::OnData virtual function will be called when a data object is dropped, from which the - data itself may be requested by calling + data itself may be requested by calling wxDropTarget::GetData method which fills the data object. - + */ - - + + diff --git a/docs/doxygen/overviews/datetime.h b/docs/doxygen/overviews/datetime.h index f8ca881dd5..756abb77fc 100644 --- a/docs/doxygen/overviews/datetime.h +++ b/docs/doxygen/overviews/datetime.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page datetime_overview Date and time classes overview - + Classes: #wxDateTime, #wxDateSpan, #wxTimeSpan, #wxCalendarCtrl #Introduction @ref alldatetimeclasses_overview @@ -20,89 +20,89 @@ #Daylight saving time (DST) @ref tdateholidays_overview #Compatibility - - + + @section introductiontowxdatetime Introduction - + wxWidgets provides a set of powerful classes to work with dates and times. Some of the supported features of #wxDateTime class are: - - - - - - - + + + + + + + Wide range - - - - + + + + The range of supported dates goes from about 4714 B.C. to some 480 million years in the future. - - - - - + + + + + Precision - - - - + + + + Not using floating point calculations anywhere ensures that the date calculations don't suffer from rounding errors. - - - - - + + + + + Many features - - - - + + + + Not only all usual calculations with dates are supported, but also more exotic week and year day calculations, work day testing, standard astronomical functions, conversion to and from strings in either strict or free format. - - - - - + + + + + Efficiency - - - - + + + + Objects of wxDateTime are small (8 bytes) and working with them is fast - - - - - - + + + + + + @section alldatetimeclasses All date/time classes at a glance - - There are 3 main classes declared in @c wx/datetime.h: except + + There are 3 main classes declared in @c wx/datetime.h: except #wxDateTime itself which represents an absolute - moment in time, there are also two classes - + moment in time, there are also two classes - #wxTimeSpan and #wxDateSpan - which represent the intervals of time. - There are also helper classes which are used together with wxDateTime: + There are also helper classes which are used together with wxDateTime: #wxDateTimeHolidayAuthority which is used - to determine whether a given date is a holiday or not and + to determine whether a given date is a holiday or not and #wxDateTimeWorkDays which is a derivation of this class for which (only) Saturdays and Sundays are the holidays. See more about these classes in the discussion of the #holidays. Finally, in other parts of this manual you may find mentions of wxDate and wxTime classes. @ref tdatecompatibility_overview are obsolete and superseded by wxDateTime. - + @section wxdatetimecharacteristics wxDateTime characteristics - + #wxDateTime stores the time as a signed number of milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 - however this is not visible to the class users (in particular, dates prior to @@ -116,7 +116,7 @@ change if there is sufficient interest in doing it). Finally, the internal representation is time zone independent (always in GMT) and the time zones only come into play when a date is broken into - year/month/day components. See more about #timezones + year/month/day components. See more about #timezones below. Currently, the only supported calendar is Gregorian one (which is used even for the dates prior to the historic introduction of this calendar which was @@ -124,13 +124,13 @@ region, dependent). Future versions will probably have Julian calendar support as well and support for other calendars (Maya, Hebrew, Chinese...) is not ruled out. - + @section dateandtimespansdifference Difference between wxDateSpan and wxTimeSpan - + While there is only one logical way to represent an absolute moment in the time (and hence only one wxDateTime class), there are at least two methods to describe a time interval. - First, there is the direct and self-explaining way implemented by + First, there is the direct and self-explaining way implemented by #wxTimeSpan: it is just a difference in milliseconds between two moments in time. Adding or subtracting such an interval to wxDateTime is always well-defined and is a fast operation. @@ -139,7 +139,7 @@ that this is not the same as wxTimeSpan of 60*60*24*31 seconds because 'one month later' Feb 15 is Mar 15 and not Mar 17 or Mar 16 (depending on whether the year is leap or not). - This is why there is another class for representing such intervals called + This is why there is another class for representing such intervals called #wxDateSpan. It handles these sort of operations in the most natural way possible, but note that manipulating with intervals of this kind is not always well-defined. Consider, for example, Jan 31 + '1 @@ -153,78 +153,78 @@ also more efficient). However, wxDateSpan may be very useful in situations when you do need to understand what 'in a month' means (of course, it is just @c wxDateTime::Now() + wxDateSpan::Month()). - + @section tdatearithm Date arithmetics - + Many different operations may be performed with the dates, however not all of them make sense. For example, multiplying a date by a number is an invalid operation, even though multiplying either of the time span classes by a number is perfectly valid. Here is what can be done: - - - - - - + + + + + + @b Addition - - - - + + + + a wxTimeSpan or wxDateSpan can be added to wxDateTime resulting in a new wxDateTime object and also 2 objects of the same span class can be added together giving another object of the same class. - - - - - + + + + + @b Subtraction - - - - + + + + the same types of operations as above are allowed and, additionally, a difference between two wxDateTime objects can be taken and this will yield wxTimeSpan. - - - - - + + + + + @b Multiplication - - - - + + + + a wxTimeSpan or wxDateSpan object can be multiplied by an integer number resulting in an object of the same type. - - - - - + + + + + @b Unary minus - - - - + + + + a wxTimeSpan or wxDateSpan object may finally be negated giving an interval of the same magnitude but of opposite time direction. - - - - - + + + + + For all these operations there are corresponding global (overloaded) operators and also member functions which are synonyms for them: Add(), Subtract() and Multiply(). Unary minus as well as composite assignment operations (like +=) are only implemented as members and Neg() is the synonym for unary minus. - + @section tdatetimezones Time zone considerations - + Although the time is always stored internally in GMT, you will usually work in the local time zone. Because of this, all wxDateTime constructors and setters which take the broken down date assume that these values are for the local @@ -240,9 +240,9 @@ In this (rare) case, you are still limited to the local time zone when constructing wxDateTime objects, i.e. there is no way to construct a wxDateTime corresponding to the given date in, say, Pacific Standard Time. - To do it, you will need to call #ToTimezone or + To do it, you will need to call #ToTimezone or #MakeTimezone methods to adjust the date for - the target time zone. There are also special versions of these functions + the target time zone. There are also special versions of these functions #ToUTC and #MakeUTC for the most common case - when the date should be constructed in UTC. You also can just retrieve the value for some time zone without converting the @@ -257,16 +257,16 @@ usually you will just use one of the @ref datetime_overview and let the conversion constructor do the job. I.e. you would just write - + @code wxDateTime dt(...whatever...); printf("The time is %s in local time zone", dt.FormatTime().c_str()); printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str()); @endcode - - + + @section tdatedst Daylight saving time (DST) - + DST (a.k.a. 'summer time') handling is always a delicate task which is better left to the operating system which is supposed to be configured by the administrator to behave correctly. Unfortunately, when doing calculations with @@ -280,18 +280,18 @@ may perfectly well change in the future. The time zone handling #methods use these functions too, so they are subject to the same limitations. - + @section tdateholidays wxDateTime and Holidays - + TODO. - + @section tdatecompatibility Compatibility - + The old classes for date/time manipulations ported from wxWidgets version 1.xx are still included but are reimplemented in terms of wxDateTime. However, using them is strongly discouraged because they have a few quirks/bugs and were not 'Y2K' compatible. - + */ - - + + diff --git a/docs/doxygen/overviews/dc.h b/docs/doxygen/overviews/dc.h index 2949a510ca..bfcbc7275a 100644 --- a/docs/doxygen/overviews/dc.h +++ b/docs/doxygen/overviews/dc.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page dc_overview Device context overview - + Classes: #wxBufferedDC, #wxBufferedPaintDC, #wxDC, #wxPostScriptDC, #wxMetafileDC, #wxMemoryDC, #wxPrinterDC, #wxScreenDC, #wxClientDC, #wxPaintDC, @@ -21,8 +21,8 @@ This is @true of #wxScreenDC, #wxClientDC, #wxPaintDC, and #wxWindowDC. The following describes the differences between these device contexts and when you should use them. - - + + @b wxScreenDC. Use this to paint on the screen, as opposed to an individual window. @b wxClientDC. Use this to paint on the client area of window (the part without borders and other decorations), but do not use it from within an #wxPaintEvent. @@ -30,11 +30,11 @@ within a #wxPaintEvent. @b wxWindowDC. Use this to paint on the whole area of a window, including decorations. This may not be available on non-Windows platforms. - - + + To use a client, paint or window device context, create an object on the stack with the window as argument, for example: - + @code void MyWindow::OnMyCmd(wxCommandEvent& event) { @@ -42,12 +42,12 @@ DrawMyPicture(dc); } @endcode - + Try to write code so it is parameterised by wxDC - if you do this, the same piece of code may write to a number of different devices, by passing a different device context. This doesn't work for everything (for example not all device contexts support bitmap drawing) but will work most of the time. - + */ - - + + diff --git a/docs/doxygen/overviews/debugging.h b/docs/doxygen/overviews/debugging.h index d414791963..3274dc9cba 100644 --- a/docs/doxygen/overviews/debugging.h +++ b/docs/doxygen/overviews/debugging.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page debugging_overview Debugging overview - + Classes, functions and macros: #wxDebugContext, #wxObject, #wxLog, @ref logfunctions_overview, @ref debugmacros_overview Various classes, functions and macros are provided in wxWidgets to help you debug @@ -41,12 +41,12 @@ underwrites (writing to memory in front of the object). If debugging mode is on and the symbols wxUSE_GLOBAL_MEMORY_OPERATORS and wxUSE_DEBUG_NEW_ALWAYS are set to 1 in setup.h, 'new' is defined to be: - - + + @code #define new new(__FILE__,__LINE__) @endcode - + All occurrences of 'new' in wxWidgets and your own application will use the overridden form of the operator with two extra arguments. This means that the debugging output (and error messages reporting memory problems) will tell you what @@ -59,28 +59,28 @@ #wxASSERT is used to pop up an error message box when a condition is not @true. You can also use #wxASSERT_MSG to supply your own helpful error message. For example: - - + + @code void MyClass::MyFunction(wxObject* object) { wxASSERT_MSG( (object != @NULL), "object should not be @NULL in MyFunction!" ); - + ... }; @endcode - - + + The message box allows you to continue execution or abort the program. If you are running the application inside a debugger, you will be able to see exactly where the problem was. @b Logging functions You can use the #wxLogDebug and #wxLogTrace functions to output debugging information in debug mode; it will do nothing for non-debugging code. @ref debugcontext_overview - - + + @section wxdebugcontextoverview wxDebugContext overview - + @ref debugging_overview Class: #wxDebugContext wxDebugContext is a class for performing various debugging and memory tracing @@ -93,27 +93,27 @@ Check to check memory blocks for integrity. Here's an example of use. The SetCheckpoint ensures that only the allocations done after the checkpoint will be dumped. - + @code wxDebugContext::SetCheckpoint(); - + wxDebugContext::SetFile("c:\\temp\\debug.log"); - + wxString *thing = new wxString; - + char *ordinaryNonObject = new char[1000]; - + wxDebugContext::Dump(); wxDebugContext::PrintStatistics(); @endcode - + You can use wxDebugContext if __WXDEBUG__ is defined, or you can use it at any other time (if wxUSE_DEBUG_CONTEXT is set to 1 in setup.h). It is not disabled in non-debug mode because you may not wish to recompile wxWidgets and your entire application just to make use of the error logging facility. Note: wxDebugContext::SetFile has a problem at present, so use the default stream instead. Eventually the logging will be done through the wxLog facilities instead. - + */ - - + + diff --git a/docs/doxygen/overviews/dialog.h b/docs/doxygen/overviews/dialog.h index 5deac7b7ca..17c8e29103 100644 --- a/docs/doxygen/overviews/dialog.h +++ b/docs/doxygen/overviews/dialog.h @@ -7,30 +7,30 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page dialog_overview wxDialog overview - + Classes: #wxDialog, #wxDialogLayoutAdapter A dialog box is similar to a panel, in that it is a window which can be used for placing controls, with the following exceptions: - - + + A surrounding frame is implicitly created. Extra functionality is automatically given to the dialog box, such as tabbing between items (currently Windows only). If the dialog box is @e modal, the calling program is blocked until the dialog box is dismissed. - - + + For a set of dialog convenience functions, including file selection, see @ref dialogfunctions_overview. See also #wxTopLevelWindow and #wxWindow for inherited member functions. Validation of data in controls is covered in @ref validator_overview. @ref autoscrollingdialogs_overview - - + + @section autoscrollingdialogs Automatic scrolling dialogs - + As an ever greater variety of mobile hardware comes to market, it becomes more imperative for wxWidgets applications to adapt to these platforms without putting too much burden on the programmer. One area where wxWidgets can help is in adapting dialogs for the lower resolution screens that inevitably accompany a smaller form factor. wxDialog therefore supplies @@ -44,8 +44,8 @@ standard adapter class wxStandardDialogLayoutAdapter) will make part of the dialog scrolling, leaving standard buttons in a non-scrolling part at the bottom of the dialog. This is done as follows, in wxDialogLayoutAdapter::DoLayoutAdaptation called from within wxDialog::Show or wxDialog::ShowModal: - - + + If wxDialog::GetContentWindow returns a window derived from wxBookCtrlBase, the pages are made scrollable and no other adaptation is done. wxWidgets looks for a #wxStdDialogButtonSizer and uses it for the non-scrolling part. @@ -56,8 +56,8 @@ All the children apart from standard buttons are reparented onto a new #wxScrolledWindow object, using the old top-level sizer for the scrolled window and creating a new top-level sizer to lay out the scrolled window and standard button sizer. - - + + @b Customising scrolling adaptation In addition to switching adaptation on and off globally and per dialog, you can choose how aggressively wxWidgets will search for standard buttons by setting wxDialog::SetLayoutAdaptationLevel. By default, @@ -70,8 +70,8 @@ You can also override wxDialog::CanDoLayoutAdaptation and wxDialog::DoLayoutAdaptation in a class derived from wxDialog. @b Situations where automatic scrolling adaptation may fail Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof, and may fail in the following situations. - - + + The dialog doesn't use sizers. The dialog implementation makes assumptions about the window hierarchy, for example getting the parent of a control and casting to the dialog class. The dialog does custom painting and/or event handling not handled by the scrolled window. If this problem can be solved globally, @@ -79,11 +79,11 @@ The dialog has unusual layout, for example a vertical sizer containing a mixture of standard buttons and other controls. The dialog makes assumptions about the sizer hierarchy, for example to show or hide children of the top-level sizer. However, the original sizer hierarchy will still hold until Show or ShowModal is called. - - + + You can help make sure that your dialogs will continue to function after adaptation by: - - + + avoiding the above situations and assumptions; using #wxStdDialogButtonSizer; only making assumptions about hierarchy immediately after the dialog is created; @@ -91,13 +91,13 @@ for the purposes of manipulating child sizers and windows; overriding wxDialog::GetContentWindow to return a book control if your dialog implements pages: wxWidgets will then only make the pages scrollable. - - + + @b wxPropertySheetDialog and wxWizard Adaptation for wxPropertySheetDialog is always done by simply making the pages scrollable, since wxDialog::GetContentWindow returns the dialog's book control and this is handled by the standard layout adapter. wxWizard uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions rather than the global adapter: again, only the wizard pages are made scrollable. - + */ - - + + diff --git a/docs/doxygen/overviews/dnd.h b/docs/doxygen/overviews/dnd.h index fc9356a8c0..d60b9a9621 100644 --- a/docs/doxygen/overviews/dnd.h +++ b/docs/doxygen/overviews/dnd.h @@ -7,14 +7,14 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page dnd_overview Drag and drop overview - - Classes: #wxDataObject, - #wxTextDataObject, - #wxDropSource, - #wxDropTarget, - #wxTextDropTarget, + + Classes: #wxDataObject, + #wxTextDataObject, + #wxDropSource, + #wxDropTarget, + #wxTextDropTarget, #wxFileDropTarget Note that wxUSE_DRAG_AND_DROP must be defined in setup.h in order to use drag and drop in wxWidgets. @@ -27,25 +27,25 @@ class. To be a @e drag source, i.e. to provide the data which may be dragged by the user elsewhere, you should implement the following steps: - - + + @b Preparation: First of all, a data object must be created and initialized with the data you wish to drag. For example: - + @code wxTextDataObject my_data("This text will be dragged."); @endcode - + @b Drag start: To start the dragging process (typically in response to a mouse click) you must call wxDropSource::DoDragDrop like this: - + @code wxDropSource dragSource( this ); - dragSource.SetData( my_data ); - wxDragResult result = dragSource.DoDragDrop( TRUE ); + dragSource.SetData( my_data ); + wxDragResult result = dragSource.DoDragDrop( TRUE ); @endcode - + @b Dragging: The call to DoDragDrop() blocks the program until the user releases the mouse button (unless you override the #GiveFeedback function to do something special). When the mouse moves in a window of a program which understands the @@ -54,42 +54,44 @@ are called - see below. @b Processing the result: DoDragDrop() returns an @e effect code which is one of the values of @c wxDragResult enum (explained #here): - + @code switch (result) - { - case wxDragCopy: /* copy the data */ break; - case wxDragMove: /* move the data */ break; - default: /* do nothing */ break; - } - @endcode - - - - To be a @e drop target, i.e. to receive the data dropped by the user you should - follow the instructions below: - - - @b Initialization: For a window to be a drop target, it needs to have - an associated #wxDropTarget object. Normally, you will - call wxWindow::SetDropTarget during window - creation associating your drop target with it. You must derive a class from - wxDropTarget and override its pure virtual methods. Alternatively, you may - derive from #wxTextDropTarget or - #wxFileDropTarget and override their OnDropText() - or OnDropFiles() method. - @b Drop: When the user releases the mouse over a window, wxWidgets - asks the associated wxDropTarget object if it accepts the data. For this, - a #wxDataObject must be associated with the drop target - and this data object will be responsible for the format negotiation between - the drag source and the drop target. If all goes well, then #OnData - will get called and the wxDataObject belonging to the drop target can get - filled with data. - @b The end: After processing the data, DoDragDrop() returns either - wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift - and Alt at the moment of the drop. There is currently no way for the drop - target to change this return code. - - */ - - + { + case wxDragCopy: /* copy the data */ break; +case wxDragMove: /* move the data */ +break; +default: /* do nothing */ +break; +} +@endcode + + + +To be a @e drop target, i.e. to receive the data dropped by the user you should +follow the instructions below: + + +@b Initialization: For a window to be a drop target, it needs to have +an associated #wxDropTarget object. Normally, you will +call wxWindow::SetDropTarget during window +creation associating your drop target with it. You must derive a class from + wxDropTarget and override its pure virtual methods. Alternatively, you may + derive from #wxTextDropTarget or +#wxFileDropTarget and override their OnDropText() + or OnDropFiles() method. + @b Drop: When the user releases the mouse over a window, wxWidgets + asks the associated wxDropTarget object if it accepts the data. For this, + a #wxDataObject must be associated with the drop target + and this data object will be responsible for the format negotiation between + the drag source and the drop target. If all goes well, then #OnData + will get called and the wxDataObject belonging to the drop target can get + filled with data. + @b The end: After processing the data, DoDragDrop() returns either + wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift + and Alt at the moment of the drop. There is currently no way for the drop + target to change this return code. + + */ + + diff --git a/docs/doxygen/overviews/docview.h b/docs/doxygen/overviews/docview.h index bc47c79a59..dd35e477bc 100644 --- a/docs/doxygen/overviews/docview.h +++ b/docs/doxygen/overviews/docview.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page docview_overview Document/view overview - + Classes: #wxDocument, #wxView, #wxDocTemplate, #wxDocManager, #wxDocParentFrame, #wxDocChildFrame, #wxDocMDIParentFrame, #wxDocMDIChildFrame, @@ -29,8 +29,8 @@ The framework is highly modular, allowing overriding and replacement of functionality and objects to achieve more than the default behaviour. These are the overall steps involved in creating an application based on the document/view framework: - - + + Define your own document and view classes, overriding a minimal set of member functions e.g. for input/output, drawing and initialization. Define any subwindows @@ -45,37 +45,37 @@ Construct a single wxDocManager instance at the beginning of your wxApp::OnInit, and then as many wxDocTemplate instances as necessary to define relationships between documents and views. For a simple application, there will be just one wxDocTemplate. - - + + If you wish to implement Undo/Redo, you need to derive your own class(es) from wxCommand and use wxCommandProcessor::Submit instead of directly executing code. The framework will take care of calling Undo and Do functions as appropriate, so long as the wxID_UNDO and wxID_REDO menu items are defined in the view menu. Here are a few examples of the tailoring you can do to go beyond the default framework behaviour: - - + + Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy, or a command history editor. Override wxView::OnCreatePrintout to create an instance of a derived #wxPrintout class, to provide multi-page document facilities. Override wxDocManager::SelectDocumentPath to provide a different file selector. Limit the maximum number of open documents and the maximum number of undo commands. - - + + Note that to activate framework functionality, you need to use some or all of the wxWidgets @ref predefinedids_overview in your menus. @b wxPerl note: The document/view framework is available in wxPerl. To use it, you will need the following statements in your application code: - - - + + + @code use Wx::DocView; use Wx ':docview'; # import constants (optional) @endcode - - + + @ref document_overview @ref view_overview @ref doctemplate_overview @@ -84,10 +84,10 @@ @ref commandprocessor_overview @ref filehistory_overview @ref predefinedids_overview - - + + @section wxdocumentoverview wxDocument overview - + @ref docview_overview Class: #wxDocument The wxDocument class can be used to model an application's file-based @@ -117,9 +117,9 @@ If you do not wish to use the wxWidgets method of creating document objects dynamically, you must override wxDocTemplate::CreateDocument to return an instance of the appropriate class. - + @section wxviewoverview wxView overview - + @ref docview_overview Class: #wxView The wxView class can be used to model the viewing and editing component of @@ -138,9 +138,9 @@ If you do not wish to use the wxWidgets method of creating view objects dynamically, you must override wxDocTemplate::CreateView to return an instance of the appropriate class. - + @section wxdoctemplateoverview wxDocTemplate overview - + @ref docview_overview Class: #wxDocTemplate The wxDocTemplate class is used to model the relationship between a @@ -176,9 +176,9 @@ objects dynamically, you must override wxDocTemplate::CreateDocument and wxDocTemplate::CreateView to return instances of the appropriate class. @e NOTE: the document template has nothing to do with the C++ template construct. - + @section wxdocmanageroverview wxDocManager overview - + @ref docview_overview Class: #wxDocManager The wxDocManager class is part of the document/view framework supported by wxWidgets, @@ -192,9 +192,9 @@ before any documents, views or templates are manipulated. There may be multiple wxDocManager instances in an application. See the example application in @c samples/docview. - + @section wxcommandoverview wxCommand overview - + @ref docview_overview Classes: #wxCommand, #wxCommandProcessor wxCommand is a base class for modelling an application command, @@ -214,17 +214,17 @@ and replays commands. An application can derive a new class for every command, or, more likely, use one class parameterized with an integer or string command identifier. - + @section wxcommandprocessoroverview wxCommandProcessor overview - + @ref docview_overview Classes: #wxCommandProcessor, #wxCommand wxCommandProcessor is a class that maintains a history of wxCommand instances, with undo/redo functionality built-in. Derive a new class from this if you want different behaviour. - + @section wxfilehistoryoverview wxFileHistory overview - + @ref docview_overview Classes: #wxFileHistory, #wxDocManager wxFileHistory encapsulates functionality to record the last few files visited, and @@ -245,19 +245,19 @@ @c wxID_FILE1 to @c wxID_FILE9. In order to respond to a file load command from one of these identifiers, you need to handle them using an event handler, for example: - - + + @code BEGIN_EVENT_TABLE(wxDocParentFrame, wxFrame) EVT_MENU(wxID_EXIT, wxDocParentFrame::OnExit) EVT_MENU_RANGE(wxID_FILE1, wxID_FILE9, wxDocParentFrame::OnMRUFile) END_EVENT_TABLE() - + void wxDocParentFrame::OnExit(wxCommandEvent& WXUNUSED(event)) { Close(); } - + void wxDocParentFrame::OnMRUFile(wxCommandEvent& event) { wxString f(m_docManager-GetHistoryFile(event.GetId() - wxID_FILE1)); @@ -265,16 +265,16 @@ (void)m_docManager-CreateDocument(f, wxDOC_SILENT); } @endcode - - - + + + @section predefinedids wxWidgets predefined command identifiers - + To allow communication between the application's menus and the document/view framework, several command identifiers are predefined for you to use in menus. - - + + wxID_OPEN (5000) wxID_CLOSE (5001) wxID_NEW (5002) @@ -288,7 +288,7 @@ wxID_PRINT (5010) wxID_PRINT_SETUP (5011) wxID_PREVIEW (5012) - + */ - - + + diff --git a/docs/doxygen/overviews/envvars.h b/docs/doxygen/overviews/envvars.h index 98c9f65acf..33d44ab047 100644 --- a/docs/doxygen/overviews/envvars.h +++ b/docs/doxygen/overviews/envvars.h @@ -7,36 +7,36 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page envvars_overview Environment variables - + This section describes all environment variables that affect execution of wxWidgets programs. - - - - - + + + + + @c WXTRACE - - - - + + + + (Debug build only.) This variable can be set to a comma-separated list of trace masks used in #wxLogTrace calls; wxLog::AddTraceMask is called for every mask in the list during wxWidgets initialization. - - - - - + + + + + @c WXPREFIX - - - - + + + + (Unix only.) Overrides installation prefix. Normally, the prefix is hard-coded and is the same as the value passed to @c configure via @@ -44,32 +44,32 @@ @c /usr/local or @c /usr). You can set WXPREFIX if you are for example distributing a binary version of an application and you don't know in advance where it will be installed. - - - - - + + + + + @c WXMODE - - - - + + + + (wxMGL only.) Sets MGL video mode. The value must be in form @e widthx@e height-@e depth. The default is @c 640x480-16. - - - - - + + + + + @c WXSTDERR - - - - + + + + (wxMGL only.) Redirects stderr output to a file. - + */ - - + + diff --git a/docs/doxygen/overviews/eventhandling.h b/docs/doxygen/overviews/eventhandling.h index eada100791..91213416cf 100644 --- a/docs/doxygen/overviews/eventhandling.h +++ b/docs/doxygen/overviews/eventhandling.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page eventhandling_overview Event handling overview - + Classes: #wxEvtHandler, #wxWindow, #wxEvent #Introduction @ref eventprocessing_overview @@ -18,10 +18,10 @@ @ref windowids_overview @ref eventmacros_overview @ref customevents_overview - - + + @section eventintroduction Introduction - + Before version 2.0 of wxWidgets, events were handled by the application either by supplying callback functions, or by overriding virtual member functions such as @b OnSize. @@ -31,7 +31,7 @@ they are all similar in form: they take a single wxEvent-derived argument, and have a void return type. Here's an example of an event table. - + @code BEGIN_EVENT_TABLE(MyFrame, wxFrame) EVT_MENU (wxID_EXIT, MyFrame::OnExit) @@ -40,7 +40,7 @@ EVT_BUTTON (BUTTON1, MyFrame::OnButton1) END_EVENT_TABLE() @endcode - + The first two entries map menu commands to two different member functions. The EVT_SIZE macro doesn't need a window identifier, since normally you are only interested in the current window's size events. @@ -55,16 +55,16 @@ handler ignores that the functions are virtual, i.e. overriding a virtual member function in a derived class will not have any effect. These member functions take an event argument, and the class of event differs according to - the type of event and the class of the originating window. For size events, + the type of event and the class of the originating window. For size events, #wxSizeEvent is used. For menu commands and most - control commands (such as button presses), + control commands (such as button presses), #wxCommandEvent is used. When controls get more - complicated, then specific event classes are used, such as - #wxTreeEvent for events from + complicated, then specific event classes are used, such as + #wxTreeEvent for events from #wxTreeCtrl windows. As well as the event table in the implementation file, there must also be a DECLARE_EVENT_TABLE macro somewhere in the class declaration. For example: - + @code class MyFrame : public wxFrame { @@ -72,15 +72,15 @@ ... void OnExit(wxCommandEvent& event); void OnSize(wxSizeEvent& event); - + protected: int m_count; ... - + DECLARE_EVENT_TABLE() }; @endcode - + Note that this macro may occur in any section of the class (public, protected or private) but that it is probably better to insert it at the end, as shown, because this macro implicitly changes the access to protected which may be @@ -89,11 +89,11 @@ tables you may also use wxEvtHandler::Connect to connect the events to the handlers dynamically, during run-time. See the @ref sampleevent_overview for an example of doing it. - - + + @section eventprocessing How events are processed - - When an event is received from the windowing system, wxWidgets calls + + When an event is received from the windowing system, wxWidgets calls wxEvtHandler::ProcessEvent on the first event handler object belonging to the window generating the event. It may be noted that wxWidgets' event processing system implements something @@ -111,7 +111,7 @@ you should instead call #Skip. In practice, this would look like this if the derived text control only accepts 'a' to 'z' and 'A' to 'Z': - + @code void MyTextCtrl::OnChar(wxKeyEvent& event) { @@ -120,23 +120,23 @@ // key code is within legal range. we call event.Skip() so the // event can be processed either in the base wxWidgets class // or the native control. - + event.Skip(); } else { // illegal key hit. we don't call event.Skip() so the // event is not processed anywhere else. - + wxBell(); } } @endcode - - + + The normal order of event table searching by ProcessEvent is as follows: - - + + If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled) the function skips to step (6). If the object is a wxWindow, @b ProcessEvent is recursively called on the window's @@ -150,14 +150,14 @@ wxCommandEvent based events are set to propagate), @b ProcessEvent is recursively applied to the parent window's event handler. If this returns @true, the function exits. Finally, @b ProcessEvent is called on the wxApp object. - - + + @b Pay close attention to Step 5. People often overlook or get confused by this powerful feature of the wxWidgets event processing - system. To put it a different way, events set to propagate + system. To put it a different way, events set to propagate (@ref eventshouldpropagate_overview) (most likely derived either directly or indirectly from wxCommandEvent) - will travel up the containment hierarchy from child to parent until the + will travel up the containment hierarchy from child to parent until the maximal propagation level is reached or an event handler is found that doesn't call #event.Skip(). Finally, there is another additional complication (which, in fact, simplifies @@ -172,8 +172,8 @@ may be very difficult, if not impossible, to track down all the dialogs which may be popped up in a complex program (remember that some are created automatically by wxWidgets). If you need to specify a different behaviour for - some reason, you can use - #SetExtraStyle(wxWS_EX_BLOCK_EVENTS) + some reason, you can use + #SetExtraStyle(wxWS_EX_BLOCK_EVENTS) explicitly to prevent the events from being propagated beyond the given window or unset this flag for the dialogs which have it on by default. Typically events that deal with a window as a window (size, motion, @@ -185,331 +185,331 @@ Note that your application may wish to override ProcessEvent to redirect processing of events. This is done in the document/view framework, for example, to allow event handlers to be defined in the document or view. To test for command events (which will probably - be the only events you wish to redirect), you may use - wxEvent::IsCommandEvent for efficiency, + be the only events you wish to redirect), you may use + wxEvent::IsCommandEvent for efficiency, instead of using the slower run-time type system. As mentioned above, only command events are recursively applied to the parents event handler in the library itself. As this quite often causes confusion for users, here is a list of system events which will NOT get sent to the parent's event handler: - - - - - - + + + + + + #wxEvent - - - - + + + + The event base class - - - - - + + + + + #wxActivateEvent - - - - + + + + A window or application activation event - - - - - + + + + + #wxCloseEvent - - - - + + + + A close window or end session event - - - - - + + + + + #wxEraseEvent - - - - + + + + An erase background event - - - - - + + + + + #wxFocusEvent - - - - + + + + A window focus event - - - - - + + + + + #wxKeyEvent - - - - + + + + A keypress event - - - - - + + + + + #wxIdleEvent - - - - + + + + An idle event - - - - - + + + + + #wxInitDialogEvent - - - - + + + + A dialog initialisation event - - - - - + + + + + #wxJoystickEvent - - - - + + + + A joystick event - - - - - + + + + + #wxMenuEvent - - - - + + + + A menu event - - - - - + + + + + #wxMouseEvent - - - - + + + + A mouse event - - - - - + + + + + #wxMoveEvent - - - - + + + + A move event - - - - - + + + + + #wxPaintEvent - - - - + + + + A paint event - - - - - + + + + + #wxQueryLayoutInfoEvent - - - - + + + + Used to query layout information - - - - - + + + + + #wxSetCursorEvent - - - - + + + + Used for special cursor processing based on current mouse position - - - - - + + + + + #wxSizeEvent - - - - + + + + A size event - - - - - + + + + + #wxScrollWinEvent - - - - + + + + A scroll event sent by a scrolled window (not a scroll bar) - - - - - + + + + + #wxSysColourChangedEvent - - - - + + + + A system colour change event - - - - - + + + + + In some cases, it might be desired by the programmer to get a certain number of system events in a parent window, for example all key events sent to, but not used by, the native controls in a dialog. In this case, a special event handler will have to be written that will override ProcessEvent() in order to pass all events (or any selection of them) to the parent window. - - + + @section progevent Events generated by the user vs programmatically generated events - + While generically #wxEvents can be generated both by user actions (e.g. resize of a #wxWindow) and by calls to functions (e.g. wxWindow::SetSize), wxWidgets controls normally send #wxCommandEvent-derived events only for the user-generated events. The only @b exceptions to this rule are: - - - - - - + + + + + + wxNotebook::AddPage - - - - + + + + No event-free alternatives - - - - - + + + + + wxNotebook::AdvanceSelection - - - - + + + + No event-free alternatives - - - - - + + + + + wxNotebook::DeletePage - - - - + + + + No event-free alternatives - - - - - + + + + + wxNotebook::SetSelection - - - - + + + + Use wxNotebook::ChangeSelection instead, as wxNotebook::SetSelection is deprecated - - - - - + + + + + wxTreeCtrl::Delete - - - - + + + + No event-free alternatives - - - - - + + + + + wxTreeCtrl::DeleteAllItems - - - - + + + + No event-free alternatives - - - - - + + + + + wxTreeCtrl::EditLabel - - - - - No event-free alternatives - - - - - - All #wxTextCtrl methods - - - - + + + + + No event-free alternatives + + + + + + All #wxTextCtrl methods + + + + wxTextCtrl::ChangeValue can be used instead of wxTextCtrl::SetValue but the other functions, - such as #Replace or #WriteText + such as #Replace or #WriteText don't have event-free equivalents - - - - - - - + + + + + + + @section pluggablehandlers Pluggable event handlers - + In fact, you don't have to derive a new class from a window class if you don't want to. You can derive a new class from wxEvtHandler instead, defining the appropriate event table, and then call @@ -535,9 +535,9 @@ the original event handler. Use PushEventHandler/PopEventHandler to form a chain of event handlers, where each handler processes a different range of events independently from the other handlers. - + @section windowids Window identifiers - + Window identifiers are integers, and are used to uniquely determine window identity in the event system (though you can use it for other purposes). In fact, identifiers do not need to be unique @@ -549,7 +549,7 @@ generated for you automatically by wxWidgets. This is useful when you don't care about the exact identifier either because you're not going to process the events from the control being created at all or because you process the events - from all controls in one place (in which case you should specify @c wxID_ANY + from all controls in one place (in which case you should specify @c wxID_ANY in the event table or wxEvtHandler::Connect call as well. The automatically generated identifiers are always negative and so will never conflict with the user-specified identifiers which must be always @@ -557,12 +557,12 @@ The following standard identifiers are supplied. You can use wxID_HIGHEST to determine the number above which it is safe to define your own identifiers. Or, you can use identifiers below wxID_LOWEST. - + @code #define wxID_ANY -1 - + #define wxID_LOWEST 4999 - + #define wxID_OPEN 5000 #define wxID_CLOSE 5001 #define wxID_NEW 5002 @@ -581,7 +581,7 @@ #define wxID_HELP_COMMANDS 5015 #define wxID_HELP_PROCEDURES 5016 #define wxID_HELP_CONTEXT 5017 - + #define wxID_CUT 5030 #define wxID_COPY 5031 #define wxID_PASTE 5032 @@ -593,7 +593,7 @@ #define wxID_REPLACE 5038 #define wxID_REPLACE_ALL 5039 #define wxID_PROPERTIES 5040 - + #define wxID_VIEW_DETAILS 5041 #define wxID_VIEW_LARGEICONS 5042 #define wxID_VIEW_SMALLICONS 5043 @@ -602,7 +602,7 @@ #define wxID_VIEW_SORTNAME 5046 #define wxID_VIEW_SORTSIZE 5047 #define wxID_VIEW_SORTTYPE 5048 - + #define wxID_FILE1 5050 #define wxID_FILE2 5051 #define wxID_FILE3 5052 @@ -612,275 +612,275 @@ #define wxID_FILE7 5056 #define wxID_FILE8 5057 #define wxID_FILE9 5058 - + #define wxID_OK 5100 #define wxID_CANCEL 5101 #define wxID_APPLY 5102 #define wxID_YES 5103 #define wxID_NO 5104 #define wxID_STATIC 5105 - + #define wxID_HIGHEST 5999 @endcode - - + + @section eventmacros Event macros summary - + @b Macros listed by event class The documentation for specific event macros is organised by event class. Please refer to these sections for details. - - - - - - + + + + + + #wxActivateEvent - - - - + + + + The EVT_ACTIVATE and EVT_ACTIVATE_APP macros intercept activation and deactivation events. - - - - - + + + + + #wxCommandEvent - - - - + + + + A range of commonly-used control events. - - - - - + + + + + #wxCloseEvent - - - - + + + + The EVT_CLOSE macro handles window closure called via wxWindow::Close. - - - - - + + + + + #wxDropFilesEvent - - - - + + + + The EVT_DROP_FILES macros handles file drop events. - - - - - + + + + + #wxEraseEvent - - - - + + + + The EVT_ERASE_BACKGROUND macro is used to handle window erase requests. - - - - - + + + + + #wxFocusEvent - - - - + + + + The EVT_SET_FOCUS and EVT_KILL_FOCUS macros are used to handle keyboard focus events. - - - - - + + + + + #wxKeyEvent - - - - + + + + EVT_CHAR, EVT_KEY_DOWN and EVT_KEY_UP macros handle keyboard input for any window. - - - - - + + + + + #wxIdleEvent - - - - + + + + The EVT_IDLE macro handle application idle events (to process background tasks, for example). - - - - - + + + + + #wxInitDialogEvent - - - - + + + + The EVT_INIT_DIALOG macro is used to handle dialog initialisation. - - - - - + + + + + #wxListEvent - - - - + + + + These macros handle #wxListCtrl events. - - - - - + + + + + #wxMenuEvent - - - - + + + + These macros handle special menu events (not menu commands). - - - - - + + + + + #wxMouseEvent - - - - + + + + Mouse event macros can handle either individual mouse events or all mouse events. - - - - - + + + + + #wxMoveEvent - - - - + + + + The EVT_MOVE macro is used to handle a window move. - - - - - + + + + + #wxPaintEvent - - - - + + + + The EVT_PAINT macro is used to handle window paint requests. - - - - - + + + + + #wxScrollEvent - - - - - These macros are used to handle scroll events from + + + + + These macros are used to handle scroll events from #wxScrollBar, #wxSlider,and #wxSpinButton. - - - - - + + + + + #wxSetCursorEvent - - - - + + + + The EVT_SET_CURSOR macro is used for special cursor processing. - - - - - + + + + + #wxSizeEvent - - - - + + + + The EVT_SIZE macro is used to handle a window resize. - - - - - + + + + + #wxSplitterEvent - - - - + + + + The EVT_SPLITTER_SASH_POS_CHANGED, EVT_SPLITTER_UNSPLIT and EVT_SPLITTER_DCLICK macros are used to handle the various splitter window events. - - - - - + + + + + #wxSysColourChangedEvent - - - - + + + + The EVT_SYS_COLOUR_CHANGED macro is used to handle events informing the application that the user has changed the system colours (Windows only). - - - - - + + + + + #wxTreeEvent - - - - + + + + These macros handle #wxTreeCtrl events. - - - - - + + + + + #wxUpdateUIEvent - - - - + + + + The EVT_UPDATE_UI macro is used to handle user interface update pseudo-events, which are generated to give the application the chance to update the visual state of menus, toolbars and controls. - - - - - - + + + + + + @section customevents Custom event summary - + @b General approach Since version 2.2.x of wxWidgets, each event type is identified by ID which is given to the event type @e at runtime which makes it possible to add @@ -889,21 +889,21 @@ event type ID is stored in a struct of type @b const wxEventType. In order to define a new event type, there are principally two choices. One is to define a entirely new event class (typically deriving from - #wxEvent or #wxCommandEvent. + #wxEvent or #wxCommandEvent. The other is to use the existing event classes and give them an new event type. You'll have to define and declare a new event type using either way, and this is done using the following macros: - + @code // in the header of the source file BEGIN_DECLARE_EVENT_TYPES() DECLARE_EVENT_TYPE(name, value) END_DECLARE_EVENT_TYPES() - + // in the implementation DEFINE_EVENT_TYPE(name) @endcode - + You can ignore the @e value parameter of the DECLARE_EVENT_TYPE macro since it is used only for backwards compatibility with wxWidgets 2.0.x based applications where you have to give the event type ID an explicit value. @@ -916,29 +916,29 @@ has the advantage that you won't have to define a new wxEvent::Clone() method for posting events between threads etc. This could look like this in your code: - + @code DECLARE_EVENT_TYPE(wxEVT_MY_EVENT, -1) - + DEFINE_EVENT_TYPE(wxEVT_MY_EVENT) - + // user code intercepting the event - + BEGIN_EVENT_TABLE(MyFrame, wxFrame) EVT_MENU (wxID_EXIT, MyFrame::OnExit) // .... EVT_COMMAND (ID_MY_WINDOW, wxEVT_MY_EVENT, MyFrame::OnMyEvent) END_EVENT_TABLE() - + void MyFrame::OnMyEvent( wxCommandEvent ) { // do something wxString text = event.GetText(); } - - + + // user code sending the event - + void MyWindow::SendEvent() { wxCommandEvent event( wxEVT_MY_EVENT, GetId() ); @@ -949,146 +949,146 @@ GetEventHandler()-ProcessEvent( event ); } @endcode - - + + @b Generic event table macros - - - - - - + + + + + + @b EVT_CUSTOM(event, id, func) - - - - + + + + Allows you to add a custom event table entry by specifying the event identifier (such as wxEVT_SIZE), the window identifier, and a member function to call. - - - - - + + + + + @b EVT_CUSTOM_RANGE(event, id1, id2, func) - - - - + + + + The same as EVT_CUSTOM, but responds to a range of window identifiers. - - - - - + + + + + @b EVT_COMMAND(id, event, func) - - - - + + + + The same as EVT_CUSTOM, but expects a member function with a wxCommandEvent argument. - - - - - + + + + + @b EVT_COMMAND_RANGE(id1, id2, event, func) - - - - + + + + The same as EVT_CUSTOM_RANGE, but expects a member function with a wxCommandEvent argument. - - - - - + + + + + @b EVT_NOTIFY(event, id, func) - - - - + + + + The same as EVT_CUSTOM, but expects a member function with a wxNotifyEvent argument. - - - - - + + + + + @b EVT_NOTIFY_RANGE(event, id1, id2, func) - - - - + + + + The same as EVT_CUSTOM_RANGE, but expects a member function with a wxNotifyEvent argument. - - - - - - + + + + + + @b Defining your own event class Under certain circumstances, it will be required to define your own event class e.g. for sending more complex data from one place to another. Apart from defining your event class, you will also need to define your own event table macro (which is quite long). Watch out to put in enough casts to the inherited event function. Here is an example: - + @code // code defining event - + class wxPlotEvent: public wxNotifyEvent { public: wxPlotEvent( wxEventType commandType = wxEVT_@NULL, int id = 0 ); - + // accessors wxPlotCurve *GetCurve() { return m_curve; } - + // required for sending with wxPostEvent() virtual wxEvent *Clone() const; - + private: wxPlotCurve *m_curve; }; - + DECLARE_EVENT_TYPE( wxEVT_PLOT_ACTION, -1 ) - + typedef void (wxEvtHandler::*wxPlotEventFunction)(wxPlotEvent&); - + #define EVT_PLOT(id, fn) \ DECLARE_EVENT_TABLE_ENTRY( wxEVT_PLOT_ACTION, id, -1, \ (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) (wxNotifyEventFunction) \ wxStaticCastEvent( wxPlotEventFunction, & fn ), (wxObject *) @NULL ), - - + + // code implementing the event type and the event class - + DEFINE_EVENT_TYPE( wxEVT_PLOT_ACTION ) - + wxPlotEvent::wxPlotEvent( ... - - + + // user code intercepting the event - + BEGIN_EVENT_TABLE(MyFrame, wxFrame) EVT_PLOT (ID_MY_WINDOW, MyFrame::OnPlot) END_EVENT_TABLE() - + void MyFrame::OnPlot( wxPlotEvent ) { wxPlotCurve *curve = event.GetCurve(); } - - + + // user code sending the event - + void MyWindow::SendEvent() { wxPlotEvent event( wxEVT_PLOT_ACTION, GetId() ); @@ -1097,7 +1097,7 @@ GetEventHandler()-ProcessEvent( event ); } @endcode - + */ - - + + diff --git a/docs/doxygen/overviews/exceptions.h b/docs/doxygen/overviews/exceptions.h index 68e753d213..ed2769577f 100644 --- a/docs/doxygen/overviews/exceptions.h +++ b/docs/doxygen/overviews/exceptions.h @@ -7,16 +7,16 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page exceptions_overview C++ exceptions overview - + #Introduction @ref exceptionstrategies_overview #Technicalities - - + + @section exceptionintroduction Introduction - + wxWidgets had been started long before the exceptions were introduced in C++ so it is not very surprising that it is not built around using them as some more modern C++ libraries are. For instance, the library doesn't throw exceptions to @@ -28,10 +28,10 @@ still doesn't use the exceptions by itself but it should be now safe to use the exceptions in the user code and the library tries to help you with this. Please note that making the library exception-safe is still work in progress. - - + + @section exceptionstrategies Strategies for exceptions handling - + There are several choice for using the exceptions in wxWidgets programs. First of all, you may not use them at all. As stated above, the library doesn't throw any exceptions by itself and so you don't have to worry about exceptions at all @@ -40,27 +40,27 @@ Another strategy is to use exceptions only to signal truly fatal errors. In this case you probably don't expect to recover from them and the default behaviour -- to simply terminate the program -- may be appropriate. If it is - not, you may override #OnUnhandledException() + not, you may override #OnUnhandledException() in your wxApp-derived class to perform any clean up tasks. Note, however, that any information about the exact exception type is lost when this function is called, so if you need you should override #OnRun() and add a try/catch clause around the call of the base class version. This would allow you to catch any exceptions generated during the execution of the main event loop. To deal with the exceptions which may arise during the program - startup and/or shutdown you should insert try/catch clauses in + startup and/or shutdown you should insert try/catch clauses in #OnInit() and/or #OnExit() as well. Finally, you may also want to continue running even when certain exceptions occur. If all of your exceptions may happen only in the event handlers of a single class (or only in the classes derived from it), you may centralize your - exception handling code in #ProcessEvent + exception handling code in #ProcessEvent method of this class. If this is impractical, you may also consider overriding the wxApp::HandleEvent() which allows you to handle all the exceptions thrown by any event handler. - - + + @section exceptionstechnicalities Technicalities - - To use any kind of exception support in the library you need to build it with + + To use any kind of exception support in the library you need to build it with @c wxUSE_EXCEPTIONS set to 1. This should be the case by default but if it isn't, you should edit the @c include/wx/msw/setup.h file under Windows or run @c configure with @c --enable-exceptions argument @@ -68,9 +68,9 @@ On the other hand, if you do not plan to use exceptions, setting this flag to 0 or using @c --disable-exceptions could result in a leaner and slightly faster library. - As for any other library feature, there is a #sample + As for any other library feature, there is a #sample showing how to use it. Please look at its sources for further information. - + */ - - + + diff --git a/docs/doxygen/overviews/file.h b/docs/doxygen/overviews/file.h index 49c99a5900..e3ebf9c5d2 100644 --- a/docs/doxygen/overviews/file.h +++ b/docs/doxygen/overviews/file.h @@ -7,10 +7,10 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page file_overview File classes and functions overview - - Classes: #wxFile, #wxDir, #wxTempFile, + + Classes: #wxFile, #wxDir, #wxTempFile, #wxTextFile Functions: see @ref filefunctions_overview. wxWidgets provides some functions and classes to facilitate working with files. @@ -32,7 +32,7 @@ wxDir is a helper class for enumerating the files or subdirectories of a directory. It may be used to enumerate all files, only files satisfying the given template mask or only non-hidden files. - + */ - - + + diff --git a/docs/doxygen/overviews/font.h b/docs/doxygen/overviews/font.h index 3a24557b65..71b1a3653c 100644 --- a/docs/doxygen/overviews/font.h +++ b/docs/doxygen/overviews/font.h @@ -7,101 +7,101 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page font_overview wxFont overview - + Class: #wxFont, #wxFontDialog A font is an object which determines the appearance of text, primarily when drawing text to a window or device context. A font is determined by the following parameters (not all of them have to be specified, of course): - - - - - - + + + + + + Point size - - - - + + + + This is the standard way of referring to text size. - - - - - + + + + + Family - - - - + + + + Supported families are: @b wxDEFAULT, wxDECORATIVE, wxROMAN, wxSCRIPT, wxSWISS, wxMODERN. @b wxMODERN is a fixed pitch font; the others are either fixed or variable pitch. - - - - - + + + + + Style - - - - + + + + The value can be @b wxNORMAL, wxSLANT or @b wxITALIC. - - - - - + + + + + Weight - - - - + + + + The value can be @b wxNORMAL, wxLIGHT or @b wxBOLD. - - - - - + + + + + Underlining - - - - + + + + The value can be @true or @false. - - - - - + + + + + Face name - - - - + + + + An optional string specifying the actual typeface to be used. If @NULL, a default typeface will chosen based on the family. - - - - - + + + + + Encoding - - - - + + + + The font encoding (see @b wxFONTENCODING_XXX constants and the @ref fontencoding_overview for more details) - - - - - + + + + + Specifying a family, rather than a specific typeface name, ensures a degree of portability across platforms because a suitable font will be chosen for the given font family, however it doesn't allow to choose a font precisely as the @@ -113,26 +113,26 @@ standard Windows fonts, or if allowing the user to specify a face name, store the family name with any file that might be transported to a different Windows machine or other platform. - + @b Note: There is currently a difference between the appearance of fonts on the two platforms, if the mapping mode is anything other than wxMM_TEXT. Under X, font size is always specified in points. Under MS Windows, the unit for text is points but the text is scaled according to the current mapping mode. However, user scaling on a device context will also scale fonts under both environments. - + @ref nativefontinformation_overview - - + + @section nativefontinformation Native font information - + An alternative way of choosing fonts is to use the native font description. This is the only acceptable solution if the user is allowed to choose the font using the #wxFontDialog because the selected font cannot be described using only the family name and so, if only family name is stored permanently, the user would almost surely see a different font in the program later. - Instead, you should store the value returned by + Instead, you should store the value returned by wxFont::GetNativeFontInfoDesc and pass it to wxFont::SetNativeFontInfo later to recreate exactly the same font. @@ -142,7 +142,7 @@ implemented for Windows and Unix (GTK+ and Motif) ports only, all the methods are available for all the ports and should be used to make your program work correctly when they are implemented later. - + */ - - + + diff --git a/docs/doxygen/overviews/fontencoding.h b/docs/doxygen/overviews/fontencoding.h index 475a440880..df9ab8e424 100644 --- a/docs/doxygen/overviews/fontencoding.h +++ b/docs/doxygen/overviews/fontencoding.h @@ -7,114 +7,114 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page fontencoding_overview Font encoding overview - + wxWidgets has support for multiple font encodings. By encoding we mean here the mapping between the character codes and the letters. Probably the most well-known encoding is (7 bit) ASCII one which is used almost universally now to represent the letters of the English alphabet and some other common characters. However, it is not enough to represent the letters of foreign alphabets and here other encodings come into play. Please - note that we will only discuss 8-bit fonts here and not + note that we will only discuss 8-bit fonts here and not #Unicode. - Font encoding support is ensured by several classes: - #wxFont itself, but also - #wxFontEnumerator and + Font encoding support is ensured by several classes: + #wxFont itself, but also + #wxFontEnumerator and #wxFontMapper. wxFont encoding support is reflected by a (new) constructor parameter @e encoding which takes one of the following values (elements of enumeration type @c wxFontEncoding): - - - - - - + + + + + + wxFONTENCODING_SYSTEM - - - - + + + + The default encoding of the underlying operating system (notice that this might be a "foreign" encoding for foreign versions of Windows 9x/NT). - - - - - + + + + + wxFONTENCODING_DEFAULT - - - - + + + + The applications default encoding as returned by wxFont::GetDefaultEncoding. On program startup, the applications default encoding is the same as wxFONTENCODING_SYSTEM, but may be changed to make all the fonts created later to use it (by default). - - - - - + + + + + wxFONTENCODING_ISO8859_1..15 - - - - + + + + ISO8859 family encodings which are usually used by all non-Microsoft operating systems - - - - - + + + + + wxFONTENCODING_KOI8 - - - - + + + + Standard Cyrillic encoding for the Internet (but see also wxFONTENCODING_ISO8859_5 and wxFONTENCODING_CP1251) - - - - - + + + + + wxFONTENCODING_CP1250 - - - - + + + + Microsoft analogue of ISO8859-2 - - - - - + + + + + wxFONTENCODING_CP1251 - - - - + + + + Microsoft analogue of ISO8859-5 - - - - - + + + + + wxFONTENCODING_CP1252 - - - - + + + + Microsoft analogue of ISO8859-1 - - - - - + + + + + As you may see, Microsoft's encoding partly mirror the standard ISO8859 ones, but there are (minor) differences even between ISO8859-1 (Latin1, ISO encoding for Western Europe) and CP1251 (WinLatin1, standard code page for English @@ -129,13 +129,13 @@ written in Cyrillic) are different on different platforms and because the fonts in the given encoding might just not be installed (this is especially a problem with Unix, or, in general, non-Win32 systems). - To clarify, the #wxFontEnumerator + To clarify, the #wxFontEnumerator class may be used to enumerate both all available encodings and to find the facename(s) in which the given encoding exists. If you can find the font in the correct encoding with wxFontEnumerator then your troubles are over, but, unfortunately, sometimes this is not enough. For example, there is no standard way (that I know of, please tell me if you do!) to find a font on a Windows system - for KOI8 encoding (only for WinCyrillic one which is quite different), so + for KOI8 encoding (only for WinCyrillic one which is quite different), so #wxFontEnumerator will never return one, even if the user has installed a KOI8 font on his system. To solve this problem, a #wxFontMapper class is provided. @@ -147,7 +147,7 @@ All these topics are illustrated by the @ref samplefont_overview; please refer to it and the documentation of the classes mentioned here for further explanations. - + */ - - + + diff --git a/docs/doxygen/overviews/fs.h b/docs/doxygen/overviews/fs.h index 9c28179ab9..d061d5e2f1 100644 --- a/docs/doxygen/overviews/fs.h +++ b/docs/doxygen/overviews/fs.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page fs_overview wxFileSystem - + The wxHTML library uses a @b virtual file systems mechanism similar to the one used in Midnight Commander, Dos Navigator, FAR or almost any modern file manager. It allows the user to access @@ -17,8 +17,8 @@ generated files that exist only in memory are also supported. @b Classes Three classes are used in order to provide virtual file systems mechanism: - - + + The #wxFSFile class provides information about opened file (name, input stream, mime type and anchor). The #wxFileSystem class is the interface. @@ -29,111 +29,111 @@ the VFS mechanism. You can derive your own handler and pass it to wxFileSystem's AddHandler() method. In the new handler you only need to override the OpenFile() and CanOpen() methods. - - + + @b Locations Locations (aka filenames aka addresses) are constructed from four parts: - - + + @b protocol - handler can recognize if it is able to open a file by checking its protocol. Examples are "http", "file" or "ftp". @b right location - is the name of file within the protocol. In "http://www.wxwidgets.org/index.html" the right location is "//www.wxwidgets.org/index.html". @b anchor - an anchor is optional and is usually not present. In "index.htm#chapter2" the anchor is "chapter2". - @b left location - this is usually an empty string. + @b left location - this is usually an empty string. It is used by 'local' protocols such as ZIP. See Combined Protocols paragraph for details. - - + + @b Combined Protocols - The left location precedes the protocol in the URL string. + The left location precedes the protocol in the URL string. It is not used by global protocols like HTTP but it becomes handy when nesting protocols - for example you may want to access files in a ZIP archive: file:archives/cpp_doc.zip#zip:reference/fopen.htm#syntax In this example, the protocol is "zip", right location is "reference/fopen.htm", anchor is "syntax" and left location - is "file:archives/cpp_doc.zip". + is "file:archives/cpp_doc.zip". There are @b two protocols used in this example: "zip" and "file". @b File Systems Included in wxHTML The following virtual file system handlers are part of wxWidgets so far: - - - - - - + + + + + + @b wxArchiveFSHandler - - - - + + + + A handler for archives such as zip and tar. Include file is wx/fs_arc.h. URLs examples: "archive.zip#zip:filename", "archive.tar.gz#gzip:#tar:filename". - - - - - + + + + + @b wxFilterFSHandler - - - - + + + + A handler for compression schemes such as gzip. Header is wx/fs_filter.h. URLs are in the form, e.g.: "document.ps.gz#gzip:". - - - - - + + + + + @b wxInternetFSHandler - - - - + + + + A handler for accessing documents via HTTP or FTP protocols. Include file is wx/fs_inet.h. - - - - - + + + + + @b wxMemoryFSHandler - - - - - This handler allows you to access + + + + + This handler allows you to access data stored in memory (such as bitmaps) as if they were regular files. See @ref memoryfshandler_overview for details. - Include file is wx/fs_mem.h. URL is prefixed with memory:, e.g. + Include file is wx/fs_mem.h. URL is prefixed with memory:, e.g. "memory:myfile.htm" - - - - - + + + + + In addition, wxFileSystem itself can access local files. - + @b Initializing file system handlers Use wxFileSystem::AddHandler to initialize a handler, for example: - + @code #include wx/fs_mem.h - + ... - + bool MyApp::OnInit() { wxFileSystem::AddHandler(new wxMemoryFSHandler); ... } @endcode - + */ - - + + diff --git a/docs/doxygen/overviews/grid.h b/docs/doxygen/overviews/grid.h index 2acf6dfa52..17f2ebd5e1 100644 --- a/docs/doxygen/overviews/grid.h +++ b/docs/doxygen/overviews/grid.h @@ -7,77 +7,77 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page grid_overview wxGrid classes overview - + Classes: #wxGrid #Introduction @ref simplewxgridexample_overview @ref complexwxgridexample_overview @ref gridclassesrelations_overview @ref keyboardandmouseinwxgrid_overview - - + + @section introductiontowxgrid Introduction - + wxGrid and its related classes are used for displaying and editing tabular data. - + @section simplewxgridexample Getting started: a simple example - + For simple applications you need only refer to the wxGrid class in your code. This example shows how you might create a grid in a frame or - dialog constructor and illustrates some of the formatting functions. - + dialog constructor and illustrates some of the formatting functions. + @code // Create a wxGrid object - + grid = new wxGrid( this, -1, wxPoint( 0, 0 ), wxSize( 400, 300 ) ); - + // Then we call CreateGrid to set the dimensions of the grid // (100 rows and 10 columns in this example) grid-CreateGrid( 100, 10 ); - + // We can set the sizes of individual rows and columns // in pixels grid-SetRowSize( 0, 60 ); grid-SetColSize( 0, 120 ); - + // And set grid cell contents as strings grid-SetCellValue( 0, 0, "wxGrid is good" ); - + // We can specify that some cells are read-only grid-SetCellValue( 0, 3, "This is read-only" ); grid-SetReadOnly( 0, 3 ); - + // Colours can be specified for grid cell contents grid-SetCellValue(3, 3, "green on grey"); grid-SetCellTextColour(3, 3, *wxGREEN); grid-SetCellBackgroundColour(3, 3, *wxLIGHT_GREY); - - // We can specify the some cells will store numeric - // values rather than strings. Here we set grid column 5 - // to hold floating point values displayed with width of 6 + + // We can specify the some cells will store numeric + // values rather than strings. Here we set grid column 5 + // to hold floating point values displayed with width of 6 // and precision of 2 grid-SetColFormatFloat(5, 6, 2); grid-SetCellValue(0, 6, "3.1415"); @endcode - - + + @section complexwxgridexample A more complex example - + Yet to be written - + @section wxgridclassesrelations How the wxGrid classes relate to each other - + Yet to be written - + @section keyboardandmouseinwxgrid Keyboard and mouse actions - + Yet to be written - + */ - - + + diff --git a/docs/doxygen/overviews/helloworld.h b/docs/doxygen/overviews/helloworld.h index dfebdef2a1..294ca09cd5 100644 --- a/docs/doxygen/overviews/helloworld.h +++ b/docs/doxygen/overviews/helloworld.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page helloworld_overview wxWidgets Hello World sample - + As many people have requested a mini-sample to be published here so that some quick judgment concerning syntax and basic principles can be made, you can now look at wxWidgets' @@ -19,63 +19,63 @@ or using one global include (#include "wx/wx.h"). This is also useful on platforms which support precompiled headers such as all major compilers on the Windows platform. - + @code // // file name: hworld.cpp // // purpose: wxWidgets "Hello world" // - + // 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 @endcode - + Practically every app should define a new class derived from wxApp. By overriding wxApp's OnInit() the program can be initialized, - e.g. by creating a new main window. - + e.g. by creating a new main window. + @code class MyApp: public wxApp { virtual bool OnInit(); }; @endcode - - The main window is created by deriving a class from wxFrame and + + The main window is created by deriving a class from wxFrame and giving it a menu and a status bar in its constructor. Also, any class that wishes to respond to any "event" (such as mouse clicks or - messages from the menu or a button) must declare an event table - using the macro below. Finally, the way to react to such events - must be done in "handlers". In our sample, we react to two menu items, + messages from the menu or a button) must declare an event table + using the macro below. Finally, the way to react to such events + must be done in "handlers". In our sample, we react to two menu items, one for "Quit" and one for displaying an "About" window. These handlers should not be virtual. - + @code class MyFrame: public wxFrame { public: MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size); - + void OnQuit(wxCommandEvent& event); void OnAbout(wxCommandEvent& event); - + private: DECLARE_EVENT_TABLE() }; @endcode - + In order to be able to react to a menu command, it must be given a unique identifier such as a const or an enum. - + @code enum { @@ -83,7 +83,7 @@ ID_About, }; @endcode - + We then proceed to actually implement an event table in which the events are routed to their respective handler functions in the class MyFrame. There are predefined macros for routing all common events, ranging from @@ -95,27 +95,27 @@ the (only) parameter in an event handler is a reference to a wxEvent object, which holds various information about the event (such as the ID of and a pointer to the class, which emitted the event). - + @code BEGIN_EVENT_TABLE(MyFrame, wxFrame) EVT_MENU(ID_Quit, MyFrame::OnQuit) EVT_MENU(ID_About, MyFrame::OnAbout) END_EVENT_TABLE() @endcode - + As in all programs there must be a "main" function. Under wxWidgets main is implemented using this macro, which creates an application instance and starts the program. - + @code IMPLEMENT_APP(MyApp) @endcode - + As mentioned above, wxApp::OnInit() is called upon startup and should be used to initialize the program, maybe showing a "splash screen" and creating the main window (or several). The frame should get a title bar text ("Hello World") and a position and start-up size. One frame can also be declared to be the top window. Returning @true indicates a successful initialization. - + @code bool MyApp::OnInit() { @@ -125,46 +125,46 @@ return @true; } @endcode - - In the constructor of the main window (or later on) we create a menu with two menu - items as well as a status bar to be shown at the bottom of the main window. Both have + + In the constructor of the main window (or later on) we create a menu with two menu + items as well as a status bar to be shown at the bottom of the main window. Both have to be "announced" to the frame with respective calls. - + @code MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size) : wxFrame((wxFrame *)@NULL, -1, title, pos, size) { wxMenu *menuFile = new wxMenu; - + menuFile-Append( ID_About, "" ); menuFile-AppendSeparator(); menuFile-Append( ID_Quit, "E" ); - + wxMenuBar *menuBar = new wxMenuBar; menuBar-Append( menuFile, "" ); - + SetMenuBar( menuBar ); - + CreateStatusBar(); SetStatusText( "Welcome to wxWidgets!" ); } @endcode - + Here are the actual event handlers. MyFrame::OnQuit() closes the main window by calling Close(). The parameter @true indicates that other windows have no veto - power such as after asking "Do you really want to close?". If there is no other + power such as after asking "Do you really want to close?". If there is no other main window left, the application will quit. - + @code void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event)) { Close( @true ); } @endcode - + MyFrame::OnAbout() will display a small window with some text in it. In this case a typical "About" window with information about the program. - + @code void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event)) { @@ -172,7 +172,7 @@ "About Hello World", wxOK | wxICON_INFORMATION ); } @endcode - + */ - - + + diff --git a/docs/doxygen/overviews/html.h b/docs/doxygen/overviews/html.h index 9000e459a2..d94f132f23 100644 --- a/docs/doxygen/overviews/html.h +++ b/docs/doxygen/overviews/html.h @@ -7,15 +7,15 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page html_overview wxHTML overview - + The wxHTML library provides classes for parsing and displaying HTML. It is not intended to be a high-end HTML browser. If you are looking for something like that try #http://www.mozilla.org. - wxHTML can be used as a generic rich text viewer - for example to display + wxHTML can be used as a generic rich text viewer - for example to display a nice About Box (like those of GNOME apps) or to display the result of - database searching. There is a #wxFileSystem + database searching. There is a #wxFileSystem class which allows you to use your own virtual file systems. wxHtmlWindow supports tag handlers. This means that you can easily extend wxHtml library with new, unsupported tags. Not only that, @@ -30,19 +30,19 @@ @ref cells_overview @ref handlers_overview @ref htmltagssupported_overview - - + + @section wxhtmlquickstart wxHTML quick start - + @b Displaying HTML First of all, you must include wx/wxhtml.h. Class #wxHtmlWindow (derived from wxScrolledWindow) is used to display HTML documents. - It has two important methods: #LoadPage + It has two important methods: #LoadPage and #SetPage. LoadPage loads and displays HTML file while SetPage displays directly the passed @b string. See the example: - + @code mywin - LoadPage("test.htm"); mywin - SetPage("htmlbody" @@ -50,25 +50,25 @@ "Some error occurred :-H)" "/body/hmtl"); @endcode - + @b Displaying Help See #wxHtmlHelpController. @b Setting up wxHtmlWindow Because wxHtmlWindow is derived from wxScrolledWindow and not from wxFrame, it doesn't have visible frame. But the user usually wants to see - the title of HTML page displayed somewhere and the frame's titlebar is + the title of HTML page displayed somewhere and the frame's titlebar is the ideal place for it. - wxHtmlWindow provides 2 methods in order to handle this: - #SetRelatedFrame and - #SetRelatedStatusBar. + wxHtmlWindow provides 2 methods in order to handle this: + #SetRelatedFrame and + #SetRelatedStatusBar. See the example: - + @code html = new wxHtmlWindow(this); html - SetRelatedFrame(this, "HTML : %%s"); html - SetRelatedStatusBar(0); @endcode - + The first command associates the HTML object with its parent frame (this points to wxFrame object there) and sets the format of the title. Page title "Hello, world!" will be displayed as "HTML : Hello, world!" @@ -78,30 +78,30 @@ @b Customizing wxHtmlWindow You can customize wxHtmlWindow by setting font size, font face and borders (space between border of window and displayed HTML). Related functions: - - + + #SetFonts #SetBorders #ReadCustomization #WriteCustomization - - + + The last two functions are used to store user customization info wxConfig stuff (for example in the registry under Windows, or in a dotfile under Unix). - + @section printing HTML Printing - - The wxHTML library provides printing facilities with several levels of complexity. - The easiest way to print an HTML document is to use + + The wxHTML library provides printing facilities with several levels of complexity. + The easiest way to print an HTML document is to use @ref htmleasyprinting_overview. It lets you print HTML documents with only one - command and you don't have to worry about deriving from the wxPrintout class at all. It is only a simple wrapper around the + command and you don't have to worry about deriving from the wxPrintout class at all. It is only a simple wrapper around the #wxHtmlPrintout, normal wxWidgets printout class. And finally there is the low level class #wxHtmlDCRenderer which you can use to render HTML into a rectangular area on any DC. It supports rendering into multiple rectangles with the same width. (The most common use of this is placing one rectangle on each page or printing into two columns.) - + @section helpformat Help Files Format - + wxHTML library uses a reduced version of MS HTML Workshop format. Tex2RTF can produce these files when generating HTML, if you set @b htmlWorkshopFiles to @b @true in your tex2rtf.ini file. @@ -111,34 +111,34 @@ for wxHTML (or helpview) to read; and the .zip file can optionally be renamed to .htb. @b Header file (.hhp) Header file must contain these lines (and may contain additional lines which are ignored) : - + @code Contents file=filename.hhc Index file=filename.hhk Title=title of your book Default topic=default page to be displayed.htm @endcode - - All filenames (including the Default topic) are relative to the + + All filenames (including the Default topic) are relative to the location of .hhp file. @b Localization note: In addition, .hhp file may contain line - + @code Charset=rfc_charset @endcode - + which specifies what charset (e.g. "iso8859_1") was used in contents and index files. Please note that this line is incompatible with MS HTML Help Workshop and it would either silently remove it or complain - with some error. See also + with some error. See also @ref nonenglish_overview. @b Contents file (.hhc) Contents file has HTML syntax and it can be parsed by regular HTML parser. It contains exactly one list (@c ul....@c /ul statement): - + @code ul - + li object type="text/sitemap" param name="Name" value="@topic name@" param name="ID" value=@numeric_id@ @@ -149,19 +149,19 @@ param name="ID" value=@numeric_id@ param name="Local" value="@filename.htm@" /object - ... - + ... + /ul @endcode - + You can modify value attributes of param tags. @e topic name is name of chapter/topic as is displayed in - contents, @e filename.htm is HTML page name (relative to .hhp file) and @e numeric_id is optional + contents, @e filename.htm is HTML page name (relative to .hhp file) and @e numeric_id is optional - it is used only when you use wxHtmlHelpController::Display(int) Items in the list may be nested - one @c li statement may contain a @c ul sub-statement: - + @code ul - + li object type="text/sitemap" param name="Name" value="Top node" param name="Local" value="top.htm" @@ -173,33 +173,33 @@ /object ... /ul - + li object type="text/sitemap" param name="Name" value="Another Top" param name="Local" value="top2.htm" /object - ... - + ... + /ul @endcode - + @b Index file (.hhk) - Index files have same format as contents file except that ID params are ignored and sublists are @b not + Index files have same format as contents file except that ID params are ignored and sublists are @b not allowed. - + @section filters Input Filters - + The wxHTML library provides a mechanism for reading and displaying - files of many different file formats. + files of many different file formats. wxHtmlWindow::LoadPage can load not only HTML files but any known file. To make a file type known to wxHtmlWindow you must create a #wxHtmlFilter filter and register it using wxHtmlWindow::AddFilter. - + @section cells Cells and Containers - - This article describes mechanism used by - #wxHtmlWinParser and + + This article describes mechanism used by + #wxHtmlWinParser and #wxHtmlWindow to parse and display HTML documents. @b Cells You can divide any text (or HTML) into small fragments. Let's call these @@ -209,54 +209,54 @@ See #wxHtmlCell. @b Containers Container is kind of cell that may contain sub-cells. Its size depends - on number and sizes of its sub-cells (and also depends on width of window). - See #wxHtmlContainerCell, + on number and sizes of its sub-cells (and also depends on width of window). + See #wxHtmlContainerCell, wxHtmlCell::Layout. This image shows the cells and containers: - + @b Using Containers in Tag Handler #wxHtmlWinParser provides a user-friendly way of managing containers. It is based on the idea of opening and closing containers. Use #OpenContainer to open new - a container @e within an already opened container. This new container is a + a container @e within an already opened container. This new container is a @e sub-container of the old one. (If you want to create a new container with the same depth level you can call @c CloseContainer(); OpenContainer();.) - Use #CloseContainer to close the + Use #CloseContainer to close the container. This doesn't create a new container with same depth level but it returns "control" to the parent container. See explanation: - + There clearly must be same number of calls to OpenContainer as to CloseContainer. @b Example This code creates a new paragraph (container at same depth level) with "Hello, world!": - + @code m_WParser - CloseContainer(); c = m_WParser - OpenContainer(); - + m_WParser - AddText("Hello, "); m_WParser - AddText("world!"); - + m_WParser - CloseContainer(); m_WParser - OpenContainer(); @endcode - + and here is image of the situation: - + You can see that there was an opened container before the code was executed. We closed it, created our own container, then closed our container and opened new container. The result was that we had @e same depth level after executing. This is general rule that should be followed by tag handlers: leave depth level of containers unmodified (in other words, number of OpenContainer and CloseContainer calls should be same within #HandleTag's body). - Notice that it would be usually better to use + Notice that it would be usually better to use wxHtmlContainerCell::InsertCell instead of adding text to the parser directly. - + @section handlers Tag Handlers - + The wxHTML library provides architecture of pluggable @e tag handlers. Tag handler is class that understands particular HTML tag (or tags) and is able to interpret it. @@ -268,26 +268,26 @@ @b How it works Common tag handler's #HandleTag method works in four steps: - - + + Save state of parent parser into local variables Change parser state according to tag's params Parse text between the tag and paired ending tag (if present) Restore original parser state - - + + See #wxHtmlWinParser for methods for modifying parser's state. In general you can do things like opening/closing containers, changing colors, fonts etc. @b Providing own tag handlers - You should create new .cpp file and place following lines into it: - + You should create new .cpp file and place following lines into it: + @code #include mod_templ.h #include forcelink.h FORCE_LINK_ME(yourmodulefilenamewithoutcpp) @endcode - + Then you must define handlers and one module. @b Tag handlers The handler is derived from #wxHtmlWinTagHandler @@ -301,58 +301,58 @@ Starts handler definition. @e name is handler identifier (in fact part of class name), @e tags is string containing list of tags supported by this handler (in uppercase). This macro derives new class from - wxHtmlWinTagHandler and implements it is + wxHtmlWinTagHandler and implements it is #GetSupportedTags method. Example: TAG_HANDLER_BEGIN(FONTS, "B,I,U,T") @b TAG_HANDLER_VARS This macro starts block of variables definitions. (Variables are identical to class attributes.) Example: - + @code TAG_HANDLER_BEGIN(VARS_ONLY, "CRAZYTAG") TAG_HANDLER_VARS int my_int_var; - wxString something_else; + wxString something_else; TAG_HANDLER_END(VARS_ONLY) @endcode - + This macro is used only in rare cases. @b TAG_HANDLER_CONSTR(@e name) This macro supplies object constructor. @e name is same name as the one from TAG_HANDLER_BEGIN macro. Body of constructor follow after this macro (you must use and ). Example: - + @code TAG_HANDLER_BEGIN(VARS2, "CRAZYTAG") TAG_HANDLER_VARS int my_int_var; TAG_HANDLER_CONSTR(vars2) { // !!!!!! - my_int_var = 666; - } // !!!!!! + my_int_var = 666; + } // !!!!!! TAG_HANDLER_END(VARS2) @endcode - + Never used in wxHTML :-) @b TAG_HANDLER_PROC(@e varib) This is very important macro. It defines #HandleTag method. @e varib is name of parameter passed to the method, usually @e tag. Body of method follows after this macro. Note than you must use and ! Example: - + @code TAG_HANDLER_BEGIN(TITLE, "TITLE") TAG_HANDLER_PROC(tag) { - printf("TITLE found...\n"); - } + printf("TITLE found...\n"); + } TAG_HANDLER_END(TITLE) @endcode - + @b TAG_HANDLER_END(@e name) - Ends definition of tag handler @e name. + Ends definition of tag handler @e name. @b Tags Modules - You can use set of 3 macros TAGS_MODULE_BEGIN, TAGS_MODULE_ADD and + You can use set of 3 macros TAGS_MODULE_BEGIN, TAGS_MODULE_ADD and TAGS_MODULE_END to inherit new module from #wxHtmlTagsModule and to create instance of it. See macros reference: @@ -365,7 +365,7 @@ @b TAGS_MODULE_END(@e modname) Ends the definition of module. @b Example: - + @code TAGS_MODULE_BEGIN(Examples) TAGS_MODULE_ADD(VARS_ONLY) @@ -373,32 +373,32 @@ TAGS_MODULE_ADD(TITLE) TAGS_MODULE_END(Examples) @endcode - - + + @section htmltagssupported Tags supported by wxHTML - - wxHTML is not full implementation of HTML standard. Instead, it supports most common tags so that it + + wxHTML is not full implementation of HTML standard. Instead, it supports most common tags so that it is possible to display @e simple HTML documents with it. (For example it works fine with pages created in Netscape Composer or generated by tex2rtf). Following tables list all tags known to wxHTML, together with supported parameters. A tag has general form of @c tagname param_1 param_2 ... param_n where param_i is - either @c paramname="paramvalue" or @c paramname=paramvalue - these two are equivalent. Unless stated + either @c paramname="paramvalue" or @c paramname=paramvalue - these two are equivalent. Unless stated otherwise, wxHTML is case-insensitive. @b Table of common parameter values We will use these substitutions in tags descriptions: - + @code [alignment] CENTER LEFT RIGHT JUSTIFY - + [v_alignment] TOP BOTTOM CENTER - + [color] HTML 4.0-compliant colour specification - + [fontsize] -2 -1 +0 @@ -413,23 +413,23 @@ 5 6 7 - + [pixels] integer value that represents dimension in pixels - - [percent] i% + + [percent] i% where i is integer - - [url] an URL - + + [url] an URL + [string] text string - + [coords] c(1),c(2),c(3),...,c(n) where c(i) is integer @endcode - - + + @b List of supported tags - + @code A NAME=[string] HREF=[url] @@ -519,7 +519,7 @@ U UL @endcode - + */ - - + + diff --git a/docs/doxygen/overviews/imagelist.h b/docs/doxygen/overviews/imagelist.h index a66b1e3ea3..450d452090 100644 --- a/docs/doxygen/overviews/imagelist.h +++ b/docs/doxygen/overviews/imagelist.h @@ -7,18 +7,18 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page imagelist_overview wxImageList overview - + Classes: #wxImageList An image list is a list of images that may have transparent areas. The class helps an application organise a collection of images so that they can be referenced by integer index instead of by pointer. - Image lists are used in #wxNotebook, + Image lists are used in #wxNotebook, #wxListCtrl, #wxTreeCtrl and some other control classes. - + */ - - + + diff --git a/docs/doxygen/overviews/internationalization.h b/docs/doxygen/overviews/internationalization.h index d66fcfef4a..8507087054 100644 --- a/docs/doxygen/overviews/internationalization.h +++ b/docs/doxygen/overviews/internationalization.h @@ -7,15 +7,15 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page internationalization_overview Internationalization - + Although internationalization of an application (i18n for short) involves far more than just translating its text messages to another message - date, time and currency formats need changing too, some languages are written left to right and others right to left, character encoding may differ and many other things may need changing too - it is a necessary first step. wxWidgets provides - facilities for message translation with its + facilities for message translation with its #wxLocale class and is itself fully translated into several languages. Please consult wxWidgets home page for the most up-to-date translations - and if you translate it into one of the languages not done @@ -34,10 +34,10 @@ with @e msgfmt program (part of gettext package) and have the extension .mo. Only the binary files are needed during program execution. The program i18n involves several steps: - - - Translating the strings in the program text using - #wxGetTranslation or equivalently the + + + Translating the strings in the program text using + #wxGetTranslation or equivalently the #_() macro. Extracting the strings to be translated from the program: this uses the work done in the previous step because @c xgettext program used for string @@ -51,7 +51,7 @@ language(s). It involves editing the .po file. Compiling the .po file into .mo file to be used by the program. Installing the .mo files with your application in the appropriate - location for the target system which is the one returned by + location for the target system which is the one returned by wxStandardPaths::GetLocalizedResourcesDir(wxStandardPaths::ResourceCat_Messages). If the message catalogs are not installed in this default location you may explicitly use #AddCatalogLookupPathPrefix() to @@ -59,8 +59,8 @@ default directory. Setting the appropriate locale in your program to use the strings for the given language: see #wxLocale. - - + + See also the http://www.gnu.org/software/gettext/manual/gettext.html. See also @ref nonenglish_overview. It focuses on handling charsets related problems. @@ -73,7 +73,7 @@ code can recognise them even when translated. wxWidgets does not provide translations for all of these currently. wxWidgets does not yet handle translated special key names such as Backspace, End, Insert, etc. - + */ - - + + diff --git a/docs/doxygen/overviews/ipc.h b/docs/doxygen/overviews/ipc.h index 2fd2a44fe1..571cbcf377 100644 --- a/docs/doxygen/overviews/ipc.h +++ b/docs/doxygen/overviews/ipc.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page ipc_overview Interprocess communication overview - + Classes: #wxServer, #wxConnection, #wxClient @@ -17,16 +17,16 @@ interprocess communication and network programming. This section only discusses one family of classes -- the DDE-like protocol -- but here's a list of other useful classes: - - + + #wxSocketEvent, #wxSocketBase, #wxSocketClient, #wxSocketServer: classes for the low-level TCP/IP API. #wxProtocol, #wxURL, #wxFTP, #wxHTTP: classes for programming popular Internet protocols. - - + + wxWidgets' DDE-like protocol is a high-level protocol based on Windows DDE. There are two implementations of this DDE-like protocol: one using real DDE running on Windows only, and another @@ -47,8 +47,8 @@ equivalent wxTCP... and wxDDE... classes can be used in much the same way. Three classes are central to the DDE-like API: - - + + wxClient. This represents the client application, and is used only within a client program. wxServer. This represents the server application, and is used @@ -57,8 +57,8 @@ client to the server - both the client and the server use an instance of this class, one per connection. Most DDE transactions operate on this object. - - + + Messages between applications are usually identified by three variables: connection object, topic name and item name. A data string is a fourth element of some messages. To create a @@ -82,8 +82,8 @@ overriding virtual functions in your class derived from wxConnection allows you to handle the DDE messages. To create a working server, the programmer must: - - + + Derive a class from wxConnection, providing handlers for various messages sent to the server side of a wxConnection (e.g. OnExecute, OnRequest, OnPoke). Only the handlers actually required by the application need to be @@ -94,11 +94,11 @@ derived connection class if the connection is accepted. Create an instance of your server object and call Create to activate it, giving it a service name. - - + + To create a working client, the programmer must: - - + + Derive a class from wxConnection, providing handlers for various messages sent to the client side of a wxConnection (e.g. OnAdvise). Only the handlers actually required by the application @@ -115,19 +115,19 @@ a connection object of the derived class if the connection is successful. Use the wxConnection member functions to send messages to the server. - - + + @ref datatransfer_overview #Examples @ref ddedetails_overview - - + + @section datatransfer Data transfer - + These are the ways that data can be transferred from one application to another. These are methods of wxConnection. - - + + @b Execute: the client calls the server with a data string representing a command to be executed. This succeeds or fails, depending on the server's willingness to answer. If the client wants to find the result @@ -143,22 +143,22 @@ @b Advise: The client asks to be advised of any change in data associated with a particular item. If the server agrees, the server will send an OnAdvise message to the client along with the item and data. - - + + The default data type is wxCF_TEXT (ASCII text), and the default data size is the length of the null-terminated string. Windows-specific data types could also be used on the PC. - + @section ipcexamples Examples - + See the sample programs @e server and @e client in the IPC samples directory. Run the server, then the client. This demonstrates using the Execute, Request, and Poke commands from the client, together with an Advise loop: selecting an item in the server list box causes that item to be highlighted in the client list box. - + @section ddedetails More DDE details - + A wxClient object initiates the client part of a client-server DDE-like (Dynamic Data Exchange) conversation (available in both Windows and Unix). @@ -171,7 +171,7 @@ member can return a wxConnection of the required class, when a connection is made. For example: - + @code class MyConnection: public wxConnection { public: @@ -180,14 +180,14 @@ bool OnAdvise(const wxString& topic, const wxString& item, char *data, int size, wxIPCFormat format) { wxMessageBox(topic, data); } }; - + class MyClient: public wxClient { public: MyClient(void) {} wxConnectionBase *OnMakeConnection(void) { return new MyConnection; } }; @endcode - + Here, @b MyConnection will respond to #OnAdvise messages sent by the server by displaying a message box. @@ -201,16 +201,16 @@ request for a connection is accepted, and the client then requests an @e Advise loop from the server (an Advise loop is where the server calls the client when data has changed). - + @code wxString server = "4242"; wxString hostName; wxGetHostName(hostName); - + // Create a new client MyClient *client = new MyClient; connection = (MyConnection *)client-MakeConnection(hostName, server, "IPC TEST"); - + if (!connection) { wxMessageBox("Failed to make connection to server", "Client Demo Error"); @@ -218,7 +218,7 @@ } connection-StartAdvise("Item"); @endcode - + */ - - + + diff --git a/docs/doxygen/overviews/listctrl.h b/docs/doxygen/overviews/listctrl.h index f0887f336d..6463e4a611 100644 --- a/docs/doxygen/overviews/listctrl.h +++ b/docs/doxygen/overviews/listctrl.h @@ -7,12 +7,12 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page listctrl_overview wxListCtrl overview - + Classes: #wxListCtrl, #wxImageList Sorry, this topic has yet to be written. - + */ - - + + diff --git a/docs/doxygen/overviews/log.h b/docs/doxygen/overviews/log.h index 68a5ddc6f4..18ab6bbb9b 100644 --- a/docs/doxygen/overviews/log.h +++ b/docs/doxygen/overviews/log.h @@ -7,29 +7,31 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page log_overview wxLog classes overview - + Classes: #wxLog, - + #wxLogStderr, - + #wxLogStream, - + #wxLogTextCtrl, - + #wxLogWindow, - + #wxLogGui, - + #wxLogNull, - + + #wxLogBuffer, + #wxLogChain, - + #wxLogInterposer, - + #wxLogInterposerTemp, - + #wxStreamToTextRedirector This is a general overview of logging classes provided by wxWidgets. The word logging here has a broad sense, including all of the program output, not only @@ -42,8 +44,8 @@ the same syntax as @e printf() or @e vprintf() , i.e. they take the format string as the first argument and respectively a variable number of arguments or a variable argument list pointer. Here are all of them: - - + + @b wxLogFatalError which is like @e wxLogError, but also terminates the program with the exit code 3 (using @e abort() standard function). Unlike for all the other logging functions, this function can't be @@ -70,7 +72,7 @@ does anything at all in the debug mode (when the preprocessor symbol __WXDEBUG__ is defined) and expands to nothing in release mode (otherwise). @b Tip: under Windows, you must either run the program under debugger or - use a 3rd party program such as #DbgView + use a 3rd party program such as #DbgView to actually see the debug output. @b wxLogTrace as @b wxLogDebug only does something in debug build. The reason for making it a separate function from it is that usually @@ -78,15 +80,15 @@ from other debug messages which would be flooded in them. Moreover, the second version of this function takes a trace mask as the first argument which allows to further restrict the amount of messages generated. - - + + The usage of these functions should be fairly straightforward, however it may be asked why not use the other logging facilities, such as C standard stdio functions or C++ streams. The short answer is that they're all very good generic mechanisms, but are not really adapted for wxWidgets, while the log classes are. Some of advantages in using wxWidgets log functions are: - - + + @b Portability It is a common practice to use @e printf() statements or cout/cerr C++ streams for writing out some (debug or otherwise) information. @@ -94,16 +96,16 @@ under Windows where the stdout of GUI programs is not assigned to anything. Thus, you might view @e wxLogMessage() as a simple substitute for @e printf(). You can also redirect the @e wxLogXXX calls to @e cout by just writing: - - + + @code wxLog *logger=new wxLogStream(); wxLog::SetActiveTarget(logger); @endcode - - - Finally, there is also a possibility to redirect the output sent to @e cout - to a #wxTextCtrl by using the + + + Finally, there is also a possibility to redirect the output sent to @e cout + to a #wxTextCtrl by using the #wxStreamToTextRedirector class. @b Flexibility The output of wxLog functions can be redirected or suppressed entirely based on their importance, which is either impossible or @@ -120,8 +122,8 @@ situation, the exact error code (and the corresponding error message) will be given to the user together with "high level" message about data file writing error. - - + + After having enumerated all the functions which are normally used to log the messages, and why would you want to use them we now describe how all this works. @@ -142,8 +144,8 @@ There are some predefined classes deriving from wxLog and which might be helpful to see how you can create a new log target class and, of course, may also be used without any change. There are: - - + + @b wxLogStderr This class logs messages to a @e FILE *, using stderr by default as its name suggests. @b wxLogStream This class has the same functionality as wxLogStderr, @@ -155,32 +157,34 @@ collects all messages generated by the application and also passes them to the previous active log target. The log window frame has a menu allowing user to clear the log, close it completely or save all messages to file. + @b wxLogBuffer This target collects all the logged messages in an + internal buffer allowing to show them later to the user all at once. @b wxLogNull The last log class is quite particular: it doesn't do anything. The objects of this class may be instantiated to (temporarily) suppress output of @e wxLogXXX() functions. As an example, trying to open a non-existing file will usually provoke an error message, but if for some reasons it is unwanted, just use this construction: - + @code wxFile file; - + // wxFile.Open() normally complains if file can't be opened, we don't want it { wxLogNull logNo; if ( !file.Open("bar") ) ... process error ourselves ... } // ~wxLogNull called, old log sink restored - + wxLogMessage("..."); // ok @endcode - - - + + + The log targets can also be combined: for example you may wish to redirect the messages somewhere else (for example, to a log file) but also process them as normally. For this the #wxLogChain, #wxLogInterposer and #wxLogInterposerTemp can be used. - + */ - - + + diff --git a/docs/doxygen/overviews/mbconvclasses.h b/docs/doxygen/overviews/mbconvclasses.h index a90907a02a..28d80c4792 100644 --- a/docs/doxygen/overviews/mbconvclasses.h +++ b/docs/doxygen/overviews/mbconvclasses.h @@ -7,12 +7,12 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page mbconvclasses_overview wxMBConv classes overview - - Classes: #wxMBConv, wxMBConvLibc, - #wxMBConvUTF7, #wxMBConvUTF8, - #wxCSConv, + + Classes: #wxMBConv, wxMBConvLibc, + #wxMBConvUTF7, #wxMBConvUTF8, + #wxCSConv, #wxMBConvUTF16, #wxMBConvUTF32 The wxMBConv classes in wxWidgets enable an Unicode-aware application to easily convert between Unicode and the variety of 8-bit encoding systems still @@ -24,10 +24,10 @@ #wxCSConv @ref convertingstrings_overview @ref convertingbuffers_overview - - + + @section needforconversion Background: The need for conversion - + As programs are becoming more and more globalized, and users exchange documents across country boundaries as never before, applications increasingly need to take into account all the different character sets in use around the world. It @@ -43,9 +43,9 @@ Unicode data from one Unicode-aware system to another may need encoding to an 8-bit multibyte encoding (UTF-7 or UTF-8 is typically used for this purpose), to pass unhindered through any traditional transport channels. - + @section conversionandwxstring Background: The wxString class - + If you have compiled wxWidgets in Unicode mode, the wxChar type will become identical to wchar_t rather than char, and a wxString stores wxChars. Hence, all wxString manipulation in your application will then operate on Unicode @@ -56,18 +56,18 @@ data over a network, or processing a text file for some other application. You need a way to quickly convert your easily-handled Unicode data to and from a traditional 8-bit encoding. And this is what the wxMBConv classes do. - + @section wxmbconvclasses wxMBConv classes - + The base class for all these conversions is the wxMBConv class (which itself implements standard libc locale conversion). Derived classes include wxMBConvLibc, several different wxMBConvUTFxxx classes, and wxCSConv, which implement different kinds of conversions. You can also derive your own class for your own custom encoding and use it, should you need it. All you need to do is override the MB2WC and WC2MB methods. - + @section wxmbconvobjects wxMBConv objects - + Several of the wxWidgets-provided wxMBConv classes have predefined instances (wxConvLibc, wxConvFileName, wxConvUTF7, wxConvUTF8, wxConvLocal). You can use these predefined objects directly, or you can instantiate your own objects. @@ -75,9 +75,9 @@ interface is supposed to use, in the case that the user interface is not Unicode-based (like with GTK+ 1.2). By default, it points to wxConvLibc or wxConvLocal, depending on which works best on the current platform. - + @section wxcsconvclass wxCSConv - + The wxCSConv class is special because when it is instantiated, you can tell it which character set it should use, which makes it meaningful to keep many instances of them around, each with a different character set (or you can @@ -85,94 +85,94 @@ The predefined wxCSConv instance, wxConvLocal, is preset to use the default user character set, but you should rarely need to use it directly, it is better to go through wxConvCurrent. - + @section convertingstrings Converting strings - + Once you have chosen which object you want to use to convert your text, here is how you would use them with wxString. These examples all assume that you are using a Unicode build of wxWidgets, although they will still compile in a non-Unicode build (they just won't convert anything). Example 1: Constructing a wxString from input in current encoding. - + @code wxString str(input_data, *wxConvCurrent); @endcode - + Example 2: Input in UTF-8 encoding. - + @code wxString str(input_data, wxConvUTF8); @endcode - + Example 3: Input in KOI8-R. Construction of wxCSConv instance on the fly. - + @code wxString str(input_data, wxCSConv(wxT("koi8-r"))); @endcode - + Example 4: Printing a wxString to stdout in UTF-8 encoding. - + @code puts(str.mb_str(wxConvUTF8)); @endcode - + Example 5: Printing a wxString to stdout in custom encoding. Using preconstructed wxCSConv instance. - + @code wxCSConv cust(user_encoding); printf("Data: %s\n", (const char*) str.mb_str(cust)); @endcode - + Note: Since mb_str() returns a temporary wxCharBuffer to hold the result of the conversion, you need to explicitly cast it to const char* if you use it in a vararg context (like with printf). - + @section convertingbuffers Converting buffers - + If you have specialized needs, or just don't want to use wxString, you can also use the conversion methods of the conversion objects directly. This can even be useful if you need to do conversion in a non-Unicode build of wxWidgets; converting a string from UTF-8 to the current encoding should be possible by doing this: - + @code wxString str(wxConvUTF8.cMB2WC(input_data), *wxConvCurrent); @endcode - + Here, cMB2WC of the UTF8 object returns a wxWCharBuffer containing a Unicode string. The wxString constructor then converts it back to an 8-bit character set using the passed conversion object, *wxConvCurrent. (In a Unicode build of wxWidgets, the constructor ignores the passed conversion object and retains the Unicode data.) This could also be done by first making a wxString of the original data: - + @code wxString input_str(input_data); wxString str(input_str.wc_str(wxConvUTF8), *wxConvCurrent); @endcode - + To print a wxChar buffer to a non-Unicode stdout: - + @code printf("Data: %s\n", (const char*) wxConvCurrent-cWX2MB(unicode_data)); @endcode - + If you need to do more complex processing on the converted data, you may want to store the temporary buffer in a local variable: - + @code const wxWX2MBbuf tmp_buf = wxConvCurrent-cWX2MB(unicode_data); const char *tmp_str = (const char*) tmp_buf; printf("Data: %s\n", tmp_str); process_data(tmp_str); @endcode - + If a conversion had taken place in cWX2MB (i.e. in a Unicode build), the buffer will be deallocated as soon as tmp_buf goes out of scope. (The macro wxWX2MBbuf reflects the correct return value of cWX2MB (either char* or wxCharBuffer), except for the const.) - + */ - - + + diff --git a/docs/doxygen/overviews/nonenglish.h b/docs/doxygen/overviews/nonenglish.h index 0f69d9eb80..4f92f7b1df 100644 --- a/docs/doxygen/overviews/nonenglish.h +++ b/docs/doxygen/overviews/nonenglish.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page nonenglish_overview Writing non-English applications - + This article describes how to write applications that communicate with the user in a language other than English. Unfortunately many languages use different charsets under Unix and Windows (and other platforms, to make @@ -17,9 +17,9 @@ many characters that it is impossible to use the same texts under all platforms. The wxWidgets library provides a mechanism that helps you avoid distributing many - identical, only differently encoded, packages with your application + identical, only differently encoded, packages with your application (e.g. help files and menu items in iso8859-13 and windows-1257). Thanks - to this mechanism you can, for example, distribute only iso8859-13 data + to this mechanism you can, for example, distribute only iso8859-13 data and it will be handled transparently under all systems. Please read #Internationalization which describes the locales concept. @@ -27,11 +27,11 @@ used, any encodings are meant and any encodings may be substituted there. @b Locales The best way to ensure correctly displayed texts in a GUI across platforms - is to use locales. Write your in-code messages in English or without - diacritics and put real messages into the message catalog (see + is to use locales. Write your in-code messages in English or without + diacritics and put real messages into the message catalog (see #Internationalization). A standard .po file begins with a header like this: - + @code # SOME DESCRIPTIVE TITLE. # Copyright (C) YEAR Free Software Foundation, Inc. @@ -48,18 +48,18 @@ "Content-Type: text/plain; charset=CHARSET\n" "Content-Transfer-Encoding: ENCODING\n" @endcode - + Note this particular line: - + @code "Content-Type: text/plain; charset=CHARSET\n" @endcode - + It specifies the charset used by the catalog. All strings in the catalog are encoded using this charset. You have to fill in proper charset information. Your .po file may look like this - after doing so: - + after doing so: + @code # SOME DESCRIPTIVE TITLE. # Copyright (C) YEAR Free Software Foundation, Inc. @@ -76,7 +76,7 @@ "Content-Type: text/plain; charset=iso8859-2\n" "Content-Transfer-Encoding: 8bit\n" @endcode - + (Make sure that the header is @b not marked as @e fuzzy.) wxWidgets is able to use this catalog under any supported platform (although iso8859-2 is a Unix encoding and is normally not understood by @@ -97,25 +97,25 @@ in the source code to English and putting the original strings into message catalog, you may configure wxWidgets to use non-English msgids and translate to English using message catalogs: - - + + If you use the program @c xgettext to extract the strings from the source code, specify the option @c --from-code=source code charset. Specify the source code language and charset as arguments to wxLocale::AddCatalog. For example: - + @code locale.AddCatalog(_T("myapp"), wxLANGUAGE_GERMAN, _T("iso-8859-1")); @endcode - - - - + + + + @b Font mapping - You can use @ref mbconvclasses_overview and + You can use @ref mbconvclasses_overview and #wxFontMapper to display text: - + @code if (!wxFontMapper::Get()-IsEncodingAvailable(enc, facename)) { @@ -132,7 +132,7 @@ } ...display text... @endcode - + @b Converting data You may want to store all program data (created documents etc.) in the same encoding, let's say @c utf-8. You can use @@ -143,21 +143,21 @@ If you're using #wxHtmlHelpController there is no problem at all. You only need to make sure that all the HTML files contain the META tag, e.g. - + @code meta http-equiv="Content-Type" content="text/html; charset=iso8859-2" @endcode - + and that the hhp project file contains one additional line in the @c OPTIONS section: - + @code Charset=iso8859-2 @endcode - + This additional entry tells the HTML help controller what encoding is used in contents and index tables. - + */ - - + + diff --git a/docs/doxygen/overviews/printing.h b/docs/doxygen/overviews/printing.h index cddc7c476f..25b3c61305 100644 --- a/docs/doxygen/overviews/printing.h +++ b/docs/doxygen/overviews/printing.h @@ -7,18 +7,18 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page printing_overview Printing overview - - Classes: #wxPrintout, - #wxPrinter, - #wxPrintPreview, - #wxPrinterDC, - #wxPostScriptDC, - #wxPrintDialog, - #wxPrintData, - #wxPrintDialogData, - #wxPageSetupDialog, + + 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 @@ -42,10 +42,10 @@ @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 @@ -55,7 +55,7 @@ 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: { @@ -75,7 +75,7 @@ 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 @@ -96,24 +96,24 @@ 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 @@ -133,9 +133,9 @@ 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 @@ -144,17 +144,17 @@ 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, @@ -162,17 +162,17 @@ 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 @@ -183,9 +183,9 @@ 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 @@ -198,7 +198,7 @@ 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 df4beab878..2812ead7cd 100644 --- a/docs/doxygen/overviews/python.h +++ b/docs/doxygen/overviews/python.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page python_overview wxPython overview - + This topic was written by Robin Dunn, author of the wxPython wrapper. @ref pwhat_overview @ref pwhy_overview @@ -17,10 +17,10 @@ @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 @@ -53,9 +53,9 @@ 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 @@ -68,9 +68,9 @@ 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 @@ -107,9 +107,9 @@ 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. @@ -119,14 +119,14 @@ 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 * @@ -203,12 +203,12 @@ 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 @@ -255,17 +255,17 @@ 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 @@ -447,11 +447,11 @@ #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 @@ -461,7 +461,7 @@ #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 - + */ - - + + diff --git a/docs/doxygen/overviews/referencenotes.h b/docs/doxygen/overviews/referencenotes.h index ded0bdc1b5..fd7d631fbe 100644 --- a/docs/doxygen/overviews/referencenotes.h +++ b/docs/doxygen/overviews/referencenotes.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page referencenotes_overview Notes on using the reference - + In the descriptions of the wxWidgets classes and their member functions, note that descriptions of inherited member functions are not duplicated in derived classes unless their behaviour is different. So in @@ -26,7 +26,7 @@ used by wxWidgets. The member functions are given in alphabetical order except for constructors and destructors which appear first. - + */ - - + + diff --git a/docs/doxygen/overviews/resyn.h b/docs/doxygen/overviews/resyn.h index 2682f62068..505c3e8a43 100644 --- a/docs/doxygen/overviews/resyn.h +++ b/docs/doxygen/overviews/resyn.h @@ -7,11 +7,11 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page resyn_overview Syntax of the builtin regular expression library - + A @e regular expression describes strings of characters. It's a - pattern that matches certain strings and doesn't match others. + pattern that matches certain strings and doesn't match others. @b See also #wxRegEx @ref differentflavors_overview @@ -23,323 +23,323 @@ @ref relimits_overview @ref resynbre_overview @ref resynchars_overview - - + + @section differentflavors Different Flavors of REs - + @ref resyn_overview Regular expressions ("RE''s), as defined by POSIX, come in two flavors: @e extended REs ("EREs'') and @e basic REs ("BREs''). EREs are roughly those of the traditional @e egrep, while BREs are roughly those of the traditional @e ed. This implementation adds a third flavor, @e advanced REs ("AREs''), basically - EREs with some significant extensions. + EREs with some significant extensions. This manual page primarily describes AREs. BREs mostly exist for backward compatibility in some old programs; they will be discussed at the #end. POSIX EREs are almost an exact subset of AREs. Features of AREs that are not present in EREs will be indicated. - + @section resyntax Regular Expression Syntax - + @ref resyn_overview These regular expressions are implemented using the package written by Henry Spencer, based on the 1003.2 spec and some (not quite all) of the Perl5 extensions (thanks, Henry!). Much of the description - of regular expressions below is copied verbatim from his manual entry. + of regular expressions below is copied verbatim from his manual entry. An ARE is one or more @e branches, separated by '@b |', matching anything that matches - any of the branches. + any of the branches. A branch is zero or more @e constraints or @e quantified atoms, concatenated. It matches a match for the first, followed by a match - for the second, etc; an empty branch matches the empty string. + for the second, etc; an empty branch matches the empty string. A quantified atom is an @e atom possibly followed by a single @e quantifier. Without a quantifier, it matches a match for the atom. The quantifiers, and what a so-quantified atom matches, are: - - - - - - + + + + + + @b * - - - - + + + + a sequence of 0 or more matches of the atom - - - - - + + + + + @b + - - - - + + + + a sequence of 1 or more matches of the atom - - - - - + + + + + @b ? - - - - + + + + a sequence of 0 or 1 matches of the atom - - - - - + + + + + @b {m} - - - - + + + + a sequence of exactly @e m matches of the atom - - - - - + + + + + @b {m,} - - - - + + + + a sequence of @e m or more matches of the atom - - - - - + + + + + @b {m,n} - - - - + + + + a sequence of @e m through @e n (inclusive) matches of the atom; @e m may not exceed @e n - - - - - + + + + + @b *? +? ?? {m}? {m,}? {m,n}? - - - - + + + + @e non-greedy quantifiers, which match the same possibilities, but prefer the smallest number rather than the largest number of matches (see #Matching) - - - - - + + + + + The forms using @b { and @b } are known as @e bounds. The numbers @e m and @e n are unsigned - decimal integers with permissible values from 0 to 255 inclusive. + decimal integers with permissible values from 0 to 255 inclusive. An atom is one of: - - - - - - + + + + + + @b (re) - - - - + + + + (where @e re is any regular expression) matches a match for @e re, with the match noted for possible reporting - - - - - + + + + + @b (?:re) - - - - + + + + as previous, but does no reporting (a "non-capturing'' set of parentheses) - - - - - + + + + + @b () - - - - + + + + matches an empty string, noted for possible reporting - - - - - + + + + + @b (?:) - - - - + + + + matches an empty string, without reporting - - - - - + + + + + @b [chars] - - - - + + + + a @e bracket expression, matching any one of the @e chars (see @ref resynbracket_overview for more detail) - - - - - + + + + + @b . - - - - - matches any single character - - - - - + + + + + matches any single character + + + + + @b \k - - - - + + + + (where @e k is a non-alphanumeric character) matches that character taken as an ordinary character, e.g. \\ matches a backslash character - - - - - + + + + + @b \c - - - - + + + + where @e c is alphanumeric (possibly followed by other characters), an @e escape (AREs only), see #Escapes below - - - - - + + + + + @b { - - - - + + + + when followed by a character other than a digit, matches the left-brace character '@b {'; when followed by a digit, it is the beginning of a @e bound (see above) - - - - - + + + + + @b x - - - - + + + + where @e x is a single character with no other significance, matches that character. - - - - - + + + + + A @e constraint matches an empty string when specific conditions are met. A constraint may not be followed by a quantifier. The simple constraints are as follows; some more constraints are described later, under #Escapes. - - - - - - + + + + + + @b ^ - - - - + + + + matches at the beginning of a line - - - - - + + + + + @b $ - - - - + + + + matches at the end of a line - - - - - + + + + + @b (?=re) - - - - + + + + @e positive lookahead (AREs only), matches at any point where a substring matching @e re begins - - - - - + + + + + @b (?!re) - - - - + + + + @e negative lookahead (AREs only), matches at any point where no substring matching @e re begins - - - - - + + + + + The lookahead constraints may not contain back references (see later), and all parentheses within them are considered non-capturing. An RE may not end with '@b \'. - + @section wxresynbracket Bracket Expressions - + @ref resyn_overview A @e bracket expression is a list of characters enclosed in '@b []'. It normally matches any single character from the list (but see below). If the list begins with '@b ^', it matches any single - character (but see below) @e not from the rest of the list. + character (but see below) @e not from the rest of the list. If two characters in the list are separated by '@b -', this is shorthand for the full @e range of characters between those two (inclusive) in the collating sequence, e.g. @b [0-9] in ASCII matches any decimal digit. Two ranges may not share an endpoint, so e.g. @b a-c-e is illegal. Ranges are very collating-sequence-dependent, and portable - programs should avoid relying on them. + programs should avoid relying on them. To include a literal @b ] or @b - in the list, the simplest method is to enclose it in @b [. and @b .] to make it a collating element (see below). Alternatively, make it the first character (following @@ -349,7 +349,7 @@ @b - as the first endpoint of a range, make it a collating element or (AREs only) precede it with '@b \'. With the exception of these, some combinations using @b [ (see next paragraphs), and escapes, all other special characters lose - their special significance within a bracket expression. + their special significance within a bracket expression. Within a bracket expression, a collating element (a character, a multi-character sequence that collates as if it were a single character, or a collating-sequence @@ -365,153 +365,153 @@ is an equivalence class, standing for the sequences of characters of all collating elements equivalent to that one, including itself. An equivalence class may not be an endpoint of a range. - @e wxWidgets: Currently no equivalence classes are defined, so - @b [=X=] stands for just the single character @e X. + @e wxWidgets: Currently no equivalence classes are defined, so + @b [=X=] stands for just the single character @e X. @e X can either be a single character literal or the name of a character, see @ref resynchars_overview. Within a bracket expression, the name of a @e character class enclosed in @b [: and @b :] stands for the list of all characters (not all collating elements!) belonging to that class. Standard character classes are: - - - - - - + + + + + + @b alpha - - - - + + + + A letter. - - - - - + + + + + @b upper - - - - + + + + An upper-case letter. - - - - - + + + + + @b lower - - - - + + + + A lower-case letter. - - - - - + + + + + @b digit - - - - + + + + A decimal digit. - - - - - - @b xdigit - - - - - A hexadecimal digit. - - - - - - @b alnum - - - - + + + + + + @b xdigit + + + + + A hexadecimal digit. + + + + + + @b alnum + + + + An alphanumeric (letter or digit). - - - - - + + + + + @b print - - - - + + + + An alphanumeric (same as alnum). - - - - - + + + + + @b blank - - - - + + + + A space or tab character. - - - - - + + + + + @b space - - - - + + + + A character producing white space in displayed text. - - - - - + + + + + @b punct - - - - + + + + A punctuation character. - - - - - + + + + + @b graph - - - - + + + + A character with a visible representation. - - - - - + + + + + @b cntrl - - - - + + + + A control character. - - - - - - A character class may not be used as an endpoint of a range. + + + + + + A character class may not be used as an endpoint of a range. @e wxWidgets: In a non-Unicode build, these character classifications depend on the current locale, and correspond to the values return by the ANSI C 'is' functions: isalpha, isupper, etc. In Unicode mode they are based on @@ -522,10 +522,10 @@ as a sequence of word characters that is neither preceded nor followed by word characters. A word character is an @e alnum character or an underscore (@b _). These special bracket expressions are deprecated; users of AREs should - use constraint escapes instead (see #Escapes below). - + use constraint escapes instead (see #Escapes below). + @section wxresynescapes Escapes - + @ref resyn_overview Escapes (AREs only), which begin with a @b \ followed by an alphanumeric character, come in several @@ -535,411 +535,411 @@ a bracket expression, a @b \ followed by an alphanumeric character merely stands for that character as an ordinary character, and inside a bracket expression, @b \ is an ordinary character. (The latter is the one actual incompatibility - between EREs and AREs.) + between EREs and AREs.) Character-entry escapes (AREs only) exist to make it easier to specify non-printing and otherwise inconvenient characters in REs: - - - - - - + + + + + + @b \a - - - - + + + + alert (bell) character, as in C - - - - - + + + + + @b \b - - - - + + + + backspace, as in C - - - - - + + + + + @b \B - - - - + + + + synonym for @b \ to help reduce backslash doubling in some applications where there are multiple levels of backslash processing - - - - - + + + + + @b \c@e X - - - - + + + + (where X is any character) the character whose low-order 5 bits are the same as those of @e X, and whose other bits are all zero - - - - - + + + + + @b \e - - - - + + + + the character whose collating-sequence name is '@b ESC', or failing that, the character with octal value 033 - - - - - + + + + + @b \f - - - - + + + + formfeed, as in C - - - - - + + + + + @b \n - - - - + + + + newline, as in C - - - - - + + + + + @b \r - - - - + + + + carriage return, as in C - - - - - + + + + + @b \t - - - - + + + + horizontal tab, as in C - - - - - + + + + + @b \u@e wxyz - - - - + + + + (where @e wxyz is exactly four hexadecimal digits) the Unicode character @b U+@e wxyz in the local byte ordering - - - - - + + + + + @b \U@e stuvwxyz - - - - + + + + (where @e stuvwxyz is exactly eight hexadecimal digits) reserved for a somewhat-hypothetical Unicode extension to 32 bits - - - - - + + + + + @b \v - - - - + + + + vertical tab, as in C are all available. - - - - - + + + + + @b \x@e hhh - - - - + + + + (where @e hhh is any sequence of hexadecimal digits) the character whose hexadecimal value is @b 0x@e hhh (a single character no matter how many hexadecimal digits are used). - - - - - + + + + + @b \0 - - - - + + + + the character whose value is @b 0 - - - - - + + + + + @b \@e xy - - - - + + + + (where @e xy is exactly two octal digits, and is not a @e back reference (see below)) the character whose octal value is @b 0@e xy - - - - - + + + + + @b \@e xyz - - - - + + + + (where @e xyz is exactly three octal digits, and is not a back reference (see below)) the character whose octal value is @b 0@e xyz - - - - - + + + + + Hexadecimal digits are '@b 0'-'@b 9', '@b a'-'@b f', and '@b A'-'@b F'. Octal - digits are '@b 0'-'@b 7'. + digits are '@b 0'-'@b 7'. The character-entry escapes are always taken as ordinary characters. For example, @b \135 is @b ] in ASCII, but @b \135 does not terminate a bracket expression. Beware, however, that some applications (e.g., C compilers) interpret such sequences themselves before the regular-expression package gets to see them, which may require - doubling (quadrupling, etc.) the '@b \'. + doubling (quadrupling, etc.) the '@b \'. Class-shorthand escapes (AREs only) provide shorthands for certain commonly-used character classes: - - - - - - + + + + + + @b \d - - - - + + + + @b [[:digit:]] - - - - - + + + + + @b \s - - - - + + + + @b [[:space:]] - - - - - + + + + + @b \w - - - - + + + + @b [[:alnum:]_] (note underscore) - - - - - + + + + + @b \D - - - - + + + + @b [^[:digit:]] - - - - - + + + + + @b \S - - - - + + + + @b [^[:space:]] - - - - - + + + + + @b \W - - - - + + + + @b [^[:alnum:]_] (note underscore) - - - - - + + + + + Within bracket expressions, '@b \d', '@b \s', and '@b \w' lose their outer brackets, and '@b \D', '@b \S', and '@b \W' are illegal. (So, for example, @b [a-c\d] is equivalent to @b [a-c[:digit:]]. Also, @b [a-c\D], which is equivalent to - @b [a-c^[:digit:]], is illegal.) + @b [a-c^[:digit:]], is illegal.) A constraint escape (AREs only) is a constraint, matching the empty string if specific conditions are met, written as an escape: - - - - - - + + + + + + @b \A - - - - + + + + matches only at the beginning of the string (see #Matching, below, for how this differs from '@b ^') - - - - - + + + + + @b \m - - - - + + + + matches only at the beginning of a word - - - - - + + + + + @b \M - - - - + + + + matches only at the end of a word - - - - - + + + + + @b \y - - - - + + + + matches only at the beginning or end of a word - - - - - + + + + + @b \Y - - - - + + + + matches only at a point that is not the beginning or end of a word - - - - - + + + + + @b \Z - - - - + + + + matches only at the end of the string (see #Matching, below, for how this differs from '@b $') - - - - - + + + + + @b \@e m - - - - + + + + (where @e m is a nonzero digit) a @e back reference, see below - - - - - + + + + + @b \@e mnn - - - - + + + + (where @e m is a nonzero digit, and @e nn is some more digits, and the decimal value @e mnn is not greater than the number of closing capturing parentheses seen so far) a @e back reference, see below - - - - - + + + + + A word is defined as in the specification of @b [[::]] and @b [[::]] above. Constraint escapes are - illegal within bracket expressions. + illegal within bracket expressions. A back reference (AREs only) matches the same string matched by the parenthesized subexpression specified by the number, so that (e.g.) @b ([bc])\1 matches @b bb or @b cc but not '@b bc'. The subexpression must entirely precede the back reference in the RE. Subexpressions are numbered in the order of their leading parentheses. Non-capturing parentheses do not - define subexpressions. + define subexpressions. There is an inherent historical ambiguity between octal character-entry escapes and back references, which is resolved by heuristics, as hinted at above. A leading zero always indicates an octal @@ -947,10 +947,10 @@ taken as a back reference. A multi-digit sequence not starting with a zero is taken as a back reference if it comes after a suitable subexpression (i.e. the number is in the legal range for a back reference), and otherwise - is taken as octal. - + is taken as octal. + @section remetasyntax Metasyntax - + @ref resyn_overview In addition to the main syntax described above, there are some special forms and miscellaneous syntactic facilities available. @@ -958,155 +958,155 @@ means. However, this can be overridden by a @e director. If an RE of any flavor begins with '@b ***:', the rest of the RE is an ARE. If an RE of any flavor begins with '@b ***=', the rest of the RE is taken to be a literal string, with all - characters considered ordinary characters. + characters considered ordinary characters. An ARE may begin with @e embedded options: a sequence @b (?xyz) (where @e xyz is one or more alphabetic characters) specifies options affecting the rest of the RE. These supplement, and can override, any options specified by the application. The available option letters are: - - - - - - + + + + + + @b b - - - - + + + + rest of RE is a BRE - - - - - + + + + + @b c - - - - + + + + case-sensitive matching (usual default) - - - - - + + + + + @b e - - - - + + + + rest of RE is an ERE - - - - - + + + + + @b i - - - - + + + + case-insensitive matching (see #Matching, below) - - - - - + + + + + @b m - - - - + + + + historical synonym for @b n - - - - - + + + + + @b n - - - - + + + + newline-sensitive matching (see #Matching, below) - - - - - + + + + + @b p - - - - + + + + partial newline-sensitive matching (see #Matching, below) - - - - - + + + + + @b q - - - - + + + + rest of RE is a literal ("quoted'') string, all ordinary characters - - - - - + + + + + @b s - - - - + + + + non-newline-sensitive matching (usual default) - - - - - + + + + + @b t - - - - + + + + tight syntax (usual default; see below) - - - - - + + + + + @b w - - - - + + + + inverse partial newline-sensitive ("weird'') matching (see #Matching, below) - - - - - + + + + + @b x - - - - + + + + expanded syntax (see below) - - - - - + + + + + Embedded options take effect at the @b ) terminating the sequence. They are available only at the start of an ARE, and may not be - used later within it. + used later within it. In addition to the usual (@e tight) RE syntax, in which all characters are significant, there is an @e expanded syntax, available in AREs with the embedded @@ -1114,35 +1114,35 @@ all characters between a @b # and the following newline (or the end of the RE) are ignored, permitting paragraphing and commenting a complex RE. There are three exceptions to that basic rule: - - + + a white-space character or '@b #' preceded - by '@b \' is retained + by '@b \' is retained white space or '@b #' within a bracket expression is retained white space and comments are illegal within multi-character symbols like - the ARE '@b (?:' or the BRE '@b \(' - - + the ARE '@b (?:' or the BRE '@b \(' + + Expanded-syntax white-space characters are blank, tab, newline, and any character that belongs to the @e space character class. Finally, in an ARE, outside bracket expressions, the sequence '@b (?#ttt)' (where @e ttt is any text not containing a '@b )') is a comment, completely ignored. Again, this is not allowed between the characters of multi-character symbols like '@b (?:'. Such comments are more a historical artifact than a useful facility, - and their use is deprecated; use the expanded syntax instead. + and their use is deprecated; use the expanded syntax instead. @e None of these metasyntax extensions is available if the application (or an initial @b ***= director) has specified that the user's input be treated as a literal string - rather than as an RE. - + rather than as an RE. + @section wxresynmatching Matching - + @ref resyn_overview In the event that an RE could match more than one substring of a given string, the RE matches the one starting earliest in the string. If the RE could match more than one substring starting at that point, its choice is determined by its @e preference: either the longest - substring, or the shortest. + substring, or the shortest. Most atoms, and all constraints, have no preference. A parenthesized RE has the same preference (possibly none) as the RE. A quantified atom with quantifier @b {m} or @b {m}? has the same preference (possibly @@ -1151,15 +1151,15 @@ atom with other non-greedy quantifiers (including @b {m,n}? with @e m equal to @e n) prefers shortest match. A branch has the same preference as the first quantified atom in it which has a preference. An RE consisting of two or - more branches connected by the @b | operator prefers longest match. + more branches connected by the @b | operator prefers longest match. Subject to the constraints imposed by the rules for matching the whole RE, subexpressions also match the longest or shortest possible substrings, based on their preferences, with subexpressions starting earlier in the RE taking priority over ones starting later. Note that outer subexpressions thus take priority - over their component subexpressions. + over their component subexpressions. Note that the quantifiers @b {1,1} and @b {1,1}? can be used to force longest and shortest preference, respectively, - on a subexpression or a whole RE. + on a subexpression or a whole RE. Match lengths are measured in characters, not collating elements. An empty string is considered longer than no match at all. For example, @b bb* matches the three middle characters @@ -1167,40 +1167,40 @@ matches all ten characters of '@b weeknights', when @b (.*).* is matched against @b abc the parenthesized subexpression matches all three characters, and when @b (a*)* is matched against @b bc both the whole RE and the parenthesized subexpression - match an empty string. + match an empty string. If case-independent matching is specified, the effect is much as if all case distinctions had vanished from the alphabet. When an alphabetic that exists in multiple cases appears as an ordinary character outside a bracket expression, it is effectively transformed into a bracket expression containing both cases, so that @b x becomes '@b [xX]'. When it appears inside a bracket expression, all case counterparts of it are added to the - bracket expression, so that @b [x] becomes @b [xX] and @b [^x] becomes '@b [^xX]'. + bracket expression, so that @b [x] becomes @b [xX] and @b [^x] becomes '@b [^xX]'. If newline-sensitive matching is specified, @b . and bracket expressions using @b ^ will never match the newline character (so that matches will never cross newlines unless the RE explicitly arranges it) and @b ^ and @b $ will match the empty string after and before a newline respectively, in addition to matching at beginning and end of string respectively. ARE @b \A and @b \Z continue to match beginning - or end of string @e only. + or end of string @e only. If partial newline-sensitive matching is specified, this affects @b . and bracket expressions as with newline-sensitive matching, - but not @b ^ and '@b $'. + but not @b ^ and '@b $'. If inverse partial newline-sensitive matching is specified, this affects @b ^ and @b $ as with newline-sensitive matching, but not @b . and bracket - expressions. This isn't very useful but is provided for symmetry. - + expressions. This isn't very useful but is provided for symmetry. + @section relimits Limits And Compatibility - + @ref resyn_overview No particular limit is imposed on the length of REs. Programs intended to be highly portable should not employ REs longer than 256 bytes, - as a POSIX-compliant implementation can refuse to accept such REs. + as a POSIX-compliant implementation can refuse to accept such REs. The only feature of AREs that is actually incompatible with POSIX EREs is that @b \ does not lose its special significance inside bracket expressions. All other ARE features use syntax which is illegal or has undefined or unspecified effects in POSIX EREs; the @b *** syntax of directors likewise is outside - the POSIX syntax for both BREs and EREs. + the POSIX syntax for both BREs and EREs. Many of the ARE extensions are borrowed from Perl, but some have been changed to clean them up, and a few Perl extensions are not present. Incompatibilities of note include '@b \b', @@ -1208,29 +1208,29 @@ complemented bracket expressions to the things affected by newline-sensitive matching, the restrictions on parentheses and back references in lookahead constraints, and the longest/shortest-match (rather than first-match) matching - semantics. + semantics. The matching rules for REs containing both normal and non-greedy quantifiers have changed since early beta-test versions of this package. (The new rules are much simpler and cleaner, but don't work as hard at guessing - the user's real intentions.) + the user's real intentions.) Henry Spencer's original 1986 @e regexp package, still in widespread use, implemented an early version of today's EREs. There are four incompatibilities between @e regexp's near-EREs ('RREs' for short) and AREs. In roughly increasing order of significance: - - + + In AREs, @b \ followed by an alphanumeric character is either an escape or an error, while in RREs, it was just another way of writing the alphanumeric. This should not be a problem because there was no reason to write such - a sequence in RREs. + a sequence in RREs. @b { followed by a digit in an ARE is the beginning of a bound, while in RREs, @b { was always an ordinary character. Such sequences should be rare, and will often result in an error because following characters - will not look like a valid bound. + will not look like a valid bound. In AREs, @b \ remains a special character within '@b []', so a literal @b \ within @b [] must be written '@b \\'. @b \\ also gives a literal @b \ within @b [] in RREs, but only truly paranoid programmers routinely doubled - the backslash. + the backslash. AREs report the longest/shortest match for the RE, rather than the first found in a specified search order. This may affect some RREs which were written in the expectation that the first match would be reported. @@ -1238,12 +1238,12 @@ is obsolete (AREs examine all possible matches in parallel, and their performance is largely insensitive to their complexity) but cases where the search order was exploited to deliberately find a match which was @e not the longest/shortest - will need rewriting.) - - - + will need rewriting.) + + + @section wxresynbre Basic Regular Expressions - + @ref resyn_overview BREs differ from EREs in several respects. '@b |', '@b +', and @b ? are ordinary characters and there is no equivalent @@ -1259,1059 +1259,1059 @@ subexpression (after a possible leading '@b ^'). Finally, single-digit back references are available, and @b \ and @b \ are synonyms for @b [[::]] and @b [[::]] respectively; - no other escapes are available. - + no other escapes are available. + @section wxresynchars Regular Expression Character Names - + @ref resyn_overview Note that the character names are case sensitive. - - - - - - + + + + + + NUL - - - - + + + + '\0' - - - - - + + + + + SOH - - - - + + + + '\001' - - - - - + + + + + STX - - - - + + + + '\002' - - - - - + + + + + ETX - - - - + + + + '\003' - - - - - + + + + + EOT - - - - + + + + '\004' - - - - - + + + + + ENQ - - - - + + + + '\005' - - - - - + + + + + ACK - - - - + + + + '\006' - - - - - + + + + + BEL - - - - + + + + '\007' - - - - - + + + + + alert - - - - + + + + '\007' - - - - - + + + + + BS - - - - + + + + '\010' - - - - - + + + + + backspace - - - - + + + + '\b' - - - - - + + + + + HT - - - - + + + + '\011' - - - - - + + + + + tab - - - - + + + + '\t' - - - - - + + + + + LF - - - - + + + + '\012' - - - - - + + + + + newline - - - - + + + + '\n' - - - - - + + + + + VT - - - - + + + + '\013' - - - - - + + + + + vertical-tab - - - - + + + + '\v' - - - - - + + + + + FF - - - - + + + + '\014' - - - - - + + + + + form-feed - - - - + + + + '\f' - - - - - + + + + + CR - - - - + + + + '\015' - - - - - + + + + + carriage-return - - - - + + + + '\r' - - - - - + + + + + SO - - - - + + + + '\016' - - - - - + + + + + SI - - - - + + + + '\017' - - - - - + + + + + DLE - - - - + + + + '\020' - - - - - + + + + + DC1 - - - - + + + + '\021' - - - - - + + + + + DC2 - - - - + + + + '\022' - - - - - + + + + + DC3 - - - - + + + + '\023' - - - - - + + + + + DC4 - - - - + + + + '\024' - - - - - + + + + + NAK - - - - + + + + '\025' - - - - - + + + + + SYN - - - - + + + + '\026' - - - - - + + + + + ETB - - - - + + + + '\027' - - - - - + + + + + CAN - - - - + + + + '\030' - - - - - + + + + + EM - - - - + + + + '\031' - - - - - + + + + + SUB - - - - + + + + '\032' - - - - - + + + + + ESC - - - - + + + + '\033' - - - - - + + + + + IS4 - - - - + + + + '\034' - - - - - + + + + + FS - - - - + + + + '\034' - - - - - + + + + + IS3 - - - - + + + + '\035' - - - - - + + + + + GS - - - - + + + + '\035' - - - - - + + + + + IS2 - - - - + + + + '\036' - - - - - + + + + + RS - - - - + + + + '\036' - - - - - + + + + + IS1 - - - - + + + + '\037' - - - - - + + + + + US - - - - + + + + '\037' - - - - - + + + + + space - - - - + + + + ' ' - - - - - + + + + + exclamation-mark - - - - + + + + '!' - - - - - + + + + + quotation-mark - - - - + + + + '"' - - - - - + + + + + number-sign - - - - + + + + '#' - - - - - + + + + + dollar-sign - - - - + + + + '$' - - - - - + + + + + percent-sign - - - - + + + + '%' - - - - - + + + + + ampersand - - - - + + + + '' - - - - - + + + + + apostrophe - - - - + + + + '\'' - - - - - + + + + + left-parenthesis - - - - + + + + '(' - - - - - + + + + + right-parenthesis - - - - + + + + ')' - - - - - + + + + + asterisk - - - - + + + + '*' - - - - - + + + + + plus-sign - - - - + + + + '+' - - - - - + + + + + comma - - - - + + + + ',' - - - - - + + + + + hyphen - - - - + + + + '-' - - - - - + + + + + hyphen-minus - - - - + + + + '-' - - - - - + + + + + period - - - - + + + + '.' - - - - - + + + + + full-stop - - - - + + + + '.' - - - - - + + + + + slash - - - - + + + + '/' - - - - - + + + + + solidus - - - - + + + + '/' - - - - - + + + + + zero - - - - + + + + '0' - - - - - + + + + + one - - - - + + + + '1' - - - - - + + + + + two - - - - + + + + '2' - - - - - + + + + + three - - - - + + + + '3' - - - - - + + + + + four - - - - + + + + '4' - - - - - + + + + + five - - - - + + + + '5' - - - - - + + + + + six - - - - + + + + '6' - - - - - + + + + + seven - - - - + + + + '7' - - - - - + + + + + eight - - - - + + + + '8' - - - - - + + + + + nine - - - - + + + + '9' - - - - - + + + + + colon - - - - + + + + ':' - - - - - + + + + + semicolon - - - - + + + + ';' - - - - - + + + + + less-than-sign - - - - + + + + '' - - - - - + + + + + equals-sign - - - - + + + + '=' - - - - - + + + + + greater-than-sign - - - - + + + + '' - - - - - + + + + + question-mark - - - - + + + + '?' - - - - - + + + + + commercial-at - - - - + + + + '@' - - - - - + + + + + left-square-bracket - - - - + + + + '[' - - - - - + + + + + backslash - - - - + + + + '\' - - - - - + + + + + reverse-solidus - - - - + + + + '\' - - - - - + + + + + right-square-bracket - - - - + + + + ']' - - - - - + + + + + circumflex - - - - + + + + '^' - - - - - + + + + + circumflex-accent - - - - + + + + '^' - - - - - + + + + + underscore - - - - + + + + '_' - - - - - + + + + + low-line - - - - + + + + '_' - - - - - + + + + + grave-accent - - - - + + + + ''' - - - - - + + + + + left-brace - - - - + + + + '{' - - - - - + + + + + left-curly-bracket - - - - + + + + '{' - - - - - + + + + + vertical-line - - - - + + + + '|' - - - - - + + + + + right-brace - - - - + + + + '}' - - - - - + + + + + right-curly-bracket - - - - + + + + '}' - - - - - + + + + + tilde - - - - + + + + '~' - - - - - + + + + + DEL - - - - + + + + '\177' - + */ - - + + diff --git a/docs/doxygen/overviews/richtextctrl.h b/docs/doxygen/overviews/richtextctrl.h index 4993f630c7..cf7c1b2ddc 100644 --- a/docs/doxygen/overviews/richtextctrl.h +++ b/docs/doxygen/overviews/richtextctrl.h @@ -7,25 +7,25 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page richtextctrl_overview wxRichTextCtrl overview - + @b Major classes: #wxRichTextCtrl, #wxRichTextBuffer, #wxRichTextEvent @b Helper classes: #wxTextAttr, #wxRichTextRange - @b File handler classes: #wxRichTextFileHandler, #wxRichTextHTMLHandler, + @b File handler classes: #wxRichTextFileHandler, #wxRichTextHTMLHandler, #wxRichTextXMLHandler - @b Style classes: #wxRichTextCharacterStyleDefinition, - #wxRichTextParagraphStyleDefinition, - #wxRichTextListStyleDefinition, + @b Style classes: #wxRichTextCharacterStyleDefinition, + #wxRichTextParagraphStyleDefinition, + #wxRichTextListStyleDefinition, #wxRichTextStyleSheet - @b Additional controls: #wxRichTextStyleComboCtrl, - #wxRichTextStyleListBox, + @b Additional controls: #wxRichTextStyleComboCtrl, + #wxRichTextStyleListBox, #wxRichTextStyleListCtrl - @b Printing classes: #wxRichTextPrinting, - #wxRichTextPrintout, + @b Printing classes: #wxRichTextPrinting, + #wxRichTextPrintout, #wxRichTextHeaderFooterData - @b Dialog classes: #wxRichTextStyleOrganiserDialog, - #wxRichTextFormattingDialog, + @b Dialog classes: #wxRichTextStyleOrganiserDialog, + #wxRichTextFormattingDialog, #wxSymbolPickerDialog wxRichTextCtrl provides a generic implementation of a rich text editor that can handle different character styles, paragraph formatting, and images. It's aimed at editing 'natural' language text - if you need an editor @@ -58,62 +58,62 @@ former case. A good way to understand wxRichTextCtrl's capabilities is to compile and run the sample, @c samples/richtext, and browse the code. The following screenshot shows the sample in action: - + @b Example The following code is taken from the sample, and adds text and styles to a rich text control programmatically. - - + + @code wxRichTextCtrl* richTextCtrl = new wxRichTextCtrl(splitter, wxID_ANY, wxEmptyString, wxDefaultPosition, wxSize(200, 200), wxVSCROLL|wxHSCROLL|wxBORDER_NONE|wxWANTS_CHARS); - + wxFont textFont = wxFont(12, wxROMAN, wxNORMAL, wxNORMAL); wxFont boldFont = wxFont(12, wxROMAN, wxNORMAL, wxBOLD); wxFont italicFont = wxFont(12, wxROMAN, wxITALIC, wxNORMAL); - + wxFont font(12, wxROMAN, wxNORMAL, wxNORMAL); - + m_richTextCtrl-SetFont(font); - + wxRichTextCtrl& r = richTextCtrl; - + r.BeginSuppressUndo(); - + r.BeginParagraphSpacing(0, 20); - + r.BeginAlignment(wxTEXT_ALIGNMENT_CENTRE); r.BeginBold(); - + r.BeginFontSize(14); r.WriteText(wxT("Welcome to wxRichTextCtrl, a wxWidgets control for editing and presenting styled text and images")); r.EndFontSize(); r.Newline(); - + r.BeginItalic(); r.WriteText(wxT("by Julian Smart")); r.EndItalic(); - + r.EndBold(); - + r.Newline(); r.WriteImage(wxBitmap(zebra_xpm)); - + r.EndAlignment(); - + r.Newline(); r.Newline(); - + r.WriteText(wxT("What can you do with this thing? ")); r.WriteImage(wxBitmap(smiley_xpm)); r.WriteText(wxT(" Well, you can change text ")); - + r.BeginTextColour(wxColour(255, 0, 0)); r.WriteText(wxT("colour, like this red bit.")); r.EndTextColour(); - + r.BeginTextColour(wxColour(0, 0, 255)); r.WriteText(wxT(" And this blue bit.")); r.EndTextColour(); - + r.WriteText(wxT(" Naturally you can make things ")); r.BeginBold(); r.WriteText(wxT("bold ")); @@ -124,57 +124,57 @@ r.BeginUnderline(); r.WriteText(wxT("or underlined.")); r.EndUnderline(); - + r.BeginFontSize(14); r.WriteText(wxT(" Different font sizes on the same line is allowed, too.")); r.EndFontSize(); - + r.WriteText(wxT(" Next we'll show an indented paragraph.")); - + r.BeginLeftIndent(60); r.Newline(); - + r.WriteText(wxT("Indented paragraph.")); r.EndLeftIndent(); - + r.Newline(); - + r.WriteText(wxT("Next, we'll show a first-line indent, achieved using BeginLeftIndent(100, -40).")); - + r.BeginLeftIndent(100, -40); r.Newline(); - + r.WriteText(wxT("It was in January, the most down-trodden month of an Edinburgh winter.")); r.EndLeftIndent(); - + r.Newline(); - + r.WriteText(wxT("Numbered bullets are possible, again using subindents:")); - + r.BeginNumberedBullet(1, 100, 60); r.Newline(); - + r.WriteText(wxT("This is my first item. Note that wxRichTextCtrl doesn't automatically do numbering, but this will be added later.")); r.EndNumberedBullet(); - + r.BeginNumberedBullet(2, 100, 60); r.Newline(); - + r.WriteText(wxT("This is my second item.")); r.EndNumberedBullet(); - + r.Newline(); - + r.WriteText(wxT("The following paragraph is right-indented:")); - + r.BeginRightIndent(200); r.Newline(); - + r.WriteText(wxT("It was in January, the most down-trodden month of an Edinburgh winter. An attractive woman came into the cafe, which is nothing remarkable.")); r.EndRightIndent(); - + r.Newline(); - + wxArrayInt tabs; tabs.Add(400); tabs.Add(600); @@ -184,42 +184,42 @@ attr.SetFlags(wxTEXT_ATTR_TABS); attr.SetTabs(tabs); r.SetDefaultStyle(attr); - + r.WriteText(wxT("This line contains tabs:\tFirst tab\tSecond tab\tThird tab")); - + r.Newline(); r.WriteText(wxT("Other notable features of wxRichTextCtrl include:")); - + r.BeginSymbolBullet(wxT('*'), 100, 60); r.Newline(); r.WriteText(wxT("Compatibility with wxTextCtrl API")); r.EndSymbolBullet(); - + r.WriteText(wxT("Note: this sample content was generated programmatically from within the MyFrame constructor in the demo. The images were loaded from inline XPMs. Enjoy wxRichTextCtrl!")); - + r.EndSuppressUndo(); @endcode - - + + @ref topic19_overview @ref richtextctrldialogs_overview @ref topic22_overview @ref topic23_overview - - + + @section topic19 Programming with wxRichTextCtrl - - + + @section topic20 Starting to use wxRichTextCtrl - + You need to include @c wx/richtext/richtextctrl.h in your source, and link with the appropriate wxWidgets library with @c richtext suffix. Put the rich text library first in your link line to avoid unresolved symbols. Then you can create a wxRichTextCtrl, with the wxWANT_CHARS style if you want tabs to be processed by the control rather than being used for navigation between controls. - + @section topic21 wxRichTextCtrl and styles - + Styling attributes are represented by #wxTextAttr. When setting a style, the flags of the attribute object determine which attributes are applied. When querying a style, the passed flags are ignored @@ -229,8 +229,8 @@ the content may be responsible for contributing different attributes to the final style you see on the screen. There are four main notions of style within a control: - - + + @b Basic style: the fundamental style of a control, onto which any other styles are layered. It provides default attributes, and changing the basic style may immediately change the look of the content depending on what other styles @@ -244,20 +244,20 @@ to wxRichTextCtrl::SetStyleEx. @b Character style: characters within each paragraph can have attributes. A single character, or a run of characters, can have a particular set of attributes. - The character style can be with wxRichTextCtrl::SetStyle or + The character style can be with wxRichTextCtrl::SetStyle or wxRichTextCtrl::SetStyleEx. @b Default style: this is the 'current' style that determines the style of content that is subsequently typed, pasted or programmatically inserted. The default style is set with wxRichTextCtrl::SetDefaultStyle. - - + + What you see on the screen is the dynamically @e combined style, found by merging the first three of the above style types (the fourth is only a guide for future content insertion and therefore does not affect the currently displayed content). To make all this more concrete, here are examples of where you might set these different styles: - - + + You might set the @b basic style to have a Times Roman font in 12 point, left-aligned, with two millimetres of spacing after each paragraph. You might set the @b paragraph style (for one particular paragraph) to @@ -265,14 +265,14 @@ You might set the @b character style of one particular word to bold. You might set the @b default style to be underlined, for subsequent inserted text. - - + + Naturally you can do any of these things either using your own UI, or programmatically. The basic wxTextCtrl doesn't make the same distinctions as wxRichTextCtrl regarding attribute storage. So we need finer control when setting and retrieving attributes. wxRichTextCtrl::SetStyleEx takes a @e flags parameter: - - + + wxRICHTEXT_SETSTYLE_OPTIMIZE specifies that the style should be changed only if the combined attributes are different from the attributes for the current object. This is important when applying styling that has been edited by the user, because he has just edited the @e combined (visible) @@ -283,8 +283,8 @@ wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY specifies that only content objects (text or images) within the given range should take on the attributes. wxRICHTEXT_SETSTYLE_WITH_UNDO specifies that the operation should be undoable. - - + + It's great to be able to change arbitrary attributes in a wxRichTextCtrl, but it can be unwieldy for the user or programmer to set attributes separately. Word processors have collections of styles that you can tailor or use as-is, and this means that you can set a heading with one click @@ -301,9 +301,9 @@ It relies on the fact that when you apply a named style, the style definition name is recorded in the content. So ApplyStyleSheet works by finding the paragraph attributes with style names and re-applying the definition's attributes to the paragraph. Currently, this works with paragraph and list style definitions only. - + @section wxrichtextctrldialogs wxRichTextCtrl dialogs - + wxRichTextCtrl comes with standard dialogs to make it easier to implement text editing functionality. #wxRichTextFormattingDialog can be used @@ -323,9 +323,9 @@ #wxSymbolPickerDialog lets the user insert a symbol from a specified font. It has no wxRichTextCtrl dependencies besides being included in the rich text library. - + @section topic22 How wxRichTextCtrl is implemented - + Data representation is handled by wxRichTextBuffer, and a wxRichTextCtrl always has one such buffer. The content is represented by a hierarchy of objects, all derived from @@ -357,25 +357,25 @@ to several objects with the same style where just one would do. So a Defragment function is called when updating the control's display, to ensure that the minimum number of objects is used. - + @section topic23 wxRichTextCtrl roadmap - + @b Bugs This is an incomplete list of bugs. - - + + Moving the caret up at the beginning of a line sometimes incorrectly positions the caret. As the selection is expanded, the text jumps slightly due to kerning differences between drawing a single text string versus drawing several fragments separately. This could be improved by using wxDC::GetPartialTextExtents to calculate exactly where the separate fragments should be drawn. Note that this problem also applies to separation of text fragments due to difference in their attributes. - - + + @b Features This is a list of some of the features that have yet to be implemented. Help with them will be appreciated. - - + + RTF input and output Conversion from HTML Open Office input and output @@ -387,12 +387,12 @@ Borders Text frames Justified text, in print/preview at least - - + + There are also things that could be done to take advantage of the underlying text capabilities of the platform; higher-level text formatting APIs are available on some platforms, such as Mac OS X, and some of translation from high level to low level wxDC API is unnecessary. However this would require additions to the wxWidgets API. - + */ - - + + diff --git a/docs/doxygen/overviews/roughguide.h b/docs/doxygen/overviews/roughguide.h index e26b4bc431..535367e209 100644 --- a/docs/doxygen/overviews/roughguide.h +++ b/docs/doxygen/overviews/roughguide.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page roughguide_overview Writing a wxWidgets application: a rough guide - + To set a wxWidgets application going, you will need to derive a #wxApp class and override wxApp::OnInit. An application must have a top-level #wxFrame or #wxDialog window. @@ -48,7 +48,7 @@ and you may find it handy to maintain and search a list of paths using #wxPathList. There's a #miscellany of operating system and other functions. See also @ref classesbycat_overview for a list of classes. - + */ - - + + diff --git a/docs/doxygen/overviews/runtimeclass.h b/docs/doxygen/overviews/runtimeclass.h index fc15b6844d..34ca224893 100644 --- a/docs/doxygen/overviews/runtimeclass.h +++ b/docs/doxygen/overviews/runtimeclass.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page runtimeclass_overview Runtime class information (aka RTTI) overview - + Classes: #wxObject, #wxClassInfo. One of the failings of C++ used to be that no run-time information was provided about a class and its position in the inheritance hierarchy. @@ -54,58 +54,58 @@ can simply call wxClassInfo::CreateObject. #wxClassInfo #Example - - + + @section wxclassinfooverview wxClassInfo - + #Runtime class information (aka RTTI) overview Class: #wxClassInfo This class stores meta-information about classes. An application may use macros such as DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS to record run-time information about a class, including: - - + + its position in the inheritance hierarchy; the base class name(s) (up to two base classes are permitted); a string representation of the class name; a function that can be called to construct an instance of this class. - - + + The DECLARE_... macros declare a static wxClassInfo variable in a class, which is initialized by macros of the form IMPLEMENT_... in the implementation C++ file. Classes whose instances may be constructed dynamically are given a global constructor function which returns a new object. 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. See also #wxObject and #wxCreateDynamicObject. - + @section runtimeclassinformationexample Example - + In a header file frame.h: - + @code class wxFrame : public wxWindow { DECLARE_DYNAMIC_CLASS(wxFrame) - + private: wxString m_title; - + public: ... }; @endcode - + In a C++ file frame.cpp: - + @code IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) - + wxFrame::wxFrame() { ... } @endcode - + */ - - + + diff --git a/docs/doxygen/overviews/samples.h b/docs/doxygen/overviews/samples.h index e882069d24..24b4f94743 100644 --- a/docs/doxygen/overviews/samples.h +++ b/docs/doxygen/overviews/samples.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page samples_overview wxWidgets samples - + Probably the best way to learn wxWidgets is by reading the source of some 50+ samples provided with it. Many aspects of wxWidgets programming can be learnt from them, but sometimes it is not simple to just choose the right sample to @@ -27,60 +27,60 @@ generic controls, such as buttons, listboxes, checkboxes, comboboxes etc. Other, more complicated controls, have their own samples. In this category you may find the following samples showing the corresponding controls: - - - - - - + + + + + + #wxCalendarCtrl - - - - + + + + Calendar a.k.a. date picker control - - - - - + + + + + #wxListCtrl - - - - + + + + List view control - - - - - + + + + + #wxTreeCtrl - - - - + + + + Tree view control - - - - - + + + + + #wxGrid - - - - + + + + Grid control - - - - - + + + + + Finally, it might be helpful to do a search in the entire sample directory if you can't find the sample showing the control you are interested in by name. Most classes contained in wxWidgets occur in at least one of the samples. - + @ref sampleminimal_overview @ref sampleanimate_overview @ref sampleartprovider_overview @@ -115,49 +115,49 @@ @ref sampletreectrl_overview @ref samplewidgets_overview @ref samplewizard_overview - - + + @section sampleminimal Minimal sample - + The minimal sample is what most people will know under the term Hello World, i.e. a minimal program that doesn't demonstrate anything apart from what is needed to write a program that will display a "hello" dialog. This is usually a good starting point for learning how to use wxWidgets. - - + + @section sampleanimate Animate sample - + The @c animate sample shows how you can use #wxAnimationCtrl control and shows concept of a platform-dependent animation encapsulated in #wxAnimation. - - + + @section sampleartprovider Art provider sample - + The @c artprov sample shows how you can customize the look of standard wxWidgets dialogs by replacing default bitmaps/icons with your own versions. It also shows how you can use wxArtProvider to get stock bitmaps for use in your application. - - + + @section samplecalendar Calendar sample - + This font shows the @ref calendarctrl_overview in action. It shows how to configure the control (see the different options in the calendar menu) and also how to process the notifications from it. - - + + @section sampleconfig Config sample - + This sample demonstrates the #wxConfig classes in a platform independent way, i.e. it uses text based files to store a given configuration under Unix and uses the Registry under Windows. See @ref config_overview for the descriptions of all features of this class. - - + + @section samplecontrols Controls sample - + The controls sample is the main test program for most simple controls used in wxWidgets. The sample tests their basic functionality, events, placement, modification in terms of colour and font as well as the possibility to change @@ -168,181 +168,181 @@ notebook pages, advancing pages programmatically and vetoing a page change by intercepting the #wxNotebookEvent. The various controls tested are listed here: - - - - - - + + + + + + #wxButton - - - - + + + + Push button control, displaying text - - - - - + + + + + #wxBitmapButton - - - - + + + + Push button control, displaying a bitmap - - - - - + + + + + #wxCheckBox - - - - + + + + Checkbox control - - - - - + + + + + #wxChoice - - - - + + + + Choice control (a combobox without the editable area) - - - - - + + + + + #wxComboBox - - - - + + + + A choice with an editable area - - - - - + + + + + #wxGauge - - - - + + + + A control to represent a varying quantity, such as time remaining - - - - - + + + + + #wxStaticBox - - - - + + + + A static, or group box for visually grouping related controls - - - - - + + + + + #wxListBox - - - - + + + + A list of strings for single or multiple selection - - - - - + + + + + wxSpinCtrl - - - - + + + + A spin ctrl with a text field and a 'up-down' control - - - - - + + + + + #wxSpinButton - - - - + + + + A spin or 'up-down' control - - - - - + + + + + #wxStaticText - - - - + + + + One or more lines of non-editable text - - - - - + + + + + #wxStaticBitmap - - - - + + + + A control to display a bitmap - - - - - + + + + + #wxRadioBox - - - - + + + + A group of radio buttons - - - - - + + + + + #wxRadioButton - - - - + + + + A round button to be used with others in a mutually exclusive way - - - - - + + + + + #wxSlider - - - - + + + + A slider that can be dragged by the user - - - - - - - + + + + + + + @section sampledebugrpt DebugRpt sample - + This sample shows how to use #wxDebugReport class to generate a debug report in case of a program crash or otherwise. On start up, it proposes to either crash itself (by dereferencing a @NULL pointer) or @@ -353,16 +353,16 @@ For the report processing part of the sample to work you should make available a Web server accepting form uploads, otherwise #wxDebugReportUpload will report an error. - - + + @section sampledialogs Dialogs sample - + This sample shows how to use the common dialogs available from wxWidgets. These dialogs are described in detail in the @ref commondialogs_overview. - - + + @section sampledialup Dialup sample - + This sample shows the #wxDialUpManager class. In the status bar, it displays the information gathered through its interface: in particular, the current connection status (online or offline) and @@ -372,10 +372,10 @@ Using the menu entries, you may also dial or hang up the line if you have a modem attached and (this only makes sense for Windows) list the available connections. - - + + @section samplednd DnD sample - + This sample shows both clipboard and drag and drop in action. It is quite non trivial and may be safely used as a basis for implementing the clipboard and drag and drop operations in a real-life program. @@ -406,19 +406,19 @@ programs as well - try Write/Wordpad, for example). Take a look at DnDShapeDataObject class to see how you may use #wxDataObject to achieve this. - - + + @section sampleevent Event sample - + The event sample demonstrates various features of the wxWidgets events. It shows using dynamic events and connecting/disconnecting the event handlers during run time and also using #PushEventHandler() and #PopEventHandler(). - - + + @section sampleexcept Except(ions) sample - + This very simple sample shows how to use C++ exceptions in wxWidgets programs, i.e. where to catch the exception which may be thrown by the program code. It doesn't do anything very exciting by itself, you need to study its code to @@ -426,10 +426,10 @@ You need to build the library with @c wxUSE_EXCEPTIONS being set to 1 and compile your code with C++ exceptions support to be able to build this sample. - - + + @section sampleexec Exec sample - + The exec sample demonstrates the #wxExecute and #wxShell functions. Both of them are used to execute the external programs and the sample shows how to do this synchronously (waiting @@ -438,24 +438,24 @@ synchronous and asynchronous cases and how to kill the processes with wxProcess::Kill and test for their existence with wxProcess::Exists. - - + + @section samplefont Font sample - + The font sample demonstrates #wxFont, #wxFontEnumerator and #wxFontMapper classes. It allows you to see the fonts available (to wxWidgets) on the computer and shows all characters of the chosen font as well. - - + + @section samplegrid Grid sample - + TODO. - - + + @section samplehtml HTML samples - + Eight HTML samples (you can find them in directory @c samples/html) cover all features of the HTML sub-library. @b Test demonstrates how to create #wxHtmlWindow @@ -477,10 +477,10 @@ #wxHtmlHelpController in your application while @e Helpview is a simple tool that only pops up the help window and displays help books given at command line. - - + + @section sampleimage Image sample - + The image sample demonstrates use of the #wxImage class and shows how to download images in a variety of formats, currently PNG, GIF, TIFF, JPEG, BMP, PNM and PCX. The top of the sample shows two rectangles, one @@ -497,10 +497,10 @@ replaced with red using wxImage::Replace. This sample also contains the code for testing the image rotation and resizing and using raw bitmap access, see the corresponding menu commands. - - + + @section sampleinternat Internat(ionalization) sample - + The not very clearly named internat sample demonstrates the wxWidgets internationalization (i18n for short from now on) features. To be more precise, it only shows localization support, i.e. support for translating the @@ -508,10 +508,10 @@ changing the other aspects of the programs behaviour. More information about this sample can be found in the @c readme.txt file in its directory. Please see also @ref internationalization_overview. - - + + @section samplelayout Layout sample - + The layout sample demonstrates the two different layout systems offered by wxWidgets. When starting the program, you will see a frame with some controls and some graphics. The controls will change their size whenever @@ -524,43 +524,43 @@ a #wxBoxSizer in a simple dialog and the other one showing how to use sizers in connection with a #wxNotebook class. See also #wxSizer. - - + + @section samplelistctrl Listctrl sample - + This sample shows the #wxListCtrl control. Different modes supported by the control (list, icons, small icons, report) may be chosen from the menu. The sample also provides some timings for adding/deleting/sorting a lot of (several thousands) items into the control. - - + + @section samplemediaplayer Mediaplayer sample - + This sample demonstrates how to use all the features of #wxMediaCtrl and play various types of sound, video, and other files. - + It replaces the old dynamic sample. - + @section samplenotebook Notebook sample - + This samples shows #wxBookCtrl family of controls. Although initially it was written to demonstrate #wxNotebook only, it can now be also used to see #wxListbook, #wxChoicebook and #wxTreebook in action. Test each of the controls, their orientation, images and pages using commands through menu. - - + + @section samplerender Render sample - + This sample shows how to replace the default wxWidgets #renderer and also how to write a shared library (DLL) implementing a renderer and load and unload it during the run-time. - - + + @section samplescrollsub Scroll subwindow sample - + This sample demonstrates use of the #wxScrolledWindow class including placing subwindows into it and drawing simple graphics. It uses the #SetTargetWindow method and thus the effect @@ -569,10 +569,10 @@ in particular using the wxWindow::IsExposed method with the aim to prevent unnecessary drawing in the window and thus reducing or removing flicker on screen. - - + + @section samplesockets Sockets sample - + The sockets sample demonstrates how to use the communication facilities provided by #wxSocket. There are two different applications in this sample: a server, which is implemented using a @@ -610,46 +610,46 @@ There is also a URL test which shows how to use the #wxURL class to fetch data from a given URL. The sockets sample is work in progress. Some things to do: - - + + More tests for basic socket functionality. More tests for protocol classes (wxProtocol and its descendants). Tests for the recently added (and still in alpha stage) datagram sockets. New samples which actually do something useful (suggestions accepted). - - - - + + + + @section samplesound Sound sample - + The @c sound sample shows how to use #wxSound for simple audio output (e.g. notifications). - - + + @section samplestatbar Statbar sample - + This sample shows how to create and use wxStatusBar. Although most of the samples have a statusbar, they usually only create a default one and only do it once. Here you can see how to recreate the statusbar (with possibly different number of fields) and how to use it to show icons/bitmaps and/or put arbitrary controls into it. - - + + @section sampletaborder Tab order sample - - This sample allows to test keyboard navigation (mostly done using the + + This sample allows to test keyboard navigation (mostly done using the @c TAB key, hence the sample name) between different controls. - It shows the use of - wxWindow::MoveBeforeInTabOrder() and + It shows the use of + wxWindow::MoveBeforeInTabOrder() and #MoveAfterInTabOrder() methods to change - the default order of the windows in the navigation chain and of + the default order of the windows in the navigation chain and of wxWindow::Navigate() for moving focus along this chain. - - + + @section sampletext Text sample - + This sample demonstrates four features: firstly the use and many variants of the #wxTextCtrl class (single line, multi line, read only, password, ignoring TAB, ignoring ENTER). @@ -665,10 +665,10 @@ best known from pasting text to the XTerm program. Last not least: some of the text controls have tooltips and the sample also shows how tooltips can be centrally disabled and their latency controlled. - - + + @section samplethread Thread sample - + This sample demonstrates use of threads in connection with GUI programs. There are two fundamentally different ways to use threads in GUI programs and either way has to take care of the fact that the GUI library itself usually @@ -684,14 +684,14 @@ and #wxMutexGuiLeave functions, both of which are used and tested in the sample as well. See also @ref thread_overview and #wxThread. - - + + @section sampletoolbar Toolbar sample - + The toolbar sample shows the #wxToolBar class in action. The following things are demonstrated: - - + + Creating the toolbar using wxToolBar::AddTool and wxToolBar::AddControl: see MyApp::InitToolbar in the sample. @@ -701,8 +701,8 @@ Using wxToolBar::DeleteTool and wxToolBar::InsertTool to dynamically update the toolbar. - - + + Some buttons in the main toolbar are check buttons, i.e. they stay checked when pressed. On the platforms which support it, the sample also adds a combobox to the toolbar showing how you can use arbitrary controls and not only buttons @@ -711,10 +711,10 @@ see the radio toolbar buttons in action: the first three buttons form a radio group, i.e. checking any of them automatically unchecks the previously checked one. - - + + @section sampletreectrl Treectrl sample - + This sample demonstrates using the #wxTreeCtrl class. Here you may see how to process various notification messages sent by this control and also when they occur (by looking at the messages in the text control in @@ -722,24 +722,24 @@ Adding, inserting and deleting items and branches from the tree as well as sorting (in default alphabetical order as well as in custom one) is demonstrated here as well - try the corresponding menu entries. - - + + @section samplewidgets Widgets sample - + The widgets sample is the main presentation program for most simple and advanced native controls and complex generic widgets provided by wxWidgets. The sample tests their basic functionality, events, placement, modification in terms of colour and font as well as the possibility to change the controls programmatically, such as adding an item to a list box etc. All widgets are categorized for easy browsing. - + @section samplewizard Wizard sample - + This sample shows the so-called wizard dialog (implemented using #wxWizard and related classes). It shows almost all features supported: - - + + Using bitmaps with the wizard and changing them depending on the page shown (notice that wxValidationPage in the sample has a different image from the other ones) @@ -754,7 +754,7 @@ but sometimes it depends on the user choices: wxCheckboxPage shows how to dynamically decide which page to display next (see also #wxWizardPage) - + */ - - + + diff --git a/docs/doxygen/overviews/scrolling.h b/docs/doxygen/overviews/scrolling.h index ddc732e8e3..647196f861 100644 --- a/docs/doxygen/overviews/scrolling.h +++ b/docs/doxygen/overviews/scrolling.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page scrolling_overview Scrolling overview - + Classes: #wxWindow, #wxScrolledWindow, #wxIcon, #wxScrollBar. Scrollbars come in various guises in wxWidgets. All windows have the potential to show a vertical scrollbar and/or a horizontal scrollbar: it is a basic capability of a window. @@ -33,66 +33,66 @@ @b The scrollbar model The function wxWindow::SetScrollbar gives a clue about the way a scrollbar is modeled. This function takes the following arguments: - - - - - - + + + + + + orientation - - - - + + + + Which scrollbar: wxVERTICAL or wxHORIZONTAL. - - - - - + + + + + position - - - - + + + + The position of the scrollbar in scroll units. - - - - - + + + + + visible - - - - + + + + The size of the visible portion of the scrollbar, in scroll units. - - - - - + + + + + range - - - - + + + + The maximum position of the scrollbar. - - - - - + + + + + refresh - - - - + + + + Whether the scrollbar should be repainted. - - - - + + + + @e orientation determines whether we're talking about the built-in horizontal or vertical scrollbar. @e position is simply the position of the 'thumb' (the bit you drag to scroll around). @@ -110,12 +110,12 @@ Let's say you wish to display 50 lines of text, using the same font. The window is sized so that you can only see 16 lines at a time. You would use: - + @code SetScrollbar(wxVERTICAL, 0, 16, 50); @endcode - - + + Note that with the window at this size, the thumb position can never go above 50 minus 16, or 34. You can determine how many lines are currently visible by dividing the current view @@ -125,7 +125,7 @@ scrollbar calculations and SetScrollbar call into a function named AdjustScrollbars, which can be called initially and also from your #wxSizeEvent handler function. - + */ - - + + diff --git a/docs/doxygen/overviews/sizer.h b/docs/doxygen/overviews/sizer.h index 07f3ee30eb..b6eeca0f7e 100644 --- a/docs/doxygen/overviews/sizer.h +++ b/docs/doxygen/overviews/sizer.h @@ -7,12 +7,12 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page sizer_overview Sizer overview - - Classes: #wxSizer, #wxGridSizer, - #wxFlexGridSizer, #wxBoxSizer, - #wxStaticBoxSizer, + + Classes: #wxSizer, #wxGridSizer, + #wxFlexGridSizer, #wxBoxSizer, + #wxStaticBoxSizer, #CreateButtonSizer Sizers, as represented by the wxSizer class and its descendants in the wxWidgets class hierarchy, have become the method of choice to @@ -32,10 +32,10 @@ @ref flexgridsizerprogramming_overview @ref staticboxsizerprogramming_overview #CreateButtonSizer - - + + @section ideabehindsizers The idea behind sizers - + The layout algorithm used by sizers in wxWidgets is closely related to layout systems in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit. It is based upon the idea of individual subwindows reporting their minimal required @@ -57,9 +57,9 @@ such as wrapping a static box around a dialog item (or another sizer). These sizers will be discussed one by one in the text below. For more detailed information on how to use sizers programmatically, please refer to the section @ref boxsizerprogramming_overview. - + @section sizerscommonfeatures Common features - + All sizers are containers, that is, they are used to lay out one dialog item (or several dialog items), which they contain. Such items are sometimes referred to as the children of the sizer. Independent of how the individual sizers lay out their children, all children @@ -71,26 +71,26 @@ calculate their size (such as a checkbox) whereas others (such as a listbox) don't have any natural width or height and thus require an explicit size. Some controls can calculate their height, but not their width (e.g. a single line text control): - - - - - - - - + + + + + + + + @b A border: The border is just empty space and is used to separate dialog items in a dialog. This border can either be all around, or at any combination of sides such as only above and below the control. The thickness of this border must be set explicitly, typically 5 points. The following samples show dialogs with only one dialog item (a button) and a border of 0, 5, and 10 pixels around the button: - - - - - - - + + + + + + + @b An alignment: Often, a dialog item is given more space than its minimal size plus its border. Depending on what flags are used for the respective dialog item, the dialog item can be made to fill out the available space entirely, i.e. @@ -98,9 +98,9 @@ the centre of the available space or to either side of the space. The following sample shows a listbox and three buttons in a horizontal box sizer; one button is centred, one is aligned at the top, one is aligned at the bottom: - - - + + + @b A stretch factor: If a sizer contains more than one child and it is offered more space than its children and their borders need, the question arises how to distribute the surplus space among the children. For this purpose, a stretch @@ -113,18 +113,18 @@ three buttons, the first one has a stretch factor of 1 and thus gets stretched, whereas the other two buttons have a stretch factor of zero and keep their initial width: - - - + + + Within wxDesigner, this stretch factor gets set from the @e Option menu. - + @section sizershiding Hiding controls using sizers - + You can hide controls contained in sizers the same way you would hide any control, using the wxWindow::Show method. - However, wxSizer also offers a separate method which can tell the sizer not to + However, wxSizer also offers a separate method which can tell the sizer not to consider that control in its size calculations. To hide a window using the sizer, - call wxSizer::Show. You must then call Layout on the sizer + call wxSizer::Show. You must then call Layout on the sizer to force an update. This is useful when hiding parts of the interface, since you can avoid removing the controls from the sizer and having to add them back later. @@ -140,24 +140,24 @@ stretch factor determines how much the child can be stretched horizontally. The following sample shows the same dialog as in the last sample, only the box sizer is a vertical box sizer now: - - - + + + @b wxStaticBoxSizer #wxStaticBoxSixer is the same as a wxBoxSizer, but surrounded by a static box. Here is a sample: - - - + + + @b wxGridSizer #wxGridSizer is a two-dimensional sizer. All children are given the same size, which is the minimal size required by the biggest child, in this case the text control in the left bottom border. Either the number of columns or the number or rows is fixed and the grid sizer will grow in the respectively other orientation if new children are added: - - - + + + For programming information, see #wxGridSizer. @b wxFlexGridSizer Another two-dimensional sizer derived from @@ -167,12 +167,12 @@ rows can be declared to be stretchable if the sizer is assigned a size different from the one it requested. The following sample shows the same dialog as the one above, but using a flex grid sizer: - - - - + + + + @section boxsizerprogramming Programming with wxBoxSizer - + The basic idea behind a #wxBoxSizer is that windows will most often be laid out in rather simple basic geometry, typically in a row or a column or several hierarchies of either. As an example, we will construct a dialog that will contain a text field at the top and @@ -185,7 +185,7 @@ a thin border around all controls to make the dialog look nice and - to make matter worse - the buttons shall be centred as the width of the dialog changes. It is the unique feature of a box sizer, that it can grow in both directions (height and - width) but can distribute its growth in the main direction (horizontal for a row) @e unevenly + width) but can distribute its growth in the main direction (horizontal for a row) @e unevenly among its children. In our example case, the vertical sizer is supposed to propagate all its height changes to only the text area, not to the button area. This is determined by the @e proportion parameter when adding a window (or another sizer) to a sizer. It is interpreted @@ -209,17 +209,17 @@ Add() method using the binary or operator |. The sizer of the border also must be made known, and it is the third parameter in the Add() method. This means, that the entire behaviour of a sizer and its children can be controlled by the three parameters of the Add() method. - + @code // we want to get a dialog that is stretchable because it // has a text ctrl at the top and two buttons at the bottom - + MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString ) : wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize, wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER) { wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL ); - + // create text ctrl with minimal size 100x60 topsizer-Add( new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE), @@ -227,8 +227,8 @@ wxEXPAND | // make horizontally stretchable wxALL, // and make border all around 10 ); // set border width to 10 - - + + wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL ); button_sizer-Add( new wxButton( this, wxID_OK, "OK" ), @@ -240,103 +240,103 @@ 0, // make horizontally unstretchable wxALL, // make border all around (implicit top alignment) 10 ); // set border width to 10 - + topsizer-Add( button_sizer, 0, // make vertically unstretchable wxALIGN_CENTER ); // no border and centre horizontally - + SetSizerAndFit(topsizer); // use the sizer for layout and size window // accordingly and prevent it from being resized // to smaller size } @endcode - + Note that the new way of specifying flags to wxSizer is via #wxSizerFlags. This class greatly eases the burden of passing flags to a wxSizer. Here's how you'd do the previous example with wxSizerFlags: - + @code // we want to get a dialog that is stretchable because it // has a text ctrl at the top and two buttons at the bottom - + MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString ) : wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize, wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER) { wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL ); - - // create text ctrl with minimal size 100x60 that is horizontally and + + // create text ctrl with minimal size 100x60 that is horizontally and // vertically stretchable with a border width of 10 topsizer-Add( new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE), wxSizerFlags(1).Align().Expand().Border(wxALL, 10)); - + wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL ); - - //create two buttons that are horizontally unstretchable, + + //create two buttons that are horizontally unstretchable, // with an all-around border with a width of 10 and implicit top alignment button_sizer-Add( new wxButton( this, wxID_OK, "OK" ), - wxSizerFlags(0).Align().Border(wxALL, 10)); - + wxSizerFlags(0).Align().Border(wxALL, 10)); + button_sizer-Add( new wxButton( this, wxID_CANCEL, "Cancel" ), - wxSizerFlags(0).Align().Border(wxALL, 10)); - + wxSizerFlags(0).Align().Border(wxALL, 10)); + //create a sizer with no border and centered horizontally topsizer-Add( button_sizer, - wxSizerFlags(0).Center() ); - + wxSizerFlags(0).Center() ); + SetSizerAndFit(topsizer); // use the sizer for layout and set size and hints } @endcode - - - + + + @section gridsizerprogramming Programming with wxGridSizer - + #wxGridSizer is a sizer which lays out its children in a two-dimensional table with all table fields having the same size, i.e. the width of each field is the width of the widest child, the height of each field is the height of the tallest child. - + @section flexgridsizerprogramming Programming with wxFlexGridSizer - + #wxFlexGridSizer is a sizer which lays out its children in a two-dimensional table with all table fields in one row having the same height and all fields in one column having the same width, but all rows or all columns are not necessarily the same height or width as in the #wxGridSizer. - + @section staticboxsizerprogramming Programming with wxStaticBoxSizer - + #wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static - box around the sizer. Note that this static box has to be created + box around the sizer. Note that this static box has to be created separately. - + @section createbuttonsizer CreateButtonSizer - + As a convenience, CreateButtonSizer ( long flags ) can be used to create a standard button sizer in which standard buttons are displayed. The following flags can be passed to this function: - - + + @code wxYES_NO // Add Yes/No subpanel wxYES // return wxID_YES wxNO // return wxID_NO wxNO_DEFAULT // make the wxNO button the default, otherwise wxYES or wxOK button will be default - + wxOK // return wxID_OK wxCANCEL // return wxID_CANCEL wxHELP // return wxID_HELP - - wxFORWARD // return wxID_FORWARD - wxBACKWARD // return wxID_BACKWARD - wxSETUP // return wxID_SETUP + + wxFORWARD // return wxID_FORWARD + wxBACKWARD // return wxID_BACKWARD + wxSETUP // return wxID_SETUP wxMORE // return wxID_MORE @endcode - + */ - - + + diff --git a/docs/doxygen/overviews/splitterwindow.h b/docs/doxygen/overviews/splitterwindow.h index 9b403b902d..0888ed9a59 100644 --- a/docs/doxygen/overviews/splitterwindow.h +++ b/docs/doxygen/overviews/splitterwindow.h @@ -7,42 +7,42 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page splitterwindow_overview wxSplitterWindow overview - + Classes: #wxSplitterWindow The following screenshot shows the appearance of a splitter window with a horizontal split. - + The style wxSP_3D has been used to show a 3D border and 3D sash. #Example - - + + @section wxsplitterwindowexample Example - + The following fragment shows how to create a splitter window, creating two subwindows and hiding one of them. - - + + @code splitter = new wxSplitterWindow(this, -1, wxPoint(0, 0), wxSize(400, 400), wxSP_3D); - + leftWindow = new MyWindow(splitter); leftWindow-SetScrollbars(20, 20, 50, 50); - + rightWindow = new MyWindow(splitter); rightWindow-SetScrollbars(20, 20, 50, 50); rightWindow-Show(@false); - + splitter-Initialize(leftWindow); - + // Set this to prevent unsplitting // splitter-SetMinimumPaneSize(20); @endcode - - + + The next fragment shows how the splitter window can be manipulated after creation. - - + + @code void MyFrame::OnSplitVertical(wxCommandEvent& event) { @@ -52,7 +52,7 @@ rightWindow-Show(@true); splitter-SplitVertically( leftWindow, rightWindow ); } - + void MyFrame::OnSplitHorizontal(wxCommandEvent& event) { if ( splitter-IsSplit() ) @@ -61,14 +61,14 @@ rightWindow-Show(@true); splitter-SplitHorizontally( leftWindow, rightWindow ); } - + void MyFrame::OnUnsplit(wxCommandEvent& event) { if ( splitter-IsSplit() ) splitter-Unsplit(); } @endcode - + */ - - + + diff --git a/docs/doxygen/overviews/stream.h b/docs/doxygen/overviews/stream.h index a7782ee9f1..9a8bd31e78 100644 --- a/docs/doxygen/overviews/stream.h +++ b/docs/doxygen/overviews/stream.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page stream_overview wxStreams overview - + Classes: #wxStreamBase, #wxStreamBuffer, #wxInputStream, #wxOutputStream, @@ -25,15 +25,15 @@ reliably compile and run on all supported platforms without dependence on a particular release of libg++. wxStreams is divided in two main parts: - - + + the core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream, wxFilterIn/OutputStream the "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream, wxFileIn/OutputStream, ... - - + + wxStreamBase is the base definition of a stream. It defines, for example, - the API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions + the API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions are really implemented by the "IO" classes. wxInputStream and wxOutputStream inherit from it. wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer @@ -53,38 +53,38 @@ @b Generic usage: an example Usage is simple. We can take the example of wxFileInputStream and here is some sample code: - + @code ... // The constructor initializes the stream buffer and open the file descriptor // associated to the name of the file. wxFileInputStream in_stream("the_file_to_be_read"); - + // Ok, read some bytes ... nb_datas is expressed in bytes. in_stream.Read(data, nb_datas); if (in_stream.LastError() != wxSTREAM_NOERROR) { // Oh oh, something bad happens. // For a complete list, look into the documentation at wxStreamBase. } - + // You can also inline all like this. if (in_stream.Read(data, nb_datas).LastError() != wxSTREAM_NOERROR) { // Do something. } - + // You can also get the last number of bytes REALLY put into the buffer. size_t really_read = in_stream.LastRead(); - - // Ok, moves to the beginning of the stream. SeekI returns the last position + + // Ok, moves to the beginning of the stream. SeekI returns the last position // in the stream counted from the beginning. off_t old_position = in_stream.SeekI(0, wxFromBeginning); - + // What is my current position ? off_t position = in_stream.TellI(); - + // wxFileInputStream will close the file descriptor on destruction. @endcode - + */ - - + + diff --git a/docs/doxygen/overviews/string.h b/docs/doxygen/overviews/string.h index c328f08a8d..a8f67d014a 100644 --- a/docs/doxygen/overviews/string.h +++ b/docs/doxygen/overviews/string.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page string_overview wxString overview - + Classes: #wxString, #wxArrayString, #wxStringTokenizer #Introduction @ref otherstringclasses_overview @@ -17,11 +17,11 @@ @ref relatedtostring_overview @ref stringrefcount_overview @ref stringtuning_overview - - + + @section introductiontowxstring Introduction - - wxString is a class which represents a character string of arbitrary length (limited by + + wxString is a class which represents a character string of arbitrary length (limited by @e MAX_INT which is usually 2147483647 on 32 bit machines) and containing arbitrary characters. The ASCII NUL character is allowed, but be aware that in the current string implementation some methods might not work correctly @@ -34,11 +34,11 @@ access to individual characters, string concatenation and comparison, substring extraction, case conversion, trimming and padding (with spaces), searching and replacing and both C-like #Printf() and stream-like - insertion functions as well as much more - see #wxString + insertion functions as well as much more - see #wxString for a list of all functions. - + @section otherstringclasses Comparison of wxString to other string classes - + The advantages of using a special string class instead of working directly with C strings are so obvious that there is a huge number of such classes available. The most important advantage is the need to always @@ -46,36 +46,36 @@ inevitably leads to buffer overflows. At last, C++ has a standard string class (std::string). So why the need for wxString? There are several advantages: - - + + @b Efficiency This class was made to be as efficient as possible: both in terms of size (each wxString objects takes exactly the same space as a @e char * pointer, sing @ref stringrefcount_overview) and speed. - It also provides performance @ref stringtuning_overview + It also provides performance @ref stringtuning_overview which may be enabled to fine tune the memory allocation strategy for your particular application - and the gain might be quite big. @b Compatibility This class tries to combine almost full compatibility with the old wxWidgets 1.xx wxString class, some reminiscence to MFC CString class and 90% of the functionality of std::string class. @b Rich set of functions Some of the functions present in wxString are - very useful but don't exist in most of other string classes: for example, - #AfterFirst, - #BeforeLast, #operator + very useful but don't exist in most of other string classes: for example, + #AfterFirst, + #BeforeLast, #operator or #Printf. Of course, all the standard string operations are supported as well. @b Unicode wxString is Unicode friendly: it allows to easily convert - to and from ANSI and Unicode strings in any build mode (see the + to and from ANSI and Unicode strings in any build mode (see the @ref unicode_overview for more details) and maps to either @c string or @c wstring transparently depending on the current mode. @b Used by wxWidgets And, of course, this class is used everywhere inside wxWidgets so there is no performance loss which would result from conversions of objects of any other string class (including std::string) to wxString internally by wxWidgets. - - + + However, there are several problems as well. The most important one is probably that there are often several functions to do exactly the same thing: for - example, to get the length of the string either one of - length(), #Len() or + example, to get the length of the string either one of + length(), #Len() or #Length() may be used. The first function, as almost all the other functions in lowercase, is std::string compatible. The second one is "native" wxString version and the last one is wxWidgets 1.xx way. So the @@ -89,46 +89,46 @@ In the situations where there is no corresponding std::string function, please try to use the new wxString methods and not the old wxWidgets 1.xx variants which are deprecated and may disappear in future versions. - + @section wxstringadvices Some advice about using wxString - - Probably the main trap with using this class is the implicit conversion operator to + + Probably the main trap with using this class is the implicit conversion operator to @e const char *. It is advised that you use #c_str() instead to clearly indicate when the conversion is done. Specifically, the danger of this implicit conversion may be seen in the following code fragment: - + @code // this function converts the input string to uppercase, output it to the screen // and returns the result const char *SayHELLO(const wxString& input) { wxString output = input.Upper(); - + printf("Hello, %s!\n", output); - + return output; } @endcode - - There are two nasty bugs in these three lines. First of them is in the call to the + + There are two nasty bugs in these three lines. First of them is in the call to the @e printf() function. Although the implicit conversion to C strings is applied automatically by the compiler in the case of - + @code puts(output); @endcode - + because the argument of @e puts() is known to be of the type @e const char *, this is @b not done for @e printf() which is a function with variable number of arguments (and whose arguments are of unknown types). So this call may do anything at all (including displaying the correct string on screen), although - the most likely result is a program crash. The solution is to use + the most likely result is a program crash. The solution is to use #c_str(): just replace this line with - + @code printf("Hello, %s!\n", output.c_str()); @endcode - + The second bug is that returning @e output doesn't work. The implicit cast is used again, so the code compiles, but as it returns a pointer to a buffer belonging to a local variable which is deleted as soon as the function exits, @@ -136,13 +136,13 @@ just make the function return wxString instead of a C string. This leads us to the following general advice: all functions taking string arguments should take @e const wxString (this makes assignment to the - strings inside the function faster because of + strings inside the function faster because of @ref stringrefcount_overview) and all functions returning strings should return @e wxString - this makes it safe to return local variables. - + @section relatedtostring Other string related functions and classes - + As most programs use character strings, the standard C library provides quite a few functions to work with them. Unfortunately, some of them have rather counter-intuitive behaviour (like strncpy() which doesn't always terminate the @@ -151,17 +151,17 @@ 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), + is empty (returning @true for @NULL pointers), #wxStrlen() also handles @NULLs correctly and returns 0 for them and #wxStricmp() is just a platform-independent version of case-insensitive string comparison function known either as stricmp() or strcasecmp() on different platforms. - The @c wx/string.h header also defines #wxSnprintf + The @c wx/string.h header also defines #wxSnprintf and #wxVsnprintf functions which should be used instead of the inherently dangerous standard @c sprintf() and which use @c snprintf() instead which does buffer size checks whenever possible. Of course, you may also use wxString::Printf which is also safe. - There is another class which might be useful when working with wxString: + There is another class which might be useful when working with wxString: #wxStringTokenizer. It is helpful when a string must be broken into tokens and replaces the standard C library @e strtok() function. And the very last string-related class is #wxArrayString: it @@ -169,68 +169,68 @@ with strings. Please note that this class is specially optimized (using its knowledge of the internal structure of wxString) for storing strings and so it is vastly better from a performance point of view than a wxObjectArray of wxStrings. - + @section wxstringrefcount Reference counting and why you shouldn't care about it - + All considerations for wxObject-derived @ref trefcount_overview objects are valid also for wxString, even if it does not derive from wxObject. Probably the unique case when you might want to think about reference counting is when a string character is taken from a string which is not a constant (or a constant reference). In this case, due to C++ rules, the - "read-only" @e operator[] (which is the same as - #GetChar()) cannot be chosen and the "read/write" - @e operator[] (the same as + "read-only" @e operator[] (which is the same as + #GetChar()) cannot be chosen and the "read/write" + @e operator[] (the same as #GetWritableChar()) is used instead. As the call to this operator may modify the string, its data is unshared (COW is done) and so if the string was really shared there is some performance loss (both in terms of speed and memory consumption). In the rare cases when this may be important, you might prefer using #GetChar() instead - of the array subscript operator for this reasons. Please note that + of the array subscript operator for this reasons. Please note that #at() method has the same problem as the subscript operator in this situation and so using it is not really better. Also note that if all string arguments to your functions are passed as @e const wxString (see the section @ref stringadvices_overview) this situation will almost never arise because for constant references the correct operator is called automatically. - + @section wxstringtuning Tuning wxString for your application - - + + @b Note: this section is strictly about performance issues and is absolutely not necessary to read for using wxString class. Please skip it unless you feel familiar with profilers and relative tools. If you do read it, please - also read the preceding section about + also read the preceding section about @ref stringrefcount_overview. - + For the performance reasons wxString doesn't allocate exactly the amount of memory needed for each string. Instead, it adds a small amount of space to each allocated block which allows it to not reallocate memory (a relatively expensive operation) too often as when, for example, a string is constructed by subsequently adding one character at a time to it, as for example in: - + @code // delete all vowels from the string wxString DeleteAllVowels(const wxString& original) { wxString result; - + size_t len = original.length(); for ( size_t n = 0; n len; n++ ) { if ( strchr("aeuio", tolower(original[n])) == @NULL ) result += original[n]; } - + return result; } @endcode - + This is quite a common situation and not allocating extra memory at all would lead to very bad performance in this case because there would be as many memory (re)allocations as there are consonants in the original string. Allocating too much extra memory would help to improve the speed in this situation, but due to a great number of wxString objects typically used in a program would also increase the memory consumption too much. - The very best solution in precisely this case would be to use + The very best solution in precisely this case would be to use #Alloc() function to preallocate, for example, len bytes from the beginning - this will lead to exactly one memory allocation being performed (because the result is at most as long as the original string). @@ -256,7 +256,7 @@ really consider fine tuning wxString for your application). It goes without saying that a profiler should be used to measure the precise difference the change to EXTRA_ALLOC makes to your program. - + */ - - + + diff --git a/docs/doxygen/overviews/thread.h b/docs/doxygen/overviews/thread.h index ee90ecf270..15fe0a5d18 100644 --- a/docs/doxygen/overviews/thread.h +++ b/docs/doxygen/overviews/thread.h @@ -7,16 +7,16 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page thread_overview Multithreading overview - - Classes: #wxThread, #wxMutex, - #wxCriticalSection, + + Classes: #wxThread, #wxMutex, + #wxCriticalSection, #wxCondition wxWidgets provides a complete set of classes encapsulating objects necessary in multithreaded (MT) programs: the #thread class itself and different - synchronization objects: #mutexes and - @ref criticalsection_overview with + synchronization objects: #mutexes and + @ref criticalsection_overview with #conditions. 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 @@ -31,7 +31,7 @@ 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 + dialog example it is far better to do the calculations in the @ref idleevent_overview or even simply do everything at once but call wxWindow::Update() periodically to update the screen. @@ -44,7 +44,7 @@ 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 + 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 @@ -52,10 +52,10 @@ 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 + 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/tipprovider.h b/docs/doxygen/overviews/tipprovider.h index b6d9fa8934..96f22756cc 100644 --- a/docs/doxygen/overviews/tipprovider.h +++ b/docs/doxygen/overviews/tipprovider.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page tipprovider_overview wxTipProvider - + This is the class used together with #wxShowTip function. It must implement #GetTip function and return the current tip from it (different tip each time it is called). @@ -30,42 +30,42 @@ wxTipProvider::GetTip wxTipProvider::PreprocessTip wxCurrentTipProvider::GetCurrentTip - - + + @section wxtipproviderctor wxTipProvider::wxTipProvider - + @b @b wxTipProvider(@b size_t@e currentTip) Constructor. @e currentTip The starting tip index. - - + + @section wxtipprovidergettip wxTipProvider::GetTip - + @b #wxString @b GetTip() Return the text of the current tip and pass to the next one. This function is pure virtual, it should be implemented in the derived classes. - + @section wxtipproviderpreprocesstip wxTipProvider::PreprocessTip - + @b virtual #wxString @b PreProcessTip(@b const #wxString&@e tip) Returns a modified tip. This function will be called immediately after read, - and before being check whether it is a comment, an empty string or a string - to translate. You can optionally override this in your custom user-derived class - to optionally to modify the tip as soon as it is read. You can return any - modification to the string. If you return wxEmptyString, then this tip is + and before being check whether it is a comment, an empty string or a string + to translate. You can optionally override this in your custom user-derived class + to optionally to modify the tip as soon as it is read. You can return any + modification to the string. If you return wxEmptyString, then this tip is skipped, and the next one is read. - + @section wxtipprovidergetcurrenttip wxCurrentTipProvider::GetCurrentTip - + @b size_t @b GetCurrentTip() @b const - Returns the index of the current tip (i.e. the one which would be returned by + Returns the index of the current tip (i.e. the one which would be returned by GetTip). - The program usually remembers the value returned by this function after calling + The program usually remembers the value returned by this function after calling #wxShowTip. Note that it is not the same as the value which was passed to wxShowTip + 1 because the user might have pressed the "Next" button in the tip dialog. - + */ - - + + diff --git a/docs/doxygen/overviews/tips.h b/docs/doxygen/overviews/tips.h index 1e284e714c..3aaf24d8b0 100644 --- a/docs/doxygen/overviews/tips.h +++ b/docs/doxygen/overviews/tips.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page tips_overview 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 @@ -17,7 +17,7 @@ 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?... ) { @@ -26,13 +26,13 @@ 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 + 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 @@ -44,33 +44,33 @@ 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 + 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 + 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 + 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. + + 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 + 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 27d92ed414..8a2639cac6 100644 --- a/docs/doxygen/overviews/toolbar.h +++ b/docs/doxygen/overviews/toolbar.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page toolbar_overview Toolbar overview - + Classes: #wxToolBar The toolbar family of classes allows an application to use toolbars in a variety of configurations and styles. @@ -25,8 +25,8 @@ 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 @@ -45,8 +45,8 @@ 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 @@ -64,24 +64,24 @@ one bitmap for each tool, because the toolbar generates all three images (normal, depressed and checked) from the single bitmap you give it. @ref usingtoolbarlibrary_overview - - + + @section 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 @@ -91,25 +91,25 @@ // Created: 04/01/98 // RCS-ID: $Id: ttoolbar.tex 47878 2007-08-05 10:10:37Z JS $ // Copyright: (c) Julian Smart - // License: wxWindows license + // 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" @@ -121,9 +121,9 @@ #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) @@ -131,53 +131,53 @@ // 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"); @@ -197,14 +197,14 @@ 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"); @@ -223,19 +223,19 @@ 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) @@ -243,7 +243,7 @@ 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): @@ -251,31 +251,31 @@ { 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) @@ -288,7 +288,7 @@ SetStatusText(""); } @endcode - + */ - - + + diff --git a/docs/doxygen/overviews/treectrl.h b/docs/doxygen/overviews/treectrl.h index 5d1f4d8690..7409ec6154 100644 --- a/docs/doxygen/overviews/treectrl.h +++ b/docs/doxygen/overviews/treectrl.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page treectrl_overview 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 @@ -17,36 +17,36 @@ shown). Each item in the tree is identified by its @e itemId which is of opaque data type @e wxTreeItemId. You can test whether an item is valid by calling wxTreeItemId::IsOk. - The items text and image may be retrieved and changed with - #GetItemText/#SetItemText - and + 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 + and another one for selected state which is set/retrieved with + #SetItemSelectedImage/#GetItemSelectedImage functions, but this functionality might be unavailable on some platforms. Tree items have several attributes: an item may be selected or not, visible or not, bold or not. It may also be expanded or collapsed. All these attributes - may be retrieved with the corresponding functions: - #IsSelected, - #IsVisible, #IsBold + 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 + selected, selecting another one (with #SelectItem) automatically unselects the previously selected one. In addition to its icon and label, a user-specific data structure may be associated with all tree items. If you wish to do it, you should derive a class from @e wxTreeItemData which is a very simple class having only one function @e GetId() which returns the id of the item this data is associated with. This 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 + 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 + deleting the pointer second time). The associated data may be retrieved with #GetItemData() function. Working with trees is relatively straightforward if all the items are added to the tree at the moment of its creation. However, for large trees it may be very inefficient. To improve the performance you may want to delay adding the items to the tree until the branch containing the items is expanded: so, in the - beginning, only the root item is created (with + 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 @@ -60,16 +60,16 @@ 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 + only thing to remember is that the @e cookie passed to + #GetFirstChild and to #GetNextChild should be the same variable (and that nothing should be done with it by the user code). - Among other features of the tree control are: item sorting with + 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 + 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 @@ -78,7 +78,7 @@ 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/trefcount.h b/docs/doxygen/overviews/trefcount.h index 8879f4cc97..08f23649d6 100644 --- a/docs/doxygen/overviews/trefcount.h +++ b/docs/doxygen/overviews/trefcount.h @@ -7,18 +7,18 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page trefcount_overview Reference counting - + @ref refcount_overview @ref refcountequality_overview @ref refcountdestruct_overview @ref refcountlist_overview @ref object_overview - - + + @section refcount Why you shouldn't care about it - + Many wxWidgets objects use a technique known as @e reference counting, also known as @e copy on write (COW). This means that when an object is assigned to another, no copying really takes place: @@ -32,9 +32,9 @@ transparently to the class users and that whether an object is shared or not is not seen from the outside of the class - in any case, the result of any operation on it is the same. - + @section refcountequality Object comparison - + The == and != operators of @ref refcountlist_overview always do a @c deep comparison. This means that the equality operator will return @true if two objects are @@ -46,55 +46,55 @@ Also note that if you only need to do a @c shallow comparison between two #wxObject-derived classes, you should not use the == and != operators but rather the wxObject::IsSameAs function. - - + + @section refcountdestruct Object destruction - + When a COW object destructor is called, it may not delete the data: if it's shared, the destructor will just decrement the shared data's reference count without destroying it. Only when the destructor of the last object owning the data is called, the data is really destroyed. As for all other COW-things, this happens transparently to the class users so that you shouldn't care about it. - - + + @section refcountlist List of reference-counted wxWidgets classes - + The following classes in wxWidgets have efficient (i.e. fast) assignment operators and copy constructors since they are reference-counted: #wxAcceleratorTable - + #wxAnimation - + #wxBitmap - + #wxBrush - + #wxCursor - + #wxFont - + #wxIcon - + #wxImage - + #wxMetafile - + #wxPalette - + #wxPen - + #wxRegion - + #wxString - + #wxVariant - + #wxVariantData Note that the list above reports the objects which are reference-counted in all ports of wxWidgets; some ports may use this tecnique also for other classes. - + @section wxobjectoverview Make your own reference-counted class - + Reference counting can be implemented easily using #wxObject and #wxObjectRefData classes. Alternatively, you can also use the #wxObjectDataPtrT template. @@ -104,18 +104,18 @@ the public interface which will be seen by the user of your class. You'll probably want to add a function to your class which does the cast from #wxObjectRefData to your class-specific shared data; e.g.: - + @code MyClassRefData *GetData() const { return wx_static_cast(MyClassRefData*, m_refData); } @endcode - + in fact, all times you'll need to read the data from your wxObject-derived class, you'll need to call such function. Very important, all times you need to actually modify the data placed inside your wxObject-derived class, you must first call the wxObject::UnShare function to be sure that the modifications won't affect other instances which are eventually sharing your object's data. - + */ - - + + diff --git a/docs/doxygen/overviews/unicode.h b/docs/doxygen/overviews/unicode.h index 810d17d55c..ad8af01ec1 100644 --- a/docs/doxygen/overviews/unicode.h +++ b/docs/doxygen/overviews/unicode.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page unicode_overview 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. @@ -19,10 +19,10 @@ @ref unicodeoutsidewxw_overview @ref unicodesettings_overview @ref topic8_overview - - + + @section 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 @@ -41,24 +41,24 @@ 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 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__ + 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 @@ -73,69 +73,69 @@ 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 + 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__ + 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 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 + 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 + 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 + 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 @@ -143,11 +143,11 @@ 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 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 @@ -155,46 +155,46 @@ 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 + 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 + 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. + 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 mbconvclasses_overview. - + @section unicodesettings Unicode-related compilation settings - + You should define @c wxUSE_UNICODE to 1 to compile your program in Unicode mode. This currently works for wxMSW, wxGTK, wxMac and wxX11. If you - compile your program in ANSI mode you can still define @c wxUSE_WCHAR_T + 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 mbconvclasses_overview) + ANSI ones (using @ref mbconvclasses_overview) and construct wxString objects from Unicode strings (presumably read from some external file or elsewhere). - + @section topic8 Traps for the unwary - - - + + + Casting c_str() to void* is now char*, not wxChar* Passing c_str(), mb_str() or wc_str() to variadic functions doesn't work - + */ - - + + diff --git a/docs/doxygen/overviews/unixprinting.h b/docs/doxygen/overviews/unixprinting.h index e71649ce00..d4c429d0b0 100644 --- a/docs/doxygen/overviews/unixprinting.h +++ b/docs/doxygen/overviews/unixprinting.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page unixprinting_overview 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 @@ -33,8 +33,8 @@ 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 + 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 @@ -45,7 +45,7 @@ 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). - + */ - - + + diff --git a/docs/doxygen/overviews/validator.h b/docs/doxygen/overviews/validator.h index ce9de4e5af..73381692b7 100644 --- a/docs/doxygen/overviews/validator.h +++ b/docs/doxygen/overviews/validator.h @@ -7,10 +7,10 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page validator_overview wxValidator overview - - Classes: #wxValidator, #wxTextValidator, + + Classes: #wxValidator, #wxTextValidator, #wxGenericValidator The aim of the validator concept is to make dialogs very much easier to write. A validator is an object that can be plugged into a control (such as a wxTextCtrl), and @@ -18,27 +18,27 @@ and validating it. It also is able to intercept events generated by the control, providing filtering behaviour without the need to derive a new control class. You can use a stock validator, such as #wxTextValidator (which does text - control data transfer, validation and filtering) and + control data transfer, validation and filtering) and #wxGenericValidator (which does data transfer for a range of controls); or you can write your own. @b Example Here is an example of wxTextValidator usage. - + @code wxTextCtrl *txt1 = new wxTextCtrl(this, -1, wxT(""), wxPoint(10, 10), wxSize(100, 80), 0, wxTextValidator(wxFILTER_ALPHA, _data.m_string)); @endcode - + In this example, the text validator object provides the following functionality: - - + + It transfers the value of g_data.m_string (a wxString variable) to the wxTextCtrl when the dialog is initialised. It transfers the wxTextCtrl data back to this variable when the dialog is dismissed. It filters input characters so that only alphabetic characters are allowed. - - + + The validation and filtering of input is accomplished in two ways. When a character is input, wxTextValidator checks the character against the allowed filter flag (wxFILTER_ALPHA in this case). If the character is inappropriate, it is vetoed (does not appear) and a warning beep sounds. @@ -76,11 +76,11 @@ function finds all the validators in the window's children and calls the TransferToWindow function for each. Thus, data is transferred from C++ variables to the dialog just as the dialog is being shown. - + If you are using a window or panel instead of a dialog, you will need to call wxWindow::InitDialog explicitly before showing the window. - + When the user clicks on a button, for example the OK button, the application should first call wxWindow::Validate, which returns @false if any of the child window validators failed to validate the window data. The button handler @@ -90,7 +90,7 @@ or Show (if modeless). In fact, wxDialog contains a default command event handler for the wxID_OK button. It goes like this: - + @code void wxDialog::OnOK(wxCommandEvent& event) { @@ -106,12 +106,12 @@ } } @endcode - + So if using validators and a normal OK button, you may not even need to write any code for handling dialog dismissal. If you load your dialog from a resource file, you will need to iterate through the controls setting validators, since validators can't be specified in a dialog resource. - + */ - - + + diff --git a/docs/doxygen/overviews/windowdeletion.h b/docs/doxygen/overviews/windowdeletion.h index 850d4a227a..9ab084fa97 100644 --- a/docs/doxygen/overviews/windowdeletion.h +++ b/docs/doxygen/overviews/windowdeletion.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page windowdeletion_overview Window deletion overview - + Classes: #wxCloseEvent, #wxWindow Window deletion can be a confusing subject, so this overview is provided to help make it clear when and how you delete windows, or respond to user requests @@ -24,7 +24,7 @@ (wxCloseEvent::CanVeto returns @false), the window should always be destroyed, otherwise there is the option to ignore the request, or maybe wait until the user has answered a question before deciding whether it is safe to close. The handler for EVT_CLOSE should - signal to the calling code if it does not destroy the window, by calling + signal to the calling code if it does not destroy the window, by calling wxCloseEvent::Veto. Calling this provides useful information to the calling code. The wxCloseEvent handler should only call wxWindow::Destroy to @@ -65,7 +65,7 @@ or not delete the window. To update your code, you should provide an event table entry in your frame or dialog, using the EVT_CLOSE macro. The event handler function might look like this: - + @code void MyFrame::OnCloseWindow(wxCloseEvent& event) { @@ -73,10 +73,10 @@ { wxMessageDialog* dialog = new wxMessageDialog(this, "Save changed data?", "My app", wxYES_NO|wxCANCEL); - + int ans = dialog-ShowModal(); dialog-Destroy(); - + switch (ans) { case wxID_YES: // Save, then destroy, quitting app @@ -97,7 +97,7 @@ } } @endcode - + @b How do I exit the application gracefully? A wxWidgets application automatically exits when the last top level window (#wxFrame or #wxDialog), is destroyed. Put @@ -113,7 +113,7 @@ close event handlers, though you can implement them if you wish. For consistency, continue to use the wxWindow::Destroy function instead of the @b delete operator when deleting these kinds of windows explicitly. - + */ - - + + diff --git a/docs/doxygen/overviews/windowids.h b/docs/doxygen/overviews/windowids.h index 47fae49c5e..2e0c735b5a 100644 --- a/docs/doxygen/overviews/windowids.h +++ b/docs/doxygen/overviews/windowids.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page windowids_overview Window IDs overview - + @b See Also #wxIdManager wxWindow::NewControlId @@ -17,14 +17,14 @@ #Introduction @ref windowidstypes_overview @ref windowidsusing_overview - - + + @section windowidsoverviewintro Introduction - + Various contols and other parts of wxWidgets need an ID. Sometimes the ID may be directly provided by the use or have a predefined value, such as @c wxID_OPEN. Often, however, the value of the ID is unimportant and is - created automatically by calling wxWindow::NewControlId + created automatically by calling wxWindow::NewControlId or by passing @c wxID_ANY as the ID of an object. There are two ways to generate an ID. One way, is to start at a negative number, and for each new ID, return the next smallest number. This is fine for systems @@ -42,9 +42,9 @@ another. This is accomplished by keeping a reference count for each of the IDs that can possibly be returned by wxWindow::NewControlId. Other IDs are not reference counted. - + @section windowidsoverviewtypes Data types - + A wxWindowID is just the integer type for a window ID. It should be used almost everywhere. To help keep track of the count for the automatically generated IDs, a new type, wxWindowIDRef exists, that can take the place of wxWindowID where needed. @@ -61,15 +61,15 @@ wxWindowIDRef can store both automatic IDs from wxWindow::NewControlId as well as normal IDs. Reference counting is only done for the automatic IDs. Also, wxWindowIDRef has conversion operators that allow it to be treated just like a wxWindowID. - + @section windowidsoverviewusing Using wxWindowIDRef - + A wxWindowIDRef should be used in place of a wxWindowID where you want to make sure the ID is not created again by wxWindow::NewControlId at least until the wxWindowIDRef is destroyed, usually when the associated object is destroyed. This is done already for windows, menu items, and tool bar items. It should only be used in the main thread, as it is not thread safe. - + */ - - + + diff --git a/docs/doxygen/overviews/windowsizing.h b/docs/doxygen/overviews/windowsizing.h index e9656bd83f..ed666cb0f1 100644 --- a/docs/doxygen/overviews/windowsizing.h +++ b/docs/doxygen/overviews/windowsizing.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page windowsizing_overview Window Sizing Overview - + It can sometimes be confusing to keep track of the various size-related attributes of a #wxWindow, how they relate to each other, and how they interact with sizers. This document @@ -27,15 +27,15 @@ wants to calculate its own best size based on its content. The default @c DoGetBestSize() is designed for use in container windows, such as #wxPanel, and works something like this: - - + + If the window has a sizer then it is used to calculate the best size. Otherwise if the window has layout constraints then that is used to calculate the best size. Otherwise if the window has children then the best size is set to be large enough to show all the children. Otherwise if there are no children then the window's min size will be used for the best size. Otherwise if there is no min size set, then the current size is used for the best size. - - + + @b MinSize: The min size of a widget is a size that is normally explicitly set by the programmer either with the @c SetMinSize() method or the @c SetSizeHints() method. Most controls will also @@ -93,7 +93,7 @@ constraints instead of a sizer then the constraints algorithm is run. The @c Layout() method is what is called by the default @c EVT_SIZE handler for container windows. - + */ - - + + diff --git a/docs/doxygen/overviews/windowstyles.h b/docs/doxygen/overviews/windowstyles.h index 4cde1272a3..3260c521ee 100644 --- a/docs/doxygen/overviews/windowstyles.h +++ b/docs/doxygen/overviews/windowstyles.h @@ -7,21 +7,21 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page windowstyles_overview Window styles - + Window styles are used to specify alternative behaviour and appearances for windows, when they are created. The symbols are defined in such a way that they can be combined in a 'bit-list' using the C++ @e bitwise-or operator. For example: - + @code wxCAPTION | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER @endcode - + For the window styles specific to each window class, please see the documentation for the window. Most windows can use the generic styles listed for #wxWindow in addition to their own styles. - + */ - - + + diff --git a/docs/doxygen/overviews/xrc.h b/docs/doxygen/overviews/xrc.h index 84e7a9bbcd..2cfddd9936 100644 --- a/docs/doxygen/overviews/xrc.h +++ b/docs/doxygen/overviews/xrc.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /*! - + @page xrc_overview XML-based resource system overview - + Classes: #wxXmlResource, #wxXmlResourceHandler The XML-based resource system, known as XRC, allows user interface elements such as dialogs, menu bars and toolbars, to be stored in text files and loaded into @@ -17,8 +17,8 @@ code (the former makes it possible to store all resources in a single file and the latter is useful when you want to embed the resources into the executable). There are several advantages to using XRC resources. - - + + Recompiling and linking an application is not necessary if the resources change. If you use a dialog designer that generates C++ code, it can be hard @@ -30,8 +30,8 @@ The XRC format is a wxWidgets standard, and can be generated or postprocessed by any program that understands it. As it is based on the XML standard, existing XML editors can be used for simple editing purposes. - - + + XRC was written by Vaclav Slavik. @ref xrcconcepts_overview @ref binaryresourcefiles_overview @@ -41,13 +41,13 @@ @ref xrcfileformat_overview @ref xrccppheader_overview @ref newresourcehandlers_overview - - + + @section xrcconcepts XRC concepts - + These are the typical steps for using XRC files in your application. - - + + Include the appropriate headers: normally "wx/xrc/xmlres.h" will suffice; If you are going to use @ref binaryresourcefiles_overview, install wxFileSystem archive handler first with @c wxFileSystem::AddHandler(new wxArchiveFSHandler); @@ -57,11 +57,11 @@ load it using for example @c wxXmlResource::Get()-LoadDialog(dlg, this, "dlg1"); set up event tables as usual but use the @c XRCID(str) macro to translate from XRC string names to a suitable integer identifier, for example @c EVT_MENU(XRCID("quit"), MyFrame::OnQuit). - - + + To create an XRC file, you can use one of the following methods. - - + + Create the file by hand; use #wxDesigner, a commercial dialog designer/RAD tool; use #DialogBlocks, a commercial dialog editor; @@ -69,8 +69,8 @@ dialog editor that you can find in the @c wxPython/tools subdirectory of the wxWidgets CVS archive; use #wxGlade, a GUI designer written in wxPython. At the moment it can generate Python, C++ and XRC; - - + + A complete list of third-party tools that write to XRC can be found at #www.wxwidgets.org/lnk_tool.htm. It is highly recommended that you use a resource editing tool, since it's fiddly writing XRC files by hand. @@ -78,58 +78,58 @@ You can pass an XRC file (XML-based text resource file) or a @ref binaryresourcefiles_overview (extension ZIP or XRS) containing other XRC. You can also use @ref embeddedresource_overview - + @section binaryresourcefiles Using binary resource files - + To compile binary resource files, use the command-line wxrc utility. It takes one or more file parameters (the input XRC files) and the following switches and options: - - + + -h (--help): show a help message -v (--verbose): show verbose logging information -c (--cpp-code): write C++ source rather than a XRS file -e (--extra-cpp-code): if used together with -c, generates C++ header file - containing class definitions for the windows defined by the XRC file (see special subsection) + containing class definitions for the windows defined by the XRC file (see special subsection) -u (--uncompressed): do not compress XML files (C++ only) -g (--gettext): output underscore-wrapped strings that poEdit or gettext can scan. Outputs to stdout, or a file if -o is used -n (--function) name: specify C++ function name (use with -c) -o (--output) filename: specify the output file, such as resource.xrs or resource.cpp -l (--list-of-handlers) filename: output a list of necessary handlers to this file - - + + For example: - + @code % wxrc resource.xrc % wxrc resource.xrc -o resource.xrs % wxrc resource.xrc -v -c -o resource.cpp @endcode - + @b Note XRS file is essentially a renamed ZIP archive which means that you can manipulate it with standard ZIP tools. Note that if you are using XRS files, you have to initialize the #wxFileSystem archive handler first! It is a simple thing to do: - + @code #include wx/filesys.h #include wx/fs_arc.h ... wxFileSystem::AddHandler(new wxArchiveFSHandler); @endcode - - + + @section embeddedresource Using embedded resources - + It is sometimes useful to embed resources in the executable itself instead of loading an external file (e.g. when your app is small and consists only of one exe file). XRC provides means to convert resources into regular C++ file that - can be compiled and included in the executable. + can be compiled and included in the executable. Use the @c -c switch to @c wxrc utility to produce C++ file with embedded resources. This file will contain a function called @e InitXmlResource (unless you override this with a command line switch). Use it to load the resource: - + @code extern void InitXmlResource(); // defined in generated file ... @@ -137,124 +137,124 @@ InitXmlResource(); ... @endcode - - + + @section xrccppsample XRC C++ sample - + This is the C++ source file (xrcdemo.cpp) for the XRC sample. - + @code #include "wx/wx.h" #include "wx/image.h" #include "wx/xrc/xmlres.h" - + // the application icon #if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__) #include "rc/appicon.xpm" #endif - + // ---------------------------------------------------------------------------- // private classes // ---------------------------------------------------------------------------- - + // Define a new application type, each program should derive a class from wxApp class MyApp : public wxApp { public: // override base class virtuals // ---------------------------- - + // this one is called on application startup and is a good place for the app // initialization (doing it here and not in the ctor allows to have an error // return: if OnInit() returns @false, the application terminates) virtual bool OnInit(); }; - + // Define a new frame type: this is going to be our main frame class MyFrame : public wxFrame { public: // ctor(s) MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size); - + // event handlers (these functions should _not_ be virtual) void OnQuit(wxCommandEvent& event); void OnAbout(wxCommandEvent& event); void OnDlg1(wxCommandEvent& event); void OnDlg2(wxCommandEvent& event); - + private: // any class wishing to process wxWidgets events must use this macro DECLARE_EVENT_TABLE() }; - + // ---------------------------------------------------------------------------- // event tables and other macros for wxWidgets // ---------------------------------------------------------------------------- - + BEGIN_EVENT_TABLE(MyFrame, wxFrame) EVT_MENU(XRCID("menu_quit"), MyFrame::OnQuit) EVT_MENU(XRCID("menu_about"), MyFrame::OnAbout) EVT_MENU(XRCID("menu_dlg1"), MyFrame::OnDlg1) EVT_MENU(XRCID("menu_dlg2"), MyFrame::OnDlg2) END_EVENT_TABLE() - + IMPLEMENT_APP(MyApp) - + // ---------------------------------------------------------------------------- // the application class // ---------------------------------------------------------------------------- - + // 'Main program' equivalent: the program execution "starts" here bool MyApp::OnInit() { wxImage::AddHandler(new wxGIFHandler); wxXmlResource::Get()-InitAllHandlers(); wxXmlResource::Get()-Load("rc/resource.xrc"); - + MyFrame *frame = new MyFrame("XML resources demo", wxPoint(50, 50), wxSize(450, 340)); frame-Show(@true); return @true; } - + // ---------------------------------------------------------------------------- // main frame // ---------------------------------------------------------------------------- - + // frame constructor MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size) : wxFrame((wxFrame *)@NULL, -1, title, pos, size) { SetIcon(wxICON(appicon)); - + SetMenuBar(wxXmlResource::Get()-LoadMenuBar("mainmenu")); SetToolBar(wxXmlResource::Get()-LoadToolBar(this, "toolbar")); } - + // event handlers void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event)) { // @true is to force the frame to close Close(@true); } - + void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event)) { wxString msg; msg.Printf( _T("This is the about dialog of XML resources demo.\n") _T("Welcome to %s"), wxVERSION_STRING); - + wxMessageBox(msg, "About XML resources demo", wxOK | wxICON_INFORMATION, this); } - + void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event)) { wxDialog dlg; wxXmlResource::Get()-LoadDialog(, this, "dlg1"); dlg.ShowModal(); } - + void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event)) { wxDialog dlg; @@ -262,12 +262,12 @@ dlg.ShowModal(); } @endcode - - + + @section xrcsample XRC resource file sample - + This is the XML file (resource.xrc) for the XRC sample. - + @code ?xml version="1.0"? resource version="2.3.0.1" @@ -424,15 +424,15 @@ /object /resource @endcode - - + + @section xrcfileformat XRC file format - + Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWidgets distribution. - + @section xrccppheader C++ header file generation - + Using the @c -e switch together with @c -c, a C++ header file is written containing class definitions for the GUI windows defined in the XRC file. This code generation can make it easier to use XRC and automate program @@ -441,13 +441,13 @@ programmer from dealing with most of the XRC specifics (e.g. @c XRCCTRL). For each top level window defined in the XRC file a C++ class definition is generated, containing as class members the named widgets of the window. - A default constructor for each class is also generated. Inside the constructor - all XRC loading is done and all class members representing widgets are initialized. + A default constructor for each class is also generated. Inside the constructor + all XRC loading is done and all class members representing widgets are initialized. A simple example will help understand how the scheme works. Suppose you have - a XRC file defining a top level window @c TestWnd_Base, which subclasses @c wxFrame (any + a XRC file defining a top level window @c TestWnd_Base, which subclasses @c wxFrame (any other class like @c wxDialog will do also), and has subwidgets @c wxTextCtrl A and @c wxButton B. The XRC file and corresponding class definition in the header file will be something like: - + @code ?xml version="1.0"? resource version="2.3.0.1" @@ -469,13 +469,13 @@ /object /object /resource - - + + class TestWnd_Base : public wxFrame { protected: wxTextCtrl* A; wxButton* B; - + private: void InitWidgetsFromXRC(){ wxXmlResource::Get()-LoadObject(this,@NULL,"TestWnd","wxFrame"); @@ -488,110 +488,110 @@ } }; @endcode - + The generated window class can be used as basis for the full window class. The class members which represent widgets may be accessed by name instead of using - @c XRCCTRL every time you wish to reference them (note that they are @c protected class members), + @c XRCCTRL every time you wish to reference them (note that they are @c protected class members), though you must still use @c XRCID to refer to widget IDs in the event - table. + table. Example: - + @code #include "resource.h" - + class TestWnd : public TestWnd_Base { - public: - TestWnd(){ - // A, B already initialised at this point - A-SetValue("Updated in TestWnd::TestWnd"); - B-SetValue("Nice :)"); - } - void OnBPressed(wxEvent& event){ - Close(); - } - DECLARE_EVENT_TABLE(); + public: + TestWnd(){ + // A, B already initialised at this point + A-SetValue("Updated in TestWnd::TestWnd"); + B-SetValue("Nice :)"); + } + void OnBPressed(wxEvent& event){ + Close(); + } + DECLARE_EVENT_TABLE(); }; - + BEGIN_EVENT_TABLE(TestWnd,TestWnd_Base) EVT_BUTTON(XRCID("B"),TestWnd::OnBPressed) END_EVENT_TABLE() @endcode - + It is also possible to access the wxSizerItem of a sizer that is part of a resource. This can be done using @c XRCSIZERITEM as shown. The resource file can have something like this for a sizer item. - + @code object class="spacer" name="area" size400, 300/size /object @endcode - + The code can then access the sizer item by using @c XRCSIZERITEM and @c XRCID together. - + @code wxSizerItem* item = XRCSIZERITEM(*this, "area"); @endcode - - + + @section newresourcehandlers Adding new resource handlers - + Adding a new resource handler is pretty easy. Typically, to add an handler for the @c MyControl class, you'll want to create the @c xh_mycontrol.h @c xh_mycontrol.cpp files. The header needs to contains the @c MyControlXmlHandler class definition: - + @code class MyControlXmlHandler : public wxXmlResourceHandler { public: - + // Constructor. MyControlXmlHandler(); - + // Creates the control and returns a pointer to it. virtual wxObject *DoCreateResource(); - + // Returns @true if we know how to create a control for the given node. virtual bool CanHandle(wxXmlNode *node); - + // Register with wxWidgets' dynamic class subsystem. DECLARE_DYNAMIC_CLASS(MyControlXmlHandler) }; @endcode - + The implementation of your custom XML handler will typically look as: - + @code // Register with wxWidgets' dynamic class subsystem. IMPLEMENT_DYNAMIC_CLASS(MyControlXmlHandler, wxXmlResourceHandler) - + MyControlXmlHandler::MyControlXmlHandler() { // this call adds support for all wxWindows class styles // (e.g. wxBORDER_SIMPLE, wxBORDER_SUNKEN, wxWS_EX_* etc etc) AddWindowStyles(); - + // if MyControl class supports e.g. MYCONTROL_DEFAULT_STYLE // you should use: // XRC_ADD_STYLE(MYCONTROL_DEFAULT_STYLE); } - + wxObject *MyControlXmlHandler::DoCreateResource() { // the following macro will init a pointer named "control" // with a new instance of the MyControl class, but will NOT // Create() it! XRC_MAKE_INSTANCE(control, MyControl) - + // this is the point where you'll typically need to do the most // important changes: here the control is created and initialized. // You'll want to use the wxXmlResourceHandler's getters to // do most of your work. // If e.g. the MyControl::Create function looks like: // - // bool MyControl::Create(wxWindow *parent, int id, + // bool MyControl::Create(wxWindow *parent, int id, // const wxBitmap , const wxPoint , // const wxBitmap , const wxPoint , // const wxString , const wxFont , @@ -623,12 +623,12 @@ GetText(wxT("the-title")), GetFont(wxT("title-font")), GetPosition(), GetSize(), GetStyle(), GetName()); - + SetupWindow(control); - + return control; } - + bool MyControlXmlHandler::CanHandle(wxXmlNode *node) { // this function tells XRC system that this handler can parse @@ -636,11 +636,11 @@ return IsOfClass(node, wxT("MyControl")); } @endcode - + You may want to check the #wxXmlResourceHandler documentation to see how many built-in getters it contains. It's very easy to retrieve also complex structures out of XRC files using them. - + */ - - + + diff --git a/docs/doxygen/platdetails.h b/docs/doxygen/platdetails.h index 8750f86fe7..3aa53e43e8 100644 --- a/docs/doxygen/platdetails.h +++ b/docs/doxygen/platdetails.h @@ -15,7 +15,7 @@ user interface (GUI) on each platform, so your program will take on the native look and feel that users are familiar with. Unfortunately native toolkits and hardware do not always support the functionality that the wxWidgets API - requires. This chapter collects notes about differences among supported platforms + requires. This chapter collects notes about differences among supported platforms and ports. @li @ref nativedocs @@ -30,15 +30,15 @@ \input wxos2.tex \input wxmgl.tex \input wxx11.tex - + @section nativedocs Documentation for the native toolkits - + It's sometimes useful to interface directly with the underlying toolkit used by wxWidgets to e.g. use toolkit-specific features. In such case (or when you want to e.g. write a port-specific patch) it can be necessary to use the underlying toolkit API directly: - + @li wxMSW port uses win32 API: see MSDN docs at http://msdn2.microsoft.com/en-us/library/ms649779.aspx @li wxGTK port uses GTK+: see GTK+ 2.x docs at http://developer.gnome.org/doc/API/2.0/gtk/index.html diff --git a/docs/doxygen/topics.h b/docs/doxygen/topics.h index ebf5248925..b9830f67e9 100644 --- a/docs/doxygen/topics.h +++ b/docs/doxygen/topics.h @@ -25,15 +25,15 @@ @section topics_starting Starting with wxWidgets - + @li @ref referencenotes_overview @li @ref roughguide_overview @li @ref helloworld_overview @li @ref samples_overview @li @ref python_overview - + @section topics_programming Programming with wxWidgets - + @li @ref backwardcompatibility_overview @li @ref runtimeclass_overview @li @ref trefcount_overview @@ -50,9 +50,9 @@ @li @ref windowdeletion_overview @li @ref windowids_overview @li @ref envvars_overview - + @section topics_nongui Overviews of non-GUI classes - + @li @ref string_overview @li @ref bufferclasses_overview @li @ref datetime_overview @@ -65,18 +65,18 @@ @li @ref resyn_overview @li @ref arc_overview @li @ref ipc_overview - + @section topics_drawing Drawing related classes - + @li @ref dc_overview @li @ref bitmap_overview @li @ref font_overview @li @ref fontencoding_overview @li @ref printing_overview @li @ref unixprinting_overview - + @section topics_gui Overviews of GUI classes - + @li @ref sizer_overview @li @ref xrc_overview @li @ref windowsizing_overview @@ -86,9 +86,9 @@ @li @ref dataobject_overview @li @ref dnd_overview @li @ref constraints_overview - + @section topics_indivctrl Overviews of individual controls - + @li @ref html_overview @li @ref richtextctrl_overview @li @ref aui_overview -- 2.45.2