@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
@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
@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
@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
@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
@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
@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.
@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
@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
@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
@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<T>: A type-safe dynamic array implementation (macro based)
@li wxArrayString: An efficient container for storing wxString objects
@li wxHashMap<T>: A type-safe hash map implementation (macro based)
@li wxHashTable: A simple hash table implementation (deprecated, use wxHashMap)
@li wxList<T>: A type-safe linked list implementation (macro based)
@li wxVector<T>: Template base vector implementation identical to std::vector
-
-
+
+
@section cat_smartpointers Smart pointers
-
+
wxWidgets provides a few smart pointer class templates.
-
+
@li wxObjectDataPtr<T>: A shared pointer (using intrusive reference counting)
@li wxScopedPtr<T>: A scoped pointer
@li wxSharedPtr<T>: A shared pointer (using non-intrusive reference counting)
@li wxWeakRef<T>: 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
@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
@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
@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
@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
@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
@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
@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
@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
@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
@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.
@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
@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
@section cppconst Preprocessor symbols defined by wxWidgets
-
+
*/
Portions (c) 1996 Artificial Intelligence Applications Institute
</center>
-
- 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.
@ref wxlicense
@ref gnulicense
-
+
*/
/*!
@page wxlicense wxWindows Library License, Version 3.1
-
+
<!--
-
+
NB: this is exact copy of docs/licence.txt file. DO NOT modify this
section, it MUST be identical to docs/licence.txt!
-
+
-->
-
+
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.
-
+
<center>
WXWINDOWS LIBRARY LICENCE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
</center>
-
+
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
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
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
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
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.
-
+
<center>
GNU LIBRARY GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
</center>
-
+
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
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
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
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
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
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
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
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
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,
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
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
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
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
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
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
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
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
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
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
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.
-
-
+
+
<center>
END OF TERMS AND CONDITIONS
</center>
-
+
@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
<one line to give the library's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
-
+
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.
-
+
<signature of Ty Coon>, 1 April 1990
Ty Coon, President of Vice
@endverbatim
-
-
+
+
That's all there is to it!
*/
<hr>
-
+
@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 <wx/wxprec.h>
-
+
#ifdef __BORLANDC__
#pragma hdrstop
#endif
-
+
#ifndef WX_PRECOMP
// Include your minimal set of headers here, or wx.h
#include <wx/wx.h>
#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
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
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
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
/*!
@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.
<hr>
@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.
*/
@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
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
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.
\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.
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
\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
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.}
-
+
*/
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) }
\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} }
\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.
-
+
*/
/*!
-
+
@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
@li @ref topic_page
@li @ref platformdetails_page
- <!-- @li Alphabetical class reference
+ <!-- @li Alphabetical class reference
@li Functions and macros -->
*/
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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.
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
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
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
{
...
};
@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
{
wxCHMHelpController *m_helpCtrl;
...
};
-
+
bool MyApp::OnInit()
{
...
m_helpCtrl = new wxCHMHelpController;
...
}
-
+
int MyApp::OnExit()
{
delete m_helpCtrl;
return 0;
}
@endcode
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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'.
(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
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
// 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
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.
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()];
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
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
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
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'
// 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";
}
}
@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.
@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
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
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
{
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
@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
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
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.
+
+ */
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
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);
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
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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page commondialogs_overview Common dialogs overview
-
+
Classes: #wxColourDialog, #wxFontDialog,
#wxPrintDialog, #wxFileDialog,
#wxDirDialog, #wxTextEntryDialog,
@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.
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);
wxColour colour(i*16, i*16, i*16);
data.SetCustomColour(i, colour);
}
-
+
wxColourDialog dialog(this, );
if (dialog.ShowModal() == wxID_OK)
{
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.
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)
{
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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
@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
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
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
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);
b3-bottom.SameAs (frame-panel, wxBottom, 5);
mtext-SetConstraints(b3);
@endcode
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
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
wxArrayString is somewhat special: it is an optimized version of wxArray which
uses its knowledge about #wxString reference counting
schema.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page dataobject_overview wxDataObject overview
-
+
Classes: #wxDataObject,
#wxClipboard,
#wxDataFormat,
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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page datetime_overview Date and time classes overview
-
+
Classes: #wxDateTime, #wxDateSpan, #wxTimeSpan, #wxCalendarCtrl
#Introduction
@ref alldatetimeclasses_overview
#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
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
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.
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
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
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
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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page dc_overview Device context overview
-
+
Classes: #wxBufferedDC, #wxBufferedPaintDC, #wxDC, #wxPostScriptDC,
#wxMetafileDC, #wxMemoryDC, #wxPrinterDC,
#wxScreenDC, #wxClientDC, #wxPaintDC,
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.
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)
{
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
#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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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.
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,
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,
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;
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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.
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
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.
+
+ */
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page docview_overview Document/view overview
-
+
Classes: #wxDocument, #wxView, #wxDocTemplate,
#wxDocManager, #wxDocParentFrame, #wxDocChildFrame,
#wxDocMDIParentFrame, #wxDocMDIChildFrame,
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
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
@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
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
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
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,
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,
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
@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));
(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)
wxID_PRINT (5010)
wxID_PRINT_SETUP (5011)
wxID_PREVIEW (5012)
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
@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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page eventhandling_overview Event handling overview
-
+
Classes: #wxEvtHandler, #wxWindow, #wxEvent
#Introduction
@ref eventprocessing_overview
@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.
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)
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.
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
{
...
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
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
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)
{
// 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
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
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,
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
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
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
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
#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
#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
#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
#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
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.
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() );
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() );
GetEventHandler()-ProcessEvent( event );
}
@endcode
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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.
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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.
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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.
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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.
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
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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'
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
{
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
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()
{
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))
{
"About Hello World", wxOK | wxICON_INFORMATION );
}
@endcode
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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,
@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"
"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!"
@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.
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@
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"
/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
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.
@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
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:
@b TAGS_MODULE_END(@e modname)
Ends the definition of module.
@b Example:
-
+
@code
TAGS_MODULE_BEGIN(Examples)
TAGS_MODULE_ADD(VARS_ONLY)
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
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]
U
UL
@endcode
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
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
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.
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page ipc_overview Interprocess communication overview
-
+
Classes: #wxServer,
#wxConnection,
#wxClient
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
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
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
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
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
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
@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).
member can return a wxConnection of the required class, when a
connection is made.
For example:
-
+
@code
class MyConnection: public wxConnection {
public:
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.
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");
}
connection-StartAdvise("Item");
@endcode
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page listctrl_overview wxListCtrl overview
-
+
Classes: #wxListCtrl, #wxImageList
Sorry, this topic has yet to be written.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
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
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.
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
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.
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,
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
#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
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
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.
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
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.)
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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.
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.
"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.
"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
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))
{
}
...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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
@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
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:
{
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
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
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
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,
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
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
queries these data structures to get information like the printed page range
(from the wxPrintDialogData) or the paper size and/or page orientation (from the
wxPageSetupDialogData).
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page python_overview wxPython overview
-
+
This topic was written by Robin Dunn, author of the wxPython wrapper.
@ref pwhat_overview
@ref pwhy_overview
@ref pusing_overview
@ref pclasses_overview
@ref phelp_overview
-
-
+
+
@section wxpwhat What is wxPython?
-
+
wxPython is a blending of the wxWidgets GUI classes and the
#Python programming language.
@b Python
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
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
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.
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 *
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
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
#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
#http://lists.wxwindows.org/mailman/listinfo/wxpython-users
Or you can send mail directly to the list using this address:
wxpython-users@lists.wxwindows.org
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page 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
used by wxWidgets.
The member functions are given in alphabetical order except for
constructors and destructors which appear first.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
@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
@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
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
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
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
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.
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
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
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
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',
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.
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
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'
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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 "));
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);
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
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
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
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)
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
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
#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
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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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.
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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.
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
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
@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
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
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
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.
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
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
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
#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
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
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
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
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
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).
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
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.
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
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
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)
but sometimes it depends on the user choices: wxCheckboxPage shows how to
dynamically decide which page to display next (see also
#wxWizardPage)
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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.
@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).
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
scrollbar calculations and SetScrollbar
call into a function named AdjustScrollbars, which can be called initially and also
from your #wxSizeEvent handler function.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
@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
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
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.
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
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.
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
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
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
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),
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" ),
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
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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)
{
rightWindow-Show(@true);
splitter-SplitVertically( leftWindow, rightWindow );
}
-
+
void MyFrame::OnSplitHorizontal(wxCommandEvent& event)
{
if ( splitter-IsSplit() )
rightWindow-Show(@true);
splitter-SplitHorizontally( leftWindow, rightWindow );
}
-
+
void MyFrame::OnUnsplit(wxCommandEvent& event)
{
if ( splitter-IsSplit() )
splitter-Unsplit();
}
@endcode
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page stream_overview wxStreams overview
-
+
Classes: #wxStreamBase,
#wxStreamBuffer, #wxInputStream,
#wxOutputStream,
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
@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
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page string_overview wxString overview
-
+
Classes: #wxString, #wxArrayString, #wxStringTokenizer
#Introduction
@ref otherstringclasses_overview
@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
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
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
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,
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
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
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).
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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.
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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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).
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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?... )
{
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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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.
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
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
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
// 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"
#include "bitmaps/preview.xpm"
#include "bitmaps/help.xpm"
#endif
-
+
IMPLEMENT_APP(MyApp)
-
+
// The `main program' equivalent, creating the windows and returning the
// main frame
bool MyApp::OnInit(void)
// Create the main frame window
MyFrame* frame = new MyFrame((wxFrame *) @NULL, -1, (const wxString) "wxToolBar Sample",
wxPoint(100, 100), wxSize(450, 300));
-
+
// Give it a status line
frame-CreateStatusBar();
-
+
// Give it an icon
frame-SetIcon(wxICON(mondrian));
-
+
// Make a menubar
wxMenu *fileMenu = new wxMenu;
fileMenu-Append(wxID_EXIT, "E", "Quit toolbar sample" );
-
+
wxMenu *helpMenu = new wxMenu;
helpMenu-Append(wxID_HELP, "", "About toolbar sample");
-
+
wxMenuBar* menuBar = new wxMenuBar;
-
+
menuBar-Append(fileMenu, "");
menuBar-Append(helpMenu, "");
-
+
// Associate the menu bar with the frame
frame-SetMenuBar(menuBar);
-
+
// Create the toolbar
frame-CreateToolBar(wxBORDER\_NONE|wxHORIZONTAL|wxTB_FLAT, ID_TOOLBAR);
-
+
frame-GetToolBar()-SetMargins( 2, 2 );
-
+
InitToolbar(frame-GetToolBar());
-
+
// Force a resize. This should probably be replaced by a call to a wxFrame
// function that lays out default decorations and the remaining content window.
wxSizeEvent event(wxSize(-1, -1), frame-GetId());
frame-OnSize(event);
frame-Show(@true);
-
+
frame-SetStatusText("Hello, wxWidgets");
-
+
SetTopWindow(frame);
-
+
return @true;
}
-
+
bool MyApp::InitToolbar(wxToolBar* toolBar)
{
// Set up toolbar
wxBitmap* toolBarBitmaps[8];
-
+
#ifdef __WXMSW__
toolBarBitmaps[0] = new wxBitmap("icon1");
toolBarBitmaps[1] = new wxBitmap("icon2");
toolBarBitmaps[6] = new wxBitmap( print_xpm );
toolBarBitmaps[7] = new wxBitmap( help_xpm );
#endif
-
+
#ifdef __WXMSW__
int width = 24;
#else
int width = 16;
#endif
int currentX = 5;
-
+
toolBar-AddTool(wxID_NEW, *(toolBarBitmaps[0]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "New file");
currentX += width + 5;
toolBar-AddTool(wxID_OPEN, *(toolBarBitmaps[1]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Open file");
currentX += width + 5;
toolBar-AddSeparator();
toolBar-AddTool(wxID_HELP, *(toolBarBitmaps[7]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Help");
-
+
toolBar-Realize();
-
+
// Can delete the bitmaps since they're reference counted
int i;
for (i = 0; i 8; i++)
delete toolBarBitmaps[i];
-
+
return @true;
}
-
+
// wxID_HELP will be processed for the 'About' menu and the toolbar help button.
-
+
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
EVT_MENU(wxID_EXIT, MyFrame::OnQuit)
EVT_MENU(wxID_HELP, MyFrame::OnAbout)
EVT_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):
{
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)
SetStatusText("");
}
@endcode
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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:
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
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.
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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.
@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
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
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
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
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
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
Note that the application will not require a GTK+ version = 2.10
to be installed in order to run (there will be no dependency on
this version).
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page 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
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.
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
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)
{
}
}
@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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
(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
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)
{
{
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
}
}
@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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page windowids_overview Window IDs overview
-
+
@b See Also
#wxIdManager
wxWindow::NewControlId
#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
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.
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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.
-
+
*/
-
-
+
+
/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@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
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
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
@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);
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;
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.
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
...
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;
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"
/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
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"
/object
/object
/resource
-
-
+
+
class TestWnd_Base : public wxFrame {
protected:
wxTextCtrl* A;
wxButton* B;
-
+
private:
void InitWidgetsFromXRC(){
wxXmlResource::Get()-LoadObject(this,@NULL,"TestWnd","wxFrame");
}
};
@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 ,
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
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.
-
+
*/
-
-
+
+
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
\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
@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
@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
@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
@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