@li @subpage page_introduction
@li @subpage page_multiplatform
@li @subpage page_utils
+ @li @subpage page_samples
@li @subpage page_strategies
@li @subpage page_libs
@li @subpage page_constants
--- /dev/null
+/////////////////////////////////////////////////////////////////////////////
+// Name: samples.h
+// Purpose: Samples page of the Doxygen manual
+// Author: wxWidgets team
+// RCS-ID: $Id: utilities.h 52634 2008-03-20 13:45:17Z VS $
+// Licence: wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+
+@page page_samples Samples supplied with wxWidgets
+
+Probably the best way to learn wxWidgets is by reading the source of some 70+
+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
+look at. This overview aims at describing what each sample does/demonstrates to
+make it easier to find the relevant one if a simple grep through all sources
+didn't help. They also provide some notes about using the samples and what
+features of wxWidgets are they supposed to test.
+
+There are currently more than 50 different samples as part of wxWidgets and
+this list is not complete. You should start your tour of wxWidgets with the
+minimal sample which is the wxWidgets version of
+"Hello, world!". It shows the basic structure of wxWidgets program and is the
+most commented sample of all - looking at its source code is recommended.
+
+The next most useful samples are probably widgets
+and controls which show many of wxWidgets native and
+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:
+
+@li wxCalendarCtrl: @ref page_samples_calendar
+@li wxListCtrl: @ref page_samples_listctrl
+@li wxTreeCtrl: @ref page_samples_treectrl
+@li wxGrid: @ref page_samples_grid
+
+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.
+
+@beginInvisibleTable
+<tr><td>
+@li @ref page_samples_minimal
+@li @ref page_samples_animate
+@li @ref page_samples_artprovider
+@li @ref page_samples_calendar
+@li @ref page_samples_config
+@li @ref page_samples_controls
+@li @ref page_samples_debugrpt
+@li @ref page_samples_dialogs
+@li @ref page_samples_dialup
+@li @ref page_samples_dnd
+@li @ref page_samples_event
+@li @ref page_samples_except
+@li @ref page_samples_exec
+@li @ref page_samples_font
+@li @ref page_samples_grid
+@li @ref page_samples_html
+@li @ref page_samples_image
+</td><td>
+@li @ref page_samples_internat
+@li @ref page_samples_layout
+@li @ref page_samples_listctrl
+@li @ref page_samples_mediaplayer
+@li @ref page_samples_notebook
+@li @ref page_samples_render
+@li @ref page_samples_scrollsub
+@li @ref page_samples_sockets
+@li @ref page_samples_sound
+@li @ref page_samples_statbar
+@li @ref page_samples_taborder
+@li @ref page_samples_text
+@li @ref page_samples_thread
+@li @ref page_samples_toolbar
+@li @ref page_samples_treectrl
+@li @ref page_samples_widgets
+@li @ref page_samples_wizard
+</td></tr>
+@endTable
+
+
+<hr>
+
+
+
+@section page_samples_minimal 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 page_samples_animate 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 page_samples_artprovider 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 page_samples_calendar Calendar sample
+
+This font shows the calendar control 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 page_samples_config 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 overview_config for the descriptions of all features of this class.
+
+
+@section page_samples_controls 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
+the controls programmatically, such as adding an item to a list box etc. Apart
+from that, the sample uses a wxNotebook and tests most
+features of this special control (using bitmap in the tabs, using
+wxSizer instances and wxLayoutConstraints within notebook pages, advancing pages
+programmatically and vetoing a page change by intercepting the wxNotebookEvent.
+
+The various controls tested are listed here:
+
+@li wxButton
+@li wxBitmapButton
+@li wxCheckBox
+@li wxChoice
+@li wxComboBox
+@li wxGauge
+@li wxStaticBox
+@li wxListBox
+@li wxSpinCtrl
+@li wxSpinButton
+@li wxStaticText
+@li wxStaticBitmap
+@li wxRadioBox
+@li wxRadioButton
+@li wxSlider
+
+
+@section page_samples_debugrpt 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
+generate debug report without doing it. Next it initializes the debug report
+with standard information adding a custom file to it (just a timestamp) and
+allows to view the information gathered using
+wxDebugReportPreview.
+
+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 page_samples_dialogs Dialogs sample
+
+This sample shows how to use the common dialogs available from wxWidgets. These
+dialogs are described in detail in the @ref overview_cmndlg.
+
+
+@section page_samples_dialup 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
+whether the connection is permanent (in which case a string `LAN' appears in
+the third status bar field - but note that you may be on a LAN not
+connected to the Internet, in which case you will not see this) or not.
+
+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 page_samples_dnd 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.
+
+When you run the sample, its screen is split in several parts. On the top,
+there are two listboxes which show the standard derivations of
+wxDropTarget:
+wxTextDropTarget and
+wxFileDropTarget.
+
+The middle of the sample window is taken by the log window which shows what is
+going on (of course, this only works in debug builds) and may be helpful to see
+the sequence of steps of data transfer.
+
+Finally, the last part is used for dragging text from it to either one of the
+listboxes (only one will accept it) or another application. The last
+functionality available from the main frame is to paste a bitmap from the
+clipboard (or, in the case of the Windows version, also a metafile) - it will be
+shown in a new frame.
+
+So far, everything we mentioned was implemented with minimal amount of code
+using standard wxWidgets classes. The more advanced features are demonstrated
+if you create a shape frame from the main frame menu. A shape is a geometric
+object which has a position, size and color. It models some
+application-specific data in this sample. A shape object supports its own
+private wxDataFormat which means that you may cut and
+paste it or drag and drop (between one and the same or different shapes) from
+one sample instance to another (or the same). However, chances are that no
+other program supports this format and so shapes can also be rendered as
+bitmaps which allows them to be pasted/dropped in many other applications
+(and, under Windows, also as metafiles which are supported by most of Windows
+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 page_samples_event 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 page_samples_except 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
+understand what goes on.
+
+You need to build the library with @c wxUSE_EXCEPTIONS being set to @c 1
+and compile your code with C++ exceptions support to be able to build this
+sample.
+
+
+@section page_samples_exec 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
+until the program terminates) or asynchronously (notification will come later).
+
+It also shows how to capture the output of the child process in both
+synchronous and asynchronous cases and how to kill the processes with
+wxProcess::Kill and test for their existence with
+wxProcess::Exists.
+
+
+@section page_samples_font 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 page_samples_grid Grid sample
+
+@todo WRITE THIS DESCRIPTION.
+
+
+@section page_samples_html HTML samples
+
+Eight HTML samples (you can find them in directory @c samples/html)
+cover all features of the HTML sub-library.
+
+@li @b Test demonstrates how to create wxHtmlWindow
+and also shows most supported HTML tags.
+
+@li @b Widget shows how you can embed ordinary controls or windows within an
+HTML page. It also nicely explains how to write new tag handlers and extend
+the library to work with unsupported tags.
+
+@li @b About may give you an idea how to write good-looking About boxes.
+
+@li @b Zip demonstrates use of virtual file systems in wxHTML. The zip archives
+handler (ships with wxWidgets) allows you to access HTML pages stored
+in a compressed archive as if they were ordinary files.
+
+@li @b Virtual is yet another virtual file systems demo. This one generates pages at run-time.
+You may find it useful if you need to display some reports in your application.
+
+@li @b Printing explains use of wxHtmlEasyPrinting
+class which serves as as-simple-as-possible interface for printing HTML
+documents without much work. In fact, only few function calls are sufficient.
+
+@li @b Help and @b Helpview are variations on displaying HTML help
+(compatible with MS HTML Help Workshop). @e Help shows how to embed
+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 page_samples_image 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
+of which is drawn directly in the window, the other one is drawn into a
+wxBitmap, converted to a wxImage, saved as a PNG image
+and then reloaded from the PNG file again so that conversions between wxImage
+and wxBitmap as well as loading and saving PNG files are tested.
+
+At the bottom of the main frame there is a test for using a monochrome bitmap by
+drawing into a wxMemoryDC. The bitmap is then drawn
+specifying the foreground and background colours with
+wxDC::SetTextForeground and
+wxDC::SetTextBackground (on the left). The
+bitmap is then converted to a wxImage and the foreground colour (black) is
+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 page_samples_internat 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
+program messages into another language while true i18n would also involve
+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 also see the @ref overview_i18n.
+
+
+@section page_samples_layout 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
+you resize the entire frame and the exact behaviour of the size changes
+is determined using the wxLayoutConstraints
+class. See also the overview and the
+wxIndividualLayoutConstraint
+class for further information.
+
+The menu in this sample offers two more tests, one showing how to use
+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 page_samples_listctrl 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 page_samples_mediaplayer 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 page_samples_notebook 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 page_samples_render 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 page_samples_scrollsub 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
+of scrolling does not show in the scrolled window itself, but in one of its subwindows.
+
+Additionally, this samples demonstrates how to optimize drawing operations in wxWidgets,
+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 page_samples_sockets 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
+wxSocketServer object, and a client, which
+is implemented as a wxSocketClient.
+
+The server binds to the local address, using TCP port number 3000,
+sets up an event handler to be notified of incoming connection requests
+(@b wxSOCKET_CONNECTION events), and sits there, waiting for clients
+(@e listening, in socket parlance). For each accepted connection,
+a new wxSocketBase object is created. These
+socket objects are independent from the server that created them, so
+they set up their own event handler, and then request to be notified
+of @b wxSOCKET_INPUT (incoming data) or @b wxSOCKET_LOST
+(connection closed at the remote end) events. In the sample, the event
+handler is the same for all connections; to find out which socket the
+event is addressed to, the GetSocket function
+is used.
+
+Although it might take some time to get used to the event-oriented
+system upon which wxSocket is built, the benefits are many. See, for
+example, that the server application, while being single-threaded
+(and of course without using fork() or ugly select() loops) can handle
+an arbitrary number of connections.
+
+The client starts up unconnected, so you can use the Connect... option
+to specify the address of the server you are going to connect to (the
+TCP port number is hard-coded as 3000). Once connected, a number of
+tests are possible. Currently, three tests are implemented. They show
+how to use the basic IO calls in wxSocketBase,
+such as wxSocketBase::Read, wxSocketBase::Write,
+wxSocketBase::ReadMsg and wxSocketBase::WriteMsg,
+and how to set up the correct IO flags depending on what you are going to
+do. See the comments in the code for more information. Note that because
+both clients and connection objects in the server set up an event handler
+to catch @b wxSOCKET_LOST events, each one is immediately notified
+if the other end closes the connection.
+
+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:
+
+@li More tests for basic socket functionality.
+@li More tests for protocol classes (wxProtocol and its descendants).
+@li Tests for the recently added (and still in alpha stage) datagram sockets.
+@li New samples which actually do something useful (suggestions accepted).
+
+
+@section page_samples_sound Sound sample
+
+The @c sound sample shows how to use wxSound for simple
+audio output (e.g. notifications).
+
+
+@section page_samples_statbar 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 page_samples_taborder Tab order sample
+
+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
+MoveAfterInTabOrder() methods to change
+the default order of the windows in the navigation chain and of
+wxWindow::Navigate() for moving focus along this
+chain.
+
+
+@section page_samples_text 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).
+
+Secondly it shows how to intercept a wxKeyEvent in both
+the raw form using the @c EVT_KEY_UP and @c EVT_KEY_DOWN macros and the
+higher level from using the @c EVT_CHAR macro. All characters will be logged
+in a log window at the bottom of the main window. By pressing some of the function
+keys, you can test some actions in the text ctrl as well as get statistics on the
+text ctrls, which is useful for testing if these statistics actually are correct.
+
+Thirdly, on platforms which support it, the sample will offer to copy text to the
+wxClipboard and to paste text from it. The GTK version will
+use the so called PRIMARY SELECTION, which is the pseudo clipboard under X and
+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 page_samples_thread 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
+is not multi-threading safe, i.e. that it might crash if two threads try to
+access the GUI class simultaneously. One way to prevent that is have a normal
+GUI program in the main thread and some worker threads which work in the
+background. In order to make communication between the main thread and the
+worker threads possible, wxWidgets offers the wxPostEvent
+function and this sample makes use of this function.
+
+The other way to use a so called Mutex (such as those offered in the wxMutex
+class) that prevent threads from accessing the GUI classes as long as any other
+thread accesses them. For this, wxWidgets has the wxMutexGuiEnter
+and wxMutexGuiLeave functions, both of which are
+used and tested in the sample as well.
+
+See also @ref overview_thread and wxThread.
+
+
+@section page_samples_toolbar Toolbar sample
+
+The toolbar sample shows the wxToolBar class in action.
+
+The following things are demonstrated:
+
+@li Creating the toolbar using wxToolBar::AddTool and wxToolBar::AddControl: see
+ MyApp::InitToolbar in the sample.
+@li Using @c EVT_UPDATE_UI handler for automatically enabling/disabling
+ toolbar buttons without having to explicitly call EnableTool. This is done
+ in MyFrame::OnUpdateCopyAndCut.
+@li 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
+in it.
+
+If you toggle another toolbar in the sample (using @c Ctrl-A) you will also
+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 page_samples_treectrl 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
+the bottom part of the frame).
+
+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 page_samples_widgets 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 page_samples_wizard Wizard sample
+
+This sample shows the so-called wizard dialog (implemented using
+wxWizard and related classes). It shows almost all
+features supported:
+
+@li 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)
+@li Using TransferDataFromWindow
+ to verify that the data entered is correct before passing to the next page
+ (done in wxValidationPage which forces the user to check a checkbox before
+ continuing).
+@li Using more elaborated techniques to allow returning to the previous
+ page, but not continuing to the next one or vice versa (in wxRadioboxPage)
+@li This (wxRadioboxPage) page also shows how the page may process the
+ @e Cancel button itself instead of relying on the wizard parent to do it.
+@li Normally, the order of the pages in the wizard is known at compile-time,
+ but sometimes it depends on the user choices: wxCheckboxPage shows how to
+ dynamically decide which page to display next (see also
+ wxWizardPage)
+
+*/
/**
- @page page_utils Utilities and samples supplied with wxWidgets
+@page page_utils Utilities supplied with wxWidgets
- @li @ref page_utils_utils
- @li @ref page_utils_samples
+In addition to the wxWidgets libraries (see @ref page_libs), some utilities
+are available to the users in the @c utils hierarchy (even if some of them are
+explicitely coinceived for wxWidgets maintainance and will probably be of
+little use to others).
+Please note that these utilities do represent only the utilities developed
+and maintained by the wxWidgets team.
+There are lots of other user-contributed and user-maintained packages;
+see the wxWidgets download page: http://www.wxwidgets.org/downloads
+or directly http://wxcode.sourceforge.net or http://www.wxcommunity.com/ .
- <hr>
+@li @ref page_utils_emulator
+@li @ref page_utils_helpgen
+@li @ref page_utils_helpview
+@li @ref page_utils_hhp2cached
+@li @ref page_utils_tex2rtf
+@li @ref page_utils_wxrc
- @section page_utils_utils Utilities
+<hr>
- In addition to the @ref page_libs, some
- additional utilities are supplied in the @c utils hierarchy.
- For other user-contributed packages, please see the Contributions page
- on the wxWidgets Web site http://www.wxwidgets.org.
+@section page_utils_emulator Emulator
+Xnest-based display emulator for X11-based PDA applications.
- @subsection page_utils_utils_helpview Helpview
+<!-- On some systems, the Xnest window does not synchronise with the
+'skin' window. THIS ISN'T THE PLACE FOR THIS STATEMENT I THINK -->
- Helpview is a program for displaying wxWidgets HTML
- Help files. In many cases, you may wish to use the wxWidgets HTML
- Help classes from within your application, but this provides a
- handy stand-alone viewer. See @ref overview_html for more details.
- You can find it in @c samples/html/helpview.
+This program can be found in @c utils/emulator.
- @subsection page_utils_utils_tex2rtf Tex2RTF
- Supplied with wxWidgets is a utility called Tex2RTF for
- converting @e LaTeX manuals HTML, MS HTML Help, wxHTML Help, RTF, and Windows
- Help RTF formats. Tex2RTF was used for the wxWidgets manuals and can be used
- independently by authors wishing to create on-line and printed manuals from the
- same @e LaTeX source. Please see the separate documentation for Tex2RTF.
- You can find it under @c utils/tex2rtf.
+@section page_utils_helpgen Helpgen
- @subsection page_utils_utils_helpgen Helpgen
+Helpgen takes C++ header files and generates a Tex2RTF-compatible
+documentation file for each class it finds, using comments as appropriate.
+This is a good way to start a reference for a set of classes.
- Helpgen takes C++ header files and generates a Tex2RTF-compatible
- documentation file for each class it finds, using comments as appropriate.
- This is a good way to start a reference for a set of classes.
- Helpgen can be found in @c utils/HelpGen.
+Helpgen can be found in @c utils/HelpGen.
- @subsection page_utils_utils_emulator Emulator
- Xnest-based display emulator for X11-based PDA applications.
- On some systems, the Xnest window does not synchronise with the
- 'skin' window. This program can be found in @c utils/emulator.
+@section page_utils_helpview Helpview
+Helpview is a program for displaying wxWidgets HTML
+Help files. In many cases, you may wish to use the wxWidgets HTML
+Help classes from within your application, but this provides a
+handy stand-alone viewer. See @ref overview_html for more details.
+You can find Helpview in @c utils/helpview.
- @section page_utils_samples Samples
+@section page_utils_hhp2cached HHP2Cached
- 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
- look at. This overview aims at describing what each sample does/demonstrates to
- make it easier to find the relevant one if a simple grep through all sources
- didn't help. They also provide some notes about using the samples and what
- features of wxWidgets are they supposed to test.
+This utility creates a "cached" version of a @c .hhp file; using cached @c .hhp
+files in wxHtmlHelpController can drammatically improve the performances
+of the help viewer. See wxHtmlHelpController for more details.
- There are currently more than 50 different samples as part of wxWidgets and
- this list is not complete. You should start your tour of wxWidgets with the
- minimal sample which is the wxWidgets version of
- "Hello, world!". It shows the basic structure of wxWidgets program and is the
- most commented sample of all - looking at its source code is recommended.
+You can find HHP2Cached in @c utils/helpview.
- The next most useful samples are probably widgets
- and controls which show many of wxWidgets native and
- 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:
+@section page_utils_tex2rtf Tex2RTF
- @li wxCalendarCtrl: @ref page_utils_samples_calendar
- @li wxListCtrl: @ref page_utils_samples_listctrl
- @li wxTreeCtrl: @ref page_utils_samples_treectrl
- @li wxGrid: @ref page_utils_samples_grid
+Supplied with wxWidgets is a utility called Tex2RTF for
+converting @e LaTeX manuals HTML, MS HTML Help, wxHTML Help, RTF, and Windows
+Help RTF formats. Tex2RTF was used for the wxWidgets manuals and can be used
+independently by authors wishing to create on-line and printed manuals from the
+same @e LaTeX source. Please see the separate documentation for Tex2RTF.
- 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.
+You can find it under @c utils/tex2rtf.
- @subsection page_utils_samples_minimal Minimal sample
+@section page_utils_wxrc WxRC
- 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.
+This utility allows the user to compile @e binary versions of their XRC files,
+which are compressed and can be loaded faster than plain XRC files.
+See @ref overview_xrc for more info.
+You can find it under @c utils/wxrc.
- @subsection page_utils_samples_animate Animate sample
-
- The @c animate sample shows how you can use wxAnimationCtrl
- control and shows concept of a platform-dependent animation encapsulated
- in wxAnimation.
-
-
- @subsection page_utils_samples_artprovider 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.
-
-
- @subsection page_utils_samples_calendar Calendar sample
-
- This font shows the calendar control 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.
-
-
- @subsection page_utils_samples_config 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 overview_config for the descriptions of all features of this class.
-
-
- @subsection page_utils_samples_controls 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
- the controls programmatically, such as adding an item to a list box etc. Apart
- from that, the sample uses a wxNotebook and tests most
- features of this special control (using bitmap in the tabs, using
- wxSizer instances and wxLayoutConstraints within notebook pages, advancing pages
- programmatically and vetoing a page change by intercepting the wxNotebookEvent.
-
- The various controls tested are listed here:
-
- @li wxButton
- @li wxBitmapButton
- @li wxCheckBox
- @li wxChoice
- @li wxComboBox
- @li wxGauge
- @li wxStaticBox
- @li wxListBox
- @li wxSpinCtrl
- @li wxSpinButton
- @li wxStaticText
- @li wxStaticBitmap
- @li wxRadioBox
- @li wxRadioButton
- @li wxSlider
-
-
- @subsection page_utils_samples_debugrpt 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
- generate debug report without doing it. Next it initializes the debug report
- with standard information adding a custom file to it (just a timestamp) and
- allows to view the information gathered using
- wxDebugReportPreview.
-
- 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.
-
-
- @subsection page_utils_samples_dialogs Dialogs sample
-
- This sample shows how to use the common dialogs available from wxWidgets. These
- dialogs are described in detail in the @ref overview_cmndlg.
-
-
- @subsection page_utils_samples_dialup 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
- whether the connection is permanent (in which case a string `LAN' appears in
- the third status bar field - but note that you may be on a LAN not
- connected to the Internet, in which case you will not see this) or not.
-
- 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.
-
-
- @subsection page_utils_samples_dnd 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.
-
- When you run the sample, its screen is split in several parts. On the top,
- there are two listboxes which show the standard derivations of
- wxDropTarget:
- wxTextDropTarget and
- wxFileDropTarget.
-
- The middle of the sample window is taken by the log window which shows what is
- going on (of course, this only works in debug builds) and may be helpful to see
- the sequence of steps of data transfer.
-
- Finally, the last part is used for dragging text from it to either one of the
- listboxes (only one will accept it) or another application. The last
- functionality available from the main frame is to paste a bitmap from the
- clipboard (or, in the case of the Windows version, also a metafile) - it will be
- shown in a new frame.
-
- So far, everything we mentioned was implemented with minimal amount of code
- using standard wxWidgets classes. The more advanced features are demonstrated
- if you create a shape frame from the main frame menu. A shape is a geometric
- object which has a position, size and color. It models some
- application-specific data in this sample. A shape object supports its own
- private wxDataFormat which means that you may cut and
- paste it or drag and drop (between one and the same or different shapes) from
- one sample instance to another (or the same). However, chances are that no
- other program supports this format and so shapes can also be rendered as
- bitmaps which allows them to be pasted/dropped in many other applications
- (and, under Windows, also as metafiles which are supported by most of Windows
- programs as well - try Write/Wordpad, for example).
-
- Take a look at DnDShapeDataObject class to see how you may use
- wxDataObject to achieve this.
-
-
- @subsection page_utils_samples_event 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().
-
-
- @subsection page_utils_samples_except 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
- understand what goes on.
-
- You need to build the library with @c wxUSE_EXCEPTIONS being set to @c 1
- and compile your code with C++ exceptions support to be able to build this
- sample.
-
-
- @subsection page_utils_samples_exec 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
- until the program terminates) or asynchronously (notification will come later).
-
- It also shows how to capture the output of the child process in both
- synchronous and asynchronous cases and how to kill the processes with
- wxProcess::Kill and test for their existence with
- wxProcess::Exists.
-
-
- @subsection page_utils_samples_font 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.
-
-
- @subsection page_utils_samples_grid Grid sample
-
- TODO.
-
-
- @subsection page_utils_samples_html HTML samples
-
- Eight HTML samples (you can find them in directory @c samples/html)
- cover all features of the HTML sub-library.
-
- @li @b Test demonstrates how to create wxHtmlWindow
- and also shows most supported HTML tags.
-
- @li @b Widget shows how you can embed ordinary controls or windows within an
- HTML page. It also nicely explains how to write new tag handlers and extend
- the library to work with unsupported tags.
-
- @li @b About may give you an idea how to write good-looking About boxes.
-
- @li @b Zip demonstrates use of virtual file systems in wxHTML. The zip archives
- handler (ships with wxWidgets) allows you to access HTML pages stored
- in a compressed archive as if they were ordinary files.
-
- @li @b Virtual is yet another virtual file systems demo. This one generates pages at run-time.
- You may find it useful if you need to display some reports in your application.
-
- @li @b Printing explains use of wxHtmlEasyPrinting
- class which serves as as-simple-as-possible interface for printing HTML
- documents without much work. In fact, only few function calls are sufficient.
-
- @li @b Help and @b Helpview are variations on displaying HTML help
- (compatible with MS HTML Help Workshop). @e Help shows how to embed
- 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.
-
-
- @subsection page_utils_samples_image 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
- of which is drawn directly in the window, the other one is drawn into a
- wxBitmap, converted to a wxImage, saved as a PNG image
- and then reloaded from the PNG file again so that conversions between wxImage
- and wxBitmap as well as loading and saving PNG files are tested.
-
- At the bottom of the main frame there is a test for using a monochrome bitmap by
- drawing into a wxMemoryDC. The bitmap is then drawn
- specifying the foreground and background colours with
- wxDC::SetTextForeground and
- wxDC::SetTextBackground (on the left). The
- bitmap is then converted to a wxImage and the foreground colour (black) is
- 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.
-
-
- @subsection page_utils_samples_internat 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
- program messages into another language while true i18n would also involve
- 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 also see the @ref overview_i18n.
-
-
- @subsection page_utils_samples_layout 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
- you resize the entire frame and the exact behaviour of the size changes
- is determined using the wxLayoutConstraints
- class. See also the overview and the
- wxIndividualLayoutConstraint
- class for further information.
-
- The menu in this sample offers two more tests, one showing how to use
- a wxBoxSizer in a simple dialog and the other one
- showing how to use sizers in connection with a wxNotebook
- class. See also wxSizer.
-
-
- @subsection page_utils_samples_listctrl 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.
-
-
- @subsection page_utils_samples_mediaplayer 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.
-
-
- @subsection page_utils_samples_notebook 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.
-
-
- @subsection page_utils_samples_render 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.
-
-
- @subsection page_utils_samples_scrollsub 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
- of scrolling does not show in the scrolled window itself, but in one of its subwindows.
-
- Additionally, this samples demonstrates how to optimize drawing operations in wxWidgets,
- 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.
-
-
- @subsection page_utils_samples_sockets 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
- wxSocketServer object, and a client, which
- is implemented as a wxSocketClient.
-
- The server binds to the local address, using TCP port number 3000,
- sets up an event handler to be notified of incoming connection requests
- (@b wxSOCKET_CONNECTION events), and sits there, waiting for clients
- (@e listening, in socket parlance). For each accepted connection,
- a new wxSocketBase object is created. These
- socket objects are independent from the server that created them, so
- they set up their own event handler, and then request to be notified
- of @b wxSOCKET_INPUT (incoming data) or @b wxSOCKET_LOST
- (connection closed at the remote end) events. In the sample, the event
- handler is the same for all connections; to find out which socket the
- event is addressed to, the GetSocket function
- is used.
-
- Although it might take some time to get used to the event-oriented
- system upon which wxSocket is built, the benefits are many. See, for
- example, that the server application, while being single-threaded
- (and of course without using fork() or ugly select() loops) can handle
- an arbitrary number of connections.
-
- The client starts up unconnected, so you can use the Connect... option
- to specify the address of the server you are going to connect to (the
- TCP port number is hard-coded as 3000). Once connected, a number of
- tests are possible. Currently, three tests are implemented. They show
- how to use the basic IO calls in wxSocketBase,
- such as wxSocketBase::Read, wxSocketBase::Write,
- wxSocketBase::ReadMsg and wxSocketBase::WriteMsg,
- and how to set up the correct IO flags depending on what you are going to
- do. See the comments in the code for more information. Note that because
- both clients and connection objects in the server set up an event handler
- to catch @b wxSOCKET_LOST events, each one is immediately notified
- if the other end closes the connection.
-
- 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:
-
- @li More tests for basic socket functionality.
- @li More tests for protocol classes (wxProtocol and its descendants).
- @li Tests for the recently added (and still in alpha stage) datagram sockets.
- @li New samples which actually do something useful (suggestions accepted).
-
-
- @subsection page_utils_samples_sound Sound sample
-
- The @c sound sample shows how to use wxSound for simple
- audio output (e.g. notifications).
-
-
- @subsection page_utils_samples_statbar 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.
-
-
- @subsection page_utils_samples_taborder Tab order sample
-
- 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
- MoveAfterInTabOrder() methods to change
- the default order of the windows in the navigation chain and of
- wxWindow::Navigate() for moving focus along this
- chain.
-
-
- @subsection page_utils_samples_text 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).
-
- Secondly it shows how to intercept a wxKeyEvent in both
- the raw form using the @c EVT_KEY_UP and @c EVT_KEY_DOWN macros and the
- higher level from using the @c EVT_CHAR macro. All characters will be logged
- in a log window at the bottom of the main window. By pressing some of the function
- keys, you can test some actions in the text ctrl as well as get statistics on the
- text ctrls, which is useful for testing if these statistics actually are correct.
-
- Thirdly, on platforms which support it, the sample will offer to copy text to the
- wxClipboard and to paste text from it. The GTK version will
- use the so called PRIMARY SELECTION, which is the pseudo clipboard under X and
- 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.
-
-
- @subsection page_utils_samples_thread 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
- is not multi-threading safe, i.e. that it might crash if two threads try to
- access the GUI class simultaneously. One way to prevent that is have a normal
- GUI program in the main thread and some worker threads which work in the
- background. In order to make communication between the main thread and the
- worker threads possible, wxWidgets offers the wxPostEvent
- function and this sample makes use of this function.
-
- The other way to use a so called Mutex (such as those offered in the wxMutex
- class) that prevent threads from accessing the GUI classes as long as any other
- thread accesses them. For this, wxWidgets has the wxMutexGuiEnter
- and wxMutexGuiLeave functions, both of which are
- used and tested in the sample as well.
-
- See also @ref overview_thread and wxThread.
-
-
- @subsection page_utils_samples_toolbar Toolbar sample
-
- The toolbar sample shows the wxToolBar class in action.
-
- The following things are demonstrated:
-
- @li Creating the toolbar using wxToolBar::AddTool and wxToolBar::AddControl: see
- MyApp::InitToolbar in the sample.
- @li Using @c EVT_UPDATE_UI handler for automatically enabling/disabling
- toolbar buttons without having to explicitly call EnableTool. This is done
- in MyFrame::OnUpdateCopyAndCut.
- @li 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
- in it.
-
- If you toggle another toolbar in the sample (using @c Ctrl-A) you will also
- 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.
-
-
- @subsection page_utils_samples_treectrl 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
- the bottom part of the frame).
-
- 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.
-
-
- @subsection page_utils_samples_widgets 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.
-
-
- @subsection page_utils_samples_wizard Wizard sample
-
- This sample shows the so-called wizard dialog (implemented using
- wxWizard and related classes). It shows almost all
- features supported:
-
- @li 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)
- @li Using TransferDataFromWindow
- to verify that the data entered is correct before passing to the next page
- (done in wxValidationPage which forces the user to check a checkbox before
- continuing).
- @li Using more elaborated techniques to allow returning to the previous
- page, but not continuing to the next one or vice versa (in wxRadioboxPage)
- @li This (wxRadioboxPage) page also shows how the page may process the
- @e Cancel button itself instead of relying on the wizard parent to do it.
- @li Normally, the order of the pages in the wizard is known at compile-time,
- but sometimes it depends on the user choices: wxCheckboxPage shows how to
- dynamically decide which page to display next (see also
- wxWizardPage)
*/
@li wxTreebook: controlled by a wxTreeCtrl
@li wxToolbook: controlled by a wxToolBar
-See the @ref page_utils_samples_notebook for an example of wxBookCtrl usage.
+See the @ref page_samples_notebook for an example of wxBookCtrl usage.
@section overview_bookctrl_bestbookctrl Best Book
/**
- @page overview_dataobject wxDataObject Overview
+@page overview_dataobject wxDataObject Overview
- Classes: wxDataObject, wxClipboard, wxDataFormat, wxDropSource, wxDropTarget
+Classes: wxDataObject, wxClipboard, wxDataFormat, wxDropSource, wxDropTarget
- See also: @ref overview_dnd and @ref page_utils_samples_dnd
+See also: @ref overview_dnd and @ref page_samples_dnd
- This overview discusses data transfer through clipboard or drag and drop.
- In wxWidgets, these two ways to transfer data (either between different
- applications or inside one and the same) are very similar which allows to
- 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.
+This overview discusses data transfer through clipboard or drag and drop.
+In wxWidgets, these two ways to transfer data (either between different
+applications or inside one and the same) are very similar which allows to
+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
- 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
- clipboard. wxDataObject is a "smart" piece of data because it knows which
- formats it supports (see GetFormatCount and GetAllFormats) and knows how to
- render itself in any of them (see GetDataHere). It can also receive its value
- from the outside in a format it supports if it implements the SetData method.
- Please see the documentation of this class for more details.
+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
+clipboard. wxDataObject is a "smart" piece of data because it knows which
+formats it supports (see GetFormatCount and GetAllFormats) and knows how to
+render itself in any of them (see GetDataHere). It can also receive its value
+from the outside in a format it supports if it implements the SetData method.
+Please see the documentation of this class for more details.
- Both clipboard and drag and drop operations have two sides: the source and
- target, the data provider and the data receiver. These which may be in the same
- application and even the same window when, for example, you drag some text from
- one position to another in a word processor. Let us describe what each of them
- should do.
+Both clipboard and drag and drop operations have two sides: the source and
+target, the data provider and the data receiver. These which may be in the same
+application and even the same window when, for example, you drag some text from
+one position to another in a word processor. Let us describe what each of them
+should do.
- @li @ref overview_dataobject_source
- @li @ref overview_dataobject_target
+@li @ref overview_dataobject_source
+@li @ref overview_dataobject_target
- <hr>
+<hr>
- @section overview_dataobject_source The data provider (source) duties
+@section overview_dataobject_source The data provider (source) duties
- 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
- wxClipboard::SetData function or to wxDropSource and call wxDropSource::DoDragDrop
- function.
+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
+wxClipboard::SetData function or to wxDropSource and call wxDropSource::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
- wxDropSource::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).
+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
+wxDropSource::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
- wxDropSource::DoDragDrop returns (from its return value).
+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
+wxDropSource::DoDragDrop returns (from its return value).
- @section overview_dataobject_target The data receiver (target) duties
+@section overview_dataobject_target 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 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.
+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 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 virtual function will be called
- when a data object is dropped, from which the data itself may be requested by calling
- wxDropTarget::GetData method which fills the data object.
+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
+wxDropTarget::GetData method which fills the data object.
*/
/**
- @page overview_dnd Drag and Drop Overview
+@page overview_dnd Drag and Drop Overview
- Classes: wxDataObject, wxTextDataObject, wxDropSource, wxDropTarget,
- wxTextDropTarget, wxFileDropTarget
+Classes: wxDataObject, wxTextDataObject, wxDropSource, wxDropTarget,
+ wxTextDropTarget, wxFileDropTarget
- Note that @c wxUSE_DRAG_AND_DROP must be defined in @c setup.h in order
- to use drag and drop in wxWidgets.
+Note that @c wxUSE_DRAG_AND_DROP must be defined in @c setup.h in order
+to use drag and drop in wxWidgets.
- See also: @ref overview_dataobject and @ref page_utils_samples_dnd.
+See also: @ref overview_dataobject and @ref page_samples_dnd.
- It may be noted that data transfer to and from the clipboard is quite
- similar to data transfer with drag and drop and the code to implement
- these two types is almost the same. In particular, both data transfer
- mechanisms store data in some kind of wxDataObject and identify its format(s)
- using the wxDataFormat class.
+It may be noted that data transfer to and from the clipboard is quite
+similar to data transfer with drag and drop and the code to implement
+these two types is almost the same. In particular, both data transfer
+mechanisms store data in some kind of wxDataObject and identify its format(s)
+using the wxDataFormat 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:
+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:
- @li @b Preparation: First of all, a data object must be created and
- initialized with the data you wish to drag. For example:
+@li @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
+ @code
+ wxTextDataObject my_data("This text will be dragged.");
+ @endcode
- @li <b>Drag start</b>: To start the dragging process (typically in response to a
- mouse click) you must call wxDropSource::DoDragDrop like this:
+@li <b>Drag start</b>: 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 );
- @endcode
+ @code
+ wxDropSource dragSource( this );
+ dragSource.SetData( my_data );
+ wxDragResult result = dragSource.DoDragDrop( true );
+ @endcode
- @li @b Dragging: The call to DoDragDrop() blocks the program until the user releases
- the mouse button (unless you override the wxDropSource::GiveFeedback function to
- do something special). When the mouse moves in a window of a program which understands
- the same drag-and-drop protocol (any program under Windows or any program supporting
- the XDnD protocol under X Windows), the corresponding wxDropTarget methods
- are called - see below.
+@li @b Dragging: The call to DoDragDrop() blocks the program until the user releases
+ the mouse button (unless you override the wxDropSource::GiveFeedback function to
+ do something special). When the mouse moves in a window of a program which understands
+ the same drag-and-drop protocol (any program under Windows or any program supporting
+ the XDnD protocol under X Windows), the corresponding wxDropTarget methods
+ are called - see below.
- @li <b>Processing the result</b>: DoDragDrop() returns an @e effect code which
- is one of the values of @c wxDragResult enum (explained in wxDropTarget page):
+@li <b>Processing the result</b>: DoDragDrop() returns an @e effect code which
+ is one of the values of @c wxDragResult enum (explained in wxDropTarget page):
- @code
- switch (result)
- {
+ @code
+ switch (result)
+ {
case wxDragCopy:
// copy 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:
-
- @li @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.
-
- @li @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 wxDropTarget::OnData will get called and the wxDataObject belonging
- to the drop target can get filled with data.
-
- @li <b>The end</b>: 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.
+ }
+ @endcode
+
+
+To be a @e drop target, i.e. to receive the data dropped by the user you should
+follow the instructions below:
+
+@li @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.
+
+@li @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 wxDropTarget::OnData will get called and the wxDataObject belonging
+ to the drop target can get filled with data.
+
+@li <b>The end</b>: 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 overview_eventhandling Event Handling
-
- Classes: wxEvtHandler, wxWindow, wxEvent
-
- @li @ref overview_eventhandling_introduction
- @li @ref overview_eventhandling_processing
- @li @ref overview_eventhandling_prog
- @li @ref overview_eventhandling_pluggable
- @li @ref overview_eventhandling_winid
- @li @ref overview_eventhandling_custom
- @li @ref overview_eventhandling_macros
-
-
- <hr>
-
-
- @section overview_eventhandling_introduction 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.
-
- From wxWidgets 2.0, @e event tables are used instead, with a few exceptions.
- An event table is placed in an implementation file to tell wxWidgets how to map
- events to member functions. These member functions are not virtual functions, but
- 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_MENU(DO_TEST, MyFrame::DoTest)
- EVT_SIZE(MyFrame::OnSize)
- 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.
-
- The EVT_BUTTON macro demonstrates that the originating event does not have to
- come from the window class implementing the event table -- if the event source
- is a button within a panel within a frame, this will still work, because event
- tables are searched up through the hierarchy of windows for the command events.
- In this case, the button's event table will be searched, then the parent
- panel's, then the frame's.
-
- As mentioned before, the member functions that handle events do not have to be
- virtual. Indeed, the member functions should not be virtual as the event
- 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,
- wxSizeEvent is used. For menu commands and most 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 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
- {
- public:
- ...
- 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
- quite unexpected if there is anything following it.
-
- Finally, if you don't like using macros for static initialization of the event
- tables you may also use wxEvtHandler::Connect to
- connect the events to the handlers dynamically, during run-time. See the
- @ref page_utils_samples_event for an example of doing it.
-
-
-
- @section overview_eventhandling_processing How events are processed
-
- 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
- very close to virtual methods in normal C++, i.e. it is possible to alter
- the behaviour of a class by overriding its event handling functions. In
- many cases this works even for changing the behaviour of native controls.
-
- For example it is possible to filter out a number of key events sent by the
- system to a native text control by overriding wxTextCtrl and defining a
- handler for key events using EVT_KEY_DOWN. This would indeed prevent
- any key events from being sent to the native control - which might not be
- what is desired. In this case the event handler function has to call Skip()
- so as to indicate that the search for the event handler should continue.
-
- To summarize, instead of explicitly calling the base class version as you
- would have done with C++ virtual functions (i.e. @e wxTextCtrl::OnChar()),
- you should instead call wxEvent::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)
- {
- if ( isalpha( event.KeyCode() ) )
- {
+@page overview_eventhandling Event Handling
+
+Classes: wxEvtHandler, wxWindow, wxEvent
+
+@li @ref overview_eventhandling_introduction
+@li @ref overview_eventhandling_processing
+@li @ref overview_eventhandling_prog
+@li @ref overview_eventhandling_pluggable
+@li @ref overview_eventhandling_winid
+@li @ref overview_eventhandling_custom
+@li @ref overview_eventhandling_macros
+
+
+<hr>
+
+
+@section overview_eventhandling_introduction 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.
+
+From wxWidgets 2.0, @e event tables are used instead, with a few exceptions.
+An event table is placed in an implementation file to tell wxWidgets how to map
+events to member functions. These member functions are not virtual functions, but
+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_MENU(DO_TEST, MyFrame::DoTest)
+EVT_SIZE(MyFrame::OnSize)
+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.
+
+The EVT_BUTTON macro demonstrates that the originating event does not have to
+come from the window class implementing the event table -- if the event source
+is a button within a panel within a frame, this will still work, because event
+tables are searched up through the hierarchy of windows for the command events.
+In this case, the button's event table will be searched, then the parent
+panel's, then the frame's.
+
+As mentioned before, the member functions that handle events do not have to be
+virtual. Indeed, the member functions should not be virtual as the event
+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,
+wxSizeEvent is used. For menu commands and most 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 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
+{
+public:
+...
+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
+quite unexpected if there is anything following it.
+
+Finally, if you don't like using macros for static initialization of the event
+tables you may also use wxEvtHandler::Connect to
+connect the events to the handlers dynamically, during run-time. See the
+@ref page_samples_event for an example of doing it.
+
+
+
+@section overview_eventhandling_processing How events are processed
+
+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
+very close to virtual methods in normal C++, i.e. it is possible to alter
+the behaviour of a class by overriding its event handling functions. In
+many cases this works even for changing the behaviour of native controls.
+
+For example it is possible to filter out a number of key events sent by the
+system to a native text control by overriding wxTextCtrl and defining a
+handler for key events using EVT_KEY_DOWN. This would indeed prevent
+any key events from being sent to the native control - which might not be
+what is desired. In this case the event handler function has to call Skip()
+so as to indicate that the search for the event handler should continue.
+
+To summarize, instead of explicitly calling the base class version as you
+would have done with C++ virtual functions (i.e. @e wxTextCtrl::OnChar()),
+you should instead call wxEvent::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)
+{
+ if ( isalpha( event.KeyCode() ) )
+ {
// 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
- {
+ }
+ 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:
-
- @li If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
- the function skips to step (6).
- @li If the object is a wxWindow, @b ProcessEvent is recursively called on the window's
- wxValidator. If this returns @true, the function exits.
- @li @b SearchEventTable is called for this event handler. If this fails, the base
- class table is tried, and so on until no more tables exist or an appropriate
- function was found, in which case the function exits.
- @li The search is applied down the entire chain of event handlers (usually the chain has
- a length of one). If this succeeds, the function exits.
- @li If the object is a wxWindow and the event is set to set to propagate (in the library only
- 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.
- @li Finally, @b ProcessEvent is called on the wxApp object.
-
- <b>Pay close attention to Step 5</b>. 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
- (see wxEvent::ShouldPropagate)
- (most likely derived either directly or indirectly from wxCommandEvent)
- 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 @c event.Skip().
-
- Finally, there is another additional complication (which, in fact, simplifies
- life of wxWidgets programmers significantly): when propagating the command
- events upwards to the parent window, the event propagation stops when it
- reaches the parent dialog, if any. This means that you don't risk to get
- unexpected events from the dialog controls (which might be left unprocessed by
- the dialog itself because it doesn't care about them) when a modal dialog is
- popped up. The events do propagate beyond the frames, however. The rationale
- for this choice is that there are only a few frames in a typical application
- and their parent-child relation are well understood by the programmer while it
- 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 wxWindow::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,
- paint, mouse, keyboard, etc.) are sent only to the window. Events
- that have a higher level of meaning and/or are generated by the window
- itself, (button click, menu select, tree expand, etc.) are command
- events and are sent up to the parent to see if it is interested in the event.
-
- 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,
- 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:
-
- @li wxEvent: The event base class
- @li wxActivateEvent: A window or application activation event
- @li wxCloseEvent: A close window or end session event
- @li wxEraseEvent: An erase background event
- @li wxFocusEvent: A window focus event
- @li wxKeyEvent: A keypress event
- @li wxIdleEvent: An idle event
- @li wxInitDialogEvent: A dialog initialisation event
- @li wxJoystickEvent: A joystick event
- @li wxMenuEvent: A menu event
- @li wxMouseEvent: A mouse event
- @li wxMoveEvent: A move event
- @li wxPaintEvent: A paint event
- @li wxQueryLayoutInfoEvent: Used to query layout information
- @li wxSetCursorEvent: Used for special cursor processing based on current mouse position
- @li wxSizeEvent: A size event
- @li wxScrollWinEvent: A scroll event sent by a scrolled window (not a scroll bar)
- @li 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 overview_eventhandling_prog 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:
-
- @li wxNotebook::AddPage: No event-free alternatives
- @li wxNotebook::AdvanceSelection: No event-free alternatives
- @li wxNotebook::DeletePage: No event-free alternatives
- @li wxNotebook::SetSelection: Use wxNotebook::ChangeSelection instead, as
- wxNotebook::SetSelection is deprecated
- @li wxTreeCtrl::Delete: No event-free alternatives
- @li wxTreeCtrl::DeleteAllItems: No event-free alternatives
- @li wxTreeCtrl::EditLabel: No event-free alternatives
- @li All wxTextCtrl methods
-
- wxTextCtrl::ChangeValue can be used instead of wxTextCtrl::SetValue but the other
- functions, such as wxTextCtrl::Replace or wxTextCtrl::WriteText don't have event-free
- equivalents.
-
-
-
- @section overview_eventhandling_pluggable 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 wxWindow::SetEventHandler
- (or, preferably, wxWindow::PushEventHandler) to make this
- event handler the object that responds to events. This way, you can avoid
- a lot of class derivation, and use instances of the same event handler class (but different
- objects as the same event handler object shouldn't be used more than once) to
- handle events from instances of different widget classes.
-
- If you ever have to call a window's event handler
- manually, use the GetEventHandler function to retrieve the window's event handler and use that
- to call the member function. By default, GetEventHandler returns a pointer to the window itself
- unless an application has redirected event handling using SetEventHandler or PushEventHandler.
-
- One use of PushEventHandler is to temporarily or permanently change the
- behaviour of the GUI. For example, you might want to invoke a dialog editor
- in your application that changes aspects of dialog boxes. You can
- grab all the input for an existing dialog box, and edit it 'in situ',
- before restoring its behaviour to normal. So even if the application
- has derived new classes to customize behaviour, your utility can indulge
- in a spot of body-snatching. It could be a useful technique for on-line
- tutorials, too, where you take a user through a serious of steps and
- don't want them to diverge from the lesson. Here, you can examine the events
- coming from buttons and windows, and if acceptable, pass them through to
- 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 overview_eventhandling_winid 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
- across your entire application just so long as they are unique within a
- particular context you're interested in, such as a frame and its children. You
- may use the @c wxID_OK identifier, for example, on any number of dialogs so
- long as you don't have several within the same dialog.
-
- If you pass @c wxID_ANY to a window constructor, an identifier will be
- 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
- 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
- positive.
-
- See @ref page_stdevtid for the list of standard identifiers availabel.
- 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.
- Finally, you can allocate identifiers dynamically using wxNewId() function to.
- If you use wxNewId() consistently in your application, you can be sure that
- the your identifiers don't conflict accidentally.
-
-
- @section overview_eventhandling_custom Custom event summary
-
- @subsection overview_eventhandling_custom_general 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
- new event types to the library or application without risking ID clashes
- (two different event types mistakingly getting the same event ID). This
- 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.
-
- 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.
- See also the @ref page_utils_samples_event for an example of code
- defining and working with the custom event types.
-
-
- @subsection overview_eventhandling_custom_existing Using existing event classes
-
- If you just want to use a wxCommandEvent with
- a new event type, you can then use one of the generic event table macros
- listed below, without having to define a new macro yourself. This also
- 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();
- }
+ }
+}
+@endcode
+
+The normal order of event table searching by ProcessEvent is as follows:
+
+@li If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
+ the function skips to step (6).
+@li If the object is a wxWindow, @b ProcessEvent is recursively called on the window's
+ wxValidator. If this returns @true, the function exits.
+@li @b SearchEventTable is called for this event handler. If this fails, the base
+ class table is tried, and so on until no more tables exist or an appropriate
+ function was found, in which case the function exits.
+@li The search is applied down the entire chain of event handlers (usually the chain has
+ a length of one). If this succeeds, the function exits.
+@li If the object is a wxWindow and the event is set to set to propagate (in the library only
+ 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.
+@li Finally, @b ProcessEvent is called on the wxApp object.
+
+<b>Pay close attention to Step 5</b>. 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
+(see wxEvent::ShouldPropagate)
+(most likely derived either directly or indirectly from wxCommandEvent)
+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 @c event.Skip().
+
+Finally, there is another additional complication (which, in fact, simplifies
+life of wxWidgets programmers significantly): when propagating the command
+events upwards to the parent window, the event propagation stops when it
+reaches the parent dialog, if any. This means that you don't risk to get
+unexpected events from the dialog controls (which might be left unprocessed by
+the dialog itself because it doesn't care about them) when a modal dialog is
+popped up. The events do propagate beyond the frames, however. The rationale
+for this choice is that there are only a few frames in a typical application
+and their parent-child relation are well understood by the programmer while it
+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 wxWindow::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,
+paint, mouse, keyboard, etc.) are sent only to the window. Events
+that have a higher level of meaning and/or are generated by the window
+itself, (button click, menu select, tree expand, etc.) are command
+events and are sent up to the parent to see if it is interested in the event.
+
+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,
+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:
+
+@li wxEvent: The event base class
+@li wxActivateEvent: A window or application activation event
+@li wxCloseEvent: A close window or end session event
+@li wxEraseEvent: An erase background event
+@li wxFocusEvent: A window focus event
+@li wxKeyEvent: A keypress event
+@li wxIdleEvent: An idle event
+@li wxInitDialogEvent: A dialog initialisation event
+@li wxJoystickEvent: A joystick event
+@li wxMenuEvent: A menu event
+@li wxMouseEvent: A mouse event
+@li wxMoveEvent: A move event
+@li wxPaintEvent: A paint event
+@li wxQueryLayoutInfoEvent: Used to query layout information
+@li wxSetCursorEvent: Used for special cursor processing based on current mouse position
+@li wxSizeEvent: A size event
+@li wxScrollWinEvent: A scroll event sent by a scrolled window (not a scroll bar)
+@li 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 overview_eventhandling_prog 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:
+
+@li wxNotebook::AddPage: No event-free alternatives
+@li wxNotebook::AdvanceSelection: No event-free alternatives
+@li wxNotebook::DeletePage: No event-free alternatives
+@li wxNotebook::SetSelection: Use wxNotebook::ChangeSelection instead, as
+ wxNotebook::SetSelection is deprecated
+@li wxTreeCtrl::Delete: No event-free alternatives
+@li wxTreeCtrl::DeleteAllItems: No event-free alternatives
+@li wxTreeCtrl::EditLabel: No event-free alternatives
+@li All wxTextCtrl methods
+
+wxTextCtrl::ChangeValue can be used instead of wxTextCtrl::SetValue but the other
+functions, such as wxTextCtrl::Replace or wxTextCtrl::WriteText don't have event-free
+equivalents.
+
+
+
+@section overview_eventhandling_pluggable 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 wxWindow::SetEventHandler
+(or, preferably, wxWindow::PushEventHandler) to make this
+event handler the object that responds to events. This way, you can avoid
+a lot of class derivation, and use instances of the same event handler class (but different
+objects as the same event handler object shouldn't be used more than once) to
+handle events from instances of different widget classes.
+
+If you ever have to call a window's event handler
+manually, use the GetEventHandler function to retrieve the window's event handler and use that
+to call the member function. By default, GetEventHandler returns a pointer to the window itself
+unless an application has redirected event handling using SetEventHandler or PushEventHandler.
+
+One use of PushEventHandler is to temporarily or permanently change the
+behaviour of the GUI. For example, you might want to invoke a dialog editor
+in your application that changes aspects of dialog boxes. You can
+grab all the input for an existing dialog box, and edit it 'in situ',
+before restoring its behaviour to normal. So even if the application
+has derived new classes to customize behaviour, your utility can indulge
+in a spot of body-snatching. It could be a useful technique for on-line
+tutorials, too, where you take a user through a serious of steps and
+don't want them to diverge from the lesson. Here, you can examine the events
+coming from buttons and windows, and if acceptable, pass them through to
+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 overview_eventhandling_winid 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
+across your entire application just so long as they are unique within a
+particular context you're interested in, such as a frame and its children. You
+may use the @c wxID_OK identifier, for example, on any number of dialogs so
+long as you don't have several within the same dialog.
+
+If you pass @c wxID_ANY to a window constructor, an identifier will be
+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
+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
+positive.
+
+See @ref page_stdevtid for the list of standard identifiers availabel.
+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.
+Finally, you can allocate identifiers dynamically using wxNewId() function to.
+If you use wxNewId() consistently in your application, you can be sure that
+the your identifiers don't conflict accidentally.
+
+
+@section overview_eventhandling_custom Custom event summary
+
+@subsection overview_eventhandling_custom_general 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
+new event types to the library or application without risking ID clashes
+(two different event types mistakingly getting the same event ID). This
+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.
+
+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.
+See also the @ref page_samples_event for an example of code
+defining and working with the custom event types.
+
+
+@subsection overview_eventhandling_custom_existing Using existing event classes
+
+If you just want to use a wxCommandEvent with
+a new event type, you can then use one of the generic event table macros
+listed below, without having to define a new macro yourself. This also
+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
+// user code sending the event
- void MyWindow::SendEvent()
- {
- wxCommandEvent event( wxEVT_MY_EVENT, GetId() );
- event.SetEventObject( this );
- // Give it some contents
- event.SetText( wxT("Hallo") );
- // Send it
- GetEventHandler()->ProcessEvent( event );
- }
- @endcode
+void MyWindow::SendEvent()
+{
+ wxCommandEvent event( wxEVT_MY_EVENT, GetId() );
+ event.SetEventObject( this );
+ // Give it some contents
+ event.SetText( wxT("Hallo") );
+ // Send it
+ GetEventHandler()->ProcessEvent( event );
+}
+@endcode
- @subsection overview_eventhandling_custom_generic Generic event table macros
+@subsection overview_eventhandling_custom_generic Generic event table macros
- @beginTable
- @row2col{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.}
- @row2col{EVT_CUSTOM_RANGE(event\, id1\, id2\, func),
- The same as EVT_CUSTOM, but responds to a range of window identifiers.}
- @row2col{EVT_COMMAND(id\, event\, func),
- The same as EVT_CUSTOM, but expects a member function with a
- wxCommandEvent argument.}
- @row2col{EVT_COMMAND_RANGE(id1\, id2\, event\, func),
- The same as EVT_CUSTOM_RANGE, but
- expects a member function with a wxCommandEvent argument.}
- @row2col{EVT_NOTIFY(event\, id\, func),
- The same as EVT_CUSTOM, but
- expects a member function with a wxNotifyEvent argument.}
- @row2col{EVT_NOTIFY_RANGE(event\, id1\, id2\, func),
- The same as EVT_CUSTOM_RANGE, but
- expects a member function with a wxNotifyEvent argument.}
- @endTable
+@beginTable
+@row2col{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.}
+@row2col{EVT_CUSTOM_RANGE(event\, id1\, id2\, func),
+ The same as EVT_CUSTOM, but responds to a range of window identifiers.}
+@row2col{EVT_COMMAND(id\, event\, func),
+ The same as EVT_CUSTOM, but expects a member function with a
+ wxCommandEvent argument.}
+@row2col{EVT_COMMAND_RANGE(id1\, id2\, event\, func),
+ The same as EVT_CUSTOM_RANGE, but
+ expects a member function with a wxCommandEvent argument.}
+@row2col{EVT_NOTIFY(event\, id\, func),
+ The same as EVT_CUSTOM, but
+ expects a member function with a wxNotifyEvent argument.}
+@row2col{EVT_NOTIFY_RANGE(event\, id1\, id2\, func),
+ The same as EVT_CUSTOM_RANGE, but
+ expects a member function with a wxNotifyEvent argument.}
+@endTable
- @subsection overview_eventhandling_custom_ownclass Defining your own event class
+@subsection overview_eventhandling_custom_ownclass 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:
+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
+@code
+// code defining event
- class wxPlotEvent: public wxNotifyEvent
- {
- public:
- wxPlotEvent( wxEventType commandType = wxEVT_NULL, int id = 0 );
+class wxPlotEvent: public wxNotifyEvent
+{
+public:
+ wxPlotEvent( wxEventType commandType = wxEVT_NULL, int id = 0 );
- // accessors
- wxPlotCurve *GetCurve()
- { return m_curve; }
+ // accessors
+ wxPlotCurve *GetCurve()
+ { return m_curve; }
- // required for sending with wxPostEvent()
- virtual wxEvent *Clone() const;
+ // required for sending with wxPostEvent()
+ virtual wxEvent *Clone() const;
- private:
- wxPlotCurve *m_curve;
- };
+private:
+ wxPlotCurve *m_curve;
+};
- DECLARE_EVENT_TYPE( wxEVT_PLOT_ACTION, -1 )
+DECLARE_EVENT_TYPE( wxEVT_PLOT_ACTION, -1 )
- typedef void (wxEvtHandler::*wxPlotEventFunction)(wxPlotEvent&);
+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 ),
+#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
+// code implementing the event type and the event class
- DEFINE_EVENT_TYPE( wxEVT_PLOT_ACTION )
+DEFINE_EVENT_TYPE( wxEVT_PLOT_ACTION )
- wxPlotEvent::wxPlotEvent( ...
+wxPlotEvent::wxPlotEvent( ...
- // user code intercepting the event
+// user code intercepting the event
- BEGIN_EVENT_TABLE(MyFrame, wxFrame)
- EVT_PLOT (ID_MY_WINDOW, MyFrame::OnPlot)
- END_EVENT_TABLE()
+BEGIN_EVENT_TABLE(MyFrame, wxFrame)
+EVT_PLOT (ID_MY_WINDOW, MyFrame::OnPlot)
+END_EVENT_TABLE()
- void MyFrame::OnPlot( wxPlotEvent &event )
- {
- wxPlotCurve *curve = event.GetCurve();
- }
+void MyFrame::OnPlot( wxPlotEvent &event )
+{
+ wxPlotCurve *curve = event.GetCurve();
+}
- // user code sending the event
+// user code sending the event
- void MyWindow::SendEvent()
- {
- wxPlotEvent event( wxEVT_PLOT_ACTION, GetId() );
- event.SetEventObject( this );
- event.SetCurve( m_curve );
- GetEventHandler()->ProcessEvent( event );
- }
- @endcode
+void MyWindow::SendEvent()
+{
+ wxPlotEvent event( wxEVT_PLOT_ACTION, GetId() );
+ event.SetEventObject( this );
+ event.SetCurve( m_curve );
+ GetEventHandler()->ProcessEvent( event );
+}
+@endcode
- @section overview_eventhandling_macros Event macros summary
+@section overview_eventhandling_macros Event macros summary
- For the full list of event classes, please see the
- @ref page_class_cat_events page.
+For the full list of event classes, please see the
+@ref page_class_cat_events page.
*/
/**
- @page overview_fontencoding Font Encodings
+@page overview_fontencoding Font Encodings
- wxWidgets has support for multiple font encodings.
+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 Unicode
- (see @ref overview_unicode).
+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 Unicode
+(see @ref overview_unicode).
- 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):
+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):
- @beginDefList
- @itemdef{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).}
- @itemdef{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).}
- @itemdef{wxFONTENCODING_ISO8859_1..15,
- ISO8859 family encodings which are
- usually used by all non-Microsoft operating systems.}
- @itemdef{wxFONTENCODING_KOI8,
- Standard Cyrillic encoding for the Internet
- (but see also wxFONTENCODING_ISO8859_5 and wxFONTENCODING_CP1251).}
- @itemdef{wxFONTENCODING_CP1250, Microsoft analogue of ISO8859-2}
- @itemdef{wxFONTENCODING_CP1251, Microsoft analogue of ISO8859-5}
- @itemdef{wxFONTENCODING_CP1252, Microsoft analogue of ISO8859-1}
- @endDefList
+@beginDefList
+@itemdef{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).}
+@itemdef{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).}
+@itemdef{wxFONTENCODING_ISO8859_1..15,
+ ISO8859 family encodings which are
+ usually used by all non-Microsoft operating systems.}
+@itemdef{wxFONTENCODING_KOI8,
+ Standard Cyrillic encoding for the Internet
+ (but see also wxFONTENCODING_ISO8859_5 and wxFONTENCODING_CP1251).}
+@itemdef{wxFONTENCODING_CP1250, Microsoft analogue of ISO8859-2}
+@itemdef{wxFONTENCODING_CP1251, Microsoft analogue of ISO8859-5}
+@itemdef{wxFONTENCODING_CP1252, Microsoft analogue of ISO8859-1}
+@endDefList
- 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
- versions of Windows) and there are more of them for other encodings.
+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
+versions of Windows) and there are more of them for other encodings.
- The situation is particularly complicated with Cyrillic encodings for which
- (more than) three incompatible encodings exist: KOI8 (the old standard, widely
- used on the Internet), ISO8859-5 (ISO standard for Cyrillic) and CP1251
- (WinCyrillic).
+The situation is particularly complicated with Cyrillic encodings for which
+(more than) three incompatible encodings exist: KOI8 (the old standard, widely
+used on the Internet), ISO8859-5 (ISO standard for Cyrillic) and CP1251
+(WinCyrillic).
- This abundance of (incompatible) encodings should make it clear that using
- encodings is less easy than it might seem. The problems arise both from the
- fact that the standard encodings for the given language (say Russian, which is
- 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).
+This abundance of (incompatible) encodings should make it clear that using
+encodings is less easy than it might seem. The problems arise both from the
+fact that the standard encodings for the given language (say Russian, which is
+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
- 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
- wxFontEnumerator will never return one, even if the user has installed a KOI8
- font on his system.
+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
+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.
+To solve this problem, a wxFontMapper class is provided.
- This class stores the mapping between the encodings and the font face
- names which support them in wxConfig object. Of
- course, it would be fairly useless if it tried to determine these mappings by
- itself, so, instead, it (optionally) asks the user and remembers his answers
- so that the next time the program will automatically choose the correct font.
- All these topics are illustrated by the @ref page_utils_samples_font;
- please refer to it and the documentation of the classes mentioned here for
- further explanations.
+This class stores the mapping between the encodings and the font face
+names which support them in wxConfig object. Of
+course, it would be fairly useless if it tried to determine these mappings by
+itself, so, instead, it (optionally) asks the user and remembers his answers
+so that the next time the program will automatically choose the correct font.
+All these topics are illustrated by the @ref page_samples_font;
+please refer to it and the documentation of the classes mentioned here for
+further explanations.
*/
@see
@li The gettext Manual: http://www.gnu.org/software/gettext/manual/gettext.html
@li @ref overview_nonenglish - It focuses on handling charsets related problems.
-@li @ref page_utils_samples_internat - Shows you how all this looks in practice.
+@li @ref page_samples_internat - Shows you how all this looks in practice.
*/
projects / wxWidgets.git / commitdiff
