From dc28cdf8d4d895e953d1710bbf77a065106ff98f Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Sat, 22 Mar 2008 17:42:29 +0000 Subject: [PATCH 1/1] moved the samples in a separate page so it has a summary of all the samples descriptions and so writing references to samples is shorter (@ref page_samples_xxx instead of @ref page_utils_samples_xxx) git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52705 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/mainpages/manual.h | 1 + docs/doxygen/mainpages/samples.h | 602 ++++++++++++ docs/doxygen/mainpages/utilities.h | 616 +------------ docs/doxygen/overviews/bookctrl.h | 2 +- docs/doxygen/overviews/dataobject.h | 104 +-- docs/doxygen/overviews/dnd.h | 122 +-- docs/doxygen/overviews/eventhandling.h | 872 +++++++++--------- docs/doxygen/overviews/fontencoding.h | 130 +-- docs/doxygen/overviews/internationalization.h | 2 +- 9 files changed, 1269 insertions(+), 1182 deletions(-) create mode 100644 docs/doxygen/mainpages/samples.h diff --git a/docs/doxygen/mainpages/manual.h b/docs/doxygen/mainpages/manual.h index 631b1d8483..4a627fb1c3 100644 --- a/docs/doxygen/mainpages/manual.h +++ b/docs/doxygen/mainpages/manual.h @@ -20,6 +20,7 @@ @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 diff --git a/docs/doxygen/mainpages/samples.h b/docs/doxygen/mainpages/samples.h new file mode 100644 index 0000000000..f442ed7d52 --- /dev/null +++ b/docs/doxygen/mainpages/samples.h @@ -0,0 +1,602 @@ +///////////////////////////////////////////////////////////////////////////// +// 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 + +@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 + +@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 + +@endTable + + +
+ + + +@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) + +*/ diff --git a/docs/doxygen/mainpages/utilities.h b/docs/doxygen/mainpages/utilities.h index 9573329d36..cd8bab34b9 100644 --- a/docs/doxygen/mainpages/utilities.h +++ b/docs/doxygen/mainpages/utilities.h @@ -8,602 +8,86 @@ /** - @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/ . -
+@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 +
- 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 + - 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) */ diff --git a/docs/doxygen/overviews/bookctrl.h b/docs/doxygen/overviews/bookctrl.h index ff76a6759e..4eb6f2b549 100644 --- a/docs/doxygen/overviews/bookctrl.h +++ b/docs/doxygen/overviews/bookctrl.h @@ -38,7 +38,7 @@ displayed one page at a time. wxWidgets has five variants of this control: @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 diff --git a/docs/doxygen/overviews/dataobject.h b/docs/doxygen/overviews/dataobject.h index 18d5d71803..43a2e15ee1 100644 --- a/docs/doxygen/overviews/dataobject.h +++ b/docs/doxygen/overviews/dataobject.h @@ -8,75 +8,75 @@ /** - @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 -
+
- @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. */ diff --git a/docs/doxygen/overviews/dnd.h b/docs/doxygen/overviews/dnd.h index ee725cd088..db4bb131e9 100644 --- a/docs/doxygen/overviews/dnd.h +++ b/docs/doxygen/overviews/dnd.h @@ -8,54 +8,54 @@ /** - @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 Drag start: To start the dragging process (typically in response to a - mouse click) you must call wxDropSource::DoDragDrop like this: +@li Drag start: To start the dragging process (typically in response to a + mouse click) you must call wxDropSource::DoDragDrop like this: - @code - wxDropSource dragSource( this ); - dragSource.SetData( my_data ); - wxDragResult result = dragSource.DoDragDrop( true ); - @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 Processing the result: DoDragDrop() returns an @e effect code which - is one of the values of @c wxDragResult enum (explained in wxDropTarget page): +@li Processing the result: 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; @@ -65,31 +65,31 @@ 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 The end: After processing the data, DoDragDrop() returns either - wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift - and Alt at the moment of the drop. There is currently no way for the drop - target to change this return code. + } + @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 The end: After processing the data, DoDragDrop() returns either + wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift + and Alt at the moment of the drop. There is currently no way for the drop + target to change this return code. */ diff --git a/docs/doxygen/overviews/eventhandling.h b/docs/doxygen/overviews/eventhandling.h index 68c2aa5f45..e504d6e5d1 100644 --- a/docs/doxygen/overviews/eventhandling.h +++ b/docs/doxygen/overviews/eventhandling.h @@ -8,484 +8,484 @@ /** - @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 - - -
- - - @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 + + +
+ + +@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. - - Pay close attention to Step 5. People often overlook or get - confused by this powerful feature of the wxWidgets event processing - system. To put it a different way, events set to propagate - (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. + +Pay close attention to Step 5. People often overlook or get +confused by this powerful feature of the wxWidgets event processing +system. To put it a different way, events set to propagate +(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. */ diff --git a/docs/doxygen/overviews/fontencoding.h b/docs/doxygen/overviews/fontencoding.h index a500775131..f84c5f3204 100644 --- a/docs/doxygen/overviews/fontencoding.h +++ b/docs/doxygen/overviews/fontencoding.h @@ -8,81 +8,81 @@ /** - @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. */ diff --git a/docs/doxygen/overviews/internationalization.h b/docs/doxygen/overviews/internationalization.h index c952bb7dc6..973396a87d 100644 --- a/docs/doxygen/overviews/internationalization.h +++ b/docs/doxygen/overviews/internationalization.h @@ -84,7 +84,7 @@ translated special key names such as Backspace, End, Insert, etc. @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. */ -- 2.45.2