wxMessageBox off the main thread lost result code.

[wxWidgets.git] / docs / doxygen / mainpages / samples.h

diff --git a/docs/doxygen/mainpages/samples.h b/docs/doxygen/mainpages/samples.h
index 7334903ff70258db4ac465152f76071cb0dac329..e5c56758f92d4d7f616ce7cb194f6100587c8005 100644 (file)
--- a/docs/doxygen/mainpages/samples.h
+++ b/docs/doxygen/mainpages/samples.h
@@ -2,13 +2,14 @@
 // Name:        samples.h
 // Purpose:     Samples page of the Doxygen manual
 // Author:      wxWidgets team
 // 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
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 
 /////////////////////////////////////////////////////////////////////////////
 
 /**
 

-@page page_samples Included Samples
+@page page_samples Samples Overview
+
+@tableofcontents

 
 Probably the best way to learn wxWidgets is by reading the source of some 80+
 samples provided with it. Many aspects of wxWidgets programming can be learnt
 
 Probably the best way to learn wxWidgets is by reading the source of some 80+
 samples provided with it. Many aspects of wxWidgets programming can be learnt


@@ -18,16 +19,17 @@ 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.
 
 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 80 different samples as part of wxWidgets:
-the list in this page is not complete!
-You should start your tour of wxWidgets with the @ref page_samples_minimal
-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.
+There are currently more than 80 different samples as part of wxWidgets: the
+list in this page is not complete! You should start your tour of wxWidgets with
+the @ref page_samples_minimal 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 @ref page_samples_widgets and
-@ref page_samples_controls which show many of wxWidgets native and
-generic controls, such as buttons, listboxes, checkboxes, comboboxes etc.
+The next most useful sample is @ref page_samples_widgets which shows many of
+wxWidgets controls, such as buttons, text entry zones, list boxes, check boxes,
+combo boxes etc. It is organized in many different source files, one per each
+control, which makes it easier to study it, and also allows to change various
+control styles and call its methods interactively.

 
 Other, more complicated controls, have their own samples. In this category you
 may find the following samples showing the corresponding controls:
 
 Other, more complicated controls, have their own samples. In this category you
 may find the following samples showing the corresponding controls:


@@ -36,112 +38,26 @@ may find the following samples showing the corresponding controls:
 @li wxListCtrl: @ref page_samples_listctrl
 @li wxTreeCtrl: @ref page_samples_treectrl
 @li wxGrid: @ref page_samples_grid
 @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.
-
-<!--
-The following sample list is generated by executing command
-
-ls | egrep '[a-z]+' | egrep '^[a-z]+$' | sed 's/^/@li @sample\{/' | sed 's/$/\}/'
-
-in wxWidgets/samples
-
-TODO: Organize them in a more human-readable way.
--->
-
-@beginInvisibleTable
-<tr><td>
-@li @sample{access}
-@li @sample{animate}
-@li @sample{artprov}
-@li @sample{aui}
-@li @sample{calendar}
-@li @sample{caret}
-@li @sample{collpane}
-@li @sample{combo}
-@li @sample{config}
-@li @sample{console}
-@li @sample{controls}
-@li @sample{dataview}
-@li @sample{debugrpt}
-@li @sample{dialogs}
-@li @sample{dialup}
-@li @sample{display}
-@li @sample{dnd}
-@li @sample{docview}
-@li @sample{docvwmdi}
-@li @sample{dragimag}
-@li @sample{drawing}
-@li @sample{editlbox}
-@li @sample{erase}
-@li @sample{event}
-@li @sample{except}
-@li @sample{exec}
-@li @sample{font}
-</td><td>
-@li @sample{grid}
-@li @sample{help}
-@li @sample{htlbox}
-@li @sample{html}
-@li @sample{image}
-@li @sample{internat}
-@li @sample{ipc}
-@li @sample{joytest}
-@li @sample{keyboard}
-@li @sample{layout}
-@li @sample{listctrl}
-@li @sample{mdi}
-@li @sample{mediaplayer}
-@li @sample{memcheck}
-@li @sample{menu}
-@li @sample{mfc}
-@li @sample{minimal}
-@li @sample{mobile}
-@li @sample{nativdlg}
-@li @sample{notebook}
-@li @sample{oleauto}
-@li @sample{opengl}
-@li @sample{ownerdrw}
-@li @sample{popup}
-@li @sample{power}
-@li @sample{printing}
-@li @sample{propgrid}
-</td><td>
-@li @sample{regtest}
-@li @sample{render}
-@li @sample{richtext}
-@li @sample{sashtest}
-@li @sample{scroll}
-@li @sample{scrollsub}
-@li @sample{shaped}
-@li @sample{sockets}
-@li @sample{sound}
-@li @sample{splash}
-@li @sample{splitter}
-@li @sample{statbar}
-@li @sample{stc}
-@li @sample{svg}
-@li @sample{taborder}
-@li @sample{taskbar}
-@li @sample{text}
-@li @sample{thread}
-@li @sample{toolbar}
-@li @sample{treectrl}
-@li @sample{typetest}
-@li @sample{validate}
-@li @sample{vscroll}
-@li @sample{widgets}
-@li @sample{wizard}
-@li @sample{wrapsizer}
-@li @sample{xrc}
-</td></tr>
-@endTable
+@li wxDataViewCtrl: @ref page_samples_dataview
+@li wxWebView: @ref page_samples_webview
+
+Notice that all wxWidgets samples mentioned above can be found in @c samples
+subdirectory of the library distribution. When a @c foobar sample is mentioned
+below, its sources can be found in @c samples/foobar directory of your
+wxWidgets tree. If you installed wxWidgets from a binary package, you might not
+have this directory. In this case, you may view the samples online at
+http://svn.wxwidgets.org/viewvc/wx/wxWidgets/trunk/samples/ but you need to
+download the source distribution in order to be able to build them (highly
+recommended).
+
+Final advice is to do a search in the entire samples 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.

 
 @todo Write descriptions for the samples who description started with
  "This sample demonstrates", they are semi-auto generated.
 
 @todo Write descriptions for the samples who description started with
  "This sample demonstrates", they are semi-auto generated.

-<hr>
+
+

 
 @section page_samples_access Accessibility Sample
 
 
 @section page_samples_access Accessibility Sample
 


@@ -254,6 +170,12 @@ The various controls tested are listed here:
 
 @sampledir{dataview}
 
 
 @sampledir{dataview}
 

+@section page_samples_clipboard Clipboard Sample
+
+@sampleabout{wxClipboard}
+
+@sampledir{clipboard}
+

 @section page_samples_debugrpt Debug Reporter Sample
 
 This sample shows how to use wxDebugReport class to
 @section page_samples_debugrpt Debug Reporter Sample
 
 This sample shows how to use wxDebugReport class to


@@ -277,6 +199,11 @@ wxDebugReportUpload will report an error.
 This sample shows how to use the common dialogs available from wxWidgets. These
 dialogs are described in detail in the @ref overview_cmndlg.
 
 This sample shows how to use the common dialogs available from wxWidgets. These
 dialogs are described in detail in the @ref overview_cmndlg.
 

+In addition to the dialogs accessible from the sample menus, you can also run
+it with a <code>--progress=style</code> command line option to show a
+wxProgressDialog with the given style (try 0 for the default style) on program
+startup, before the main window is shown.
+

 @sampledir{dialogs}
 
 @section page_samples_dialup Dialup Sample
 @sampledir{dialogs}
 
 @section page_samples_dialup Dialup Sample


@@ -346,15 +273,7 @@ wxDataObject to achieve this.
 
 @sampledir{docview}
 
 
 @sampledir{docview}
 

-@see @sample{docvwmdi}, @sample{mdi}
-
-@section page_samples_docvwmdi Document/View MDI Sample
-
-@sampleabout{@ref overview_docview in MDI}
-
-@see @sample{docview}, @sample{mdi}
-
-@sampledir{docvwmdi}
+@see @sample{mdi}

 
 @section page_samples_dragimag Drag Image Sample
 
 
 @section page_samples_dragimag Drag Image Sample
 


@@ -368,12 +287,6 @@ wxDataObject to achieve this.
 
 @sampledir{drawing}
 
 
 @sampledir{drawing}
 

-@section page_samples_editlbox Editable List Box Sample
-
-@sampleabout{wxEditableListBox}
-
-@sampledir{editlbox}
-

 @section page_samples_erase Erase Event Sample
 
 @sampleabout{wxEraseEvent}
 @section page_samples_erase Erase Event Sample
 
 @sampleabout{wxEraseEvent}


@@ -417,6 +330,23 @@ wxProcess::Exists().
 
 @sampledir{exec}
 
 
 @sampledir{exec}
 

+@section page_samples_flash Flash Sample
+
+The flash sample demonstrates embedding of Adobe Flash into a wxWidgets
+program. Currently it only works under Windows as it uses the Flash ActiveX
+control to achieve this but we hope to be able to extend it to also work under
+other platforms in the future. The sample also currently requires Microsoft
+Visual C++ compiler as it uses COM support extensions specific to this
+compiler.
+
+The sample comes with 2 Flash files (SWF), showing a simple Flash animation
+which can be controlled using the "Play", "Stop" and "Back"/"Forward" buttons
+in the sample as well as a Flash form which shows how Flash and wxWidgets
+program can exchange data: calling "GetText" function without arguments returns
+the text of the text control defined inside Flash and calling "SetText" with an
+argument sets the control contents to the given string. Finally clicking on the
+button generates an event which is caught by the C++ program.
+

 @section page_samples_font Font Sample
 
 The font sample demonstrates wxFont,
 @section page_samples_font Font Sample
 
 The font sample demonstrates wxFont,


@@ -506,10 +436,10 @@ 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
 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.
+changing the other aspects of the program's behaviour.

 
 More information about this sample can be found in the @c readme.txt file in
 
 More information about this sample can be found in the @c readme.txt file in

-its directory. Please also see the @ref overview_i18n.
+its directory. Please also see the @ref overview_i18n overview.

 
 @sampledir{internat}
 
 
 @sampledir{internat}
 


@@ -529,6 +459,12 @@ its directory. Please also see the @ref overview_i18n.
 
 @sampleabout{wxKeyEvent}
 
 
 @sampleabout{wxKeyEvent}
 

+This sample can be used to interactively test the events produced by pressing
+various keyboard keys. It also shows the interaction between accelerators and
+the normal keyboard events (which are overridden by any defined accelerators)
+and finally allows to test that not skipping an event in EVT_KEY_DOWN handler
+suppresses the subsequent EVT_CHAR event.
+

 @sampledir{keyboard}
 
 @section page_samples_layout Layout Sample
 @sampledir{keyboard}
 
 @section page_samples_layout Layout Sample


@@ -564,7 +500,7 @@ The sample also provides some timings for adding/deleting/sorting a lot of
 
 @sampleabout{MDI}
 
 
 @sampleabout{MDI}
 

-@see @sample{docview}, @sample{docvwmdi}
+@see @sample{docview}

 
 @sampledir{mdi}
 
 
 @sampledir{mdi}
 


@@ -613,13 +549,6 @@ a good starting point for learning how to use wxWidgets.
 
 @sampledir{minimal}
 
 
 @sampledir{minimal}
 

-@section page_samples_mobile Mobile Sample
-
-@todo Figure out what this sample is written for, maybe remove it from samples,
-since it seems to an incomplete test program (for mobile phone?)
-
-@sampledir{mobile}
-

 @section page_samples_nativdlg Native Windows Dialog Sample
 
 @sampleabout{native windows dialog}
 @section page_samples_nativdlg Native Windows Dialog Sample
 
 @sampleabout{native windows dialog}


@@ -633,9 +562,9 @@ since it seems to an incomplete test program (for mobile phone?)
 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,
 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.
+wxChoicebook, wxTreebook and wxToolbook in action.

 Test each of the controls, their orientation, images and pages using
 Test each of the controls, their orientation, images and pages using

-commands through menu.
+commands through the menu.

 
 @sampledir{notebook}
 
 
 @sampledir{notebook}
 


@@ -651,9 +580,10 @@ commands through menu.
 
 @sampleabout{wxGLCanvas}
 
 
 @sampleabout{wxGLCanvas}
 

-@li @b cube Draws only a cube to demonstrate how to write a basic wxWidgets OpenGL program.
-@li @b isosurf Draws a surface by reading coordinates from a dat file.
-@li @b penguin Draws a rotatable penguin by reading data from a dxf file.
+@li @b cube Draws a cube to demonstrate how to write a basic wxWidgets OpenGL program.
+    Arrow keys rotate the cube. Space bar toggles spinning.
+@li @b isosurf Draws a surface by reading coordinates from a DAT file.
+@li @b penguin Draws a rotatable penguin by reading data from a DXF file.

 
 @sampledir{opengl}
 
 
 @sampledir{opengl}
 


@@ -738,23 +668,17 @@ renderer and also how to write a shared library
 
 @sampleabout{wxScrolledWindow}
 
 
 @sampleabout{wxScrolledWindow}
 

-@see @sample{scrollsub}
-
-@sampledir{scroll}
-
-@section page_samples_scrollsub Scroll Subwindow Sample
-

 This sample demonstrates use of the ::wxScrolledWindow
 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.
+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.
+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.

 
 

-@sampledir{scrollsub}
+@sampledir{scroll}

 
 @section page_samples_shaped Shaped Window Sample
 
 
 @section page_samples_shaped Shaped Window Sample
 


@@ -896,28 +820,27 @@ 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.
 
 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.
+Last but not least: some of the text controls have tooltips and the sample also
+shows how tooltips can be centrally disabled and their latency controlled.

 
 @sampledir{text}
 
 @section page_samples_thread Thread Sample
 
 This sample demonstrates use of threads in connection with GUI programs.
 
 @sampledir{text}
 
 @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
 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.
+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 ::wxQueueEvent
+function and this sample demonstrates its usage.
+
+The other way is to use a ::wxMutexGuiEnter and ::wxMutexGuiLeave functions, but
+this is not currently shown in the sample.

 
 See also @ref overview_thread and wxThread.
 
 
 See also @ref overview_thread and wxThread.
 


@@ -966,10 +889,22 @@ demonstrated here as well - try the corresponding menu entries.
 
 @sampleabout{wxWidgets types}
 
 
 @sampleabout{wxWidgets types}
 

-@todo Rewrite its description ASAP.
+@todo This sample isn't very didactive; it's more than a set of tests rather
+      than a sample and thus should be rewritten with CppUnit and moved under "tests"

 
 @sampledir{typetest}
 
 
 @sampledir{typetest}
 

+@section page_samples_uiaction wxUIActionSimulator Sample
+
+@sampleabout{wxUIActionSimulator}
+
+This sample shows some features of wxUIActionSimulator class. When a simulation
+is run using its menu items, you can see that the button is pressed
+programmatically and the characters generated by the program appear in the text
+control.
+
+@sampledir{uiaction}
+

 @section page_samples_validate Validator Sample
 
 @sampleabout{wxValidator}
 @section page_samples_validate Validator Sample
 
 @sampleabout{wxValidator}


@@ -982,6 +917,15 @@ demonstrated here as well - try the corresponding menu entries.
 
 @sampledir{vscroll}
 
 
 @sampledir{vscroll}
 

+@section page_samples_webview wxWebView Sample
+
+The wxWebView sample demonstarates the various capabilities of the wxWebView
+control. It is set up as a simple single window web broswer, but with support
+for many of the more complex wxWebView features, including browsing through 
+archives.
+
+@sampledir{webview}
+

 @section page_samples_widgets Widgets Sample
 
 The widgets sample is the main presentation program for most simple and advanced
 @section page_samples_widgets Widgets Sample
 
 The widgets sample is the main presentation program for most simple and advanced


@@ -1025,7 +969,19 @@ features supported:
 
 @section page_samples_xrc XRC Sample
 
 
 @section page_samples_xrc XRC Sample
 

-@sampleabout{@ref overview_xrc}
+This sample shows how to use the various features of the @ref overview_xrc to
+create the gui of your program. It starts by loading and showing a frame and
+other resources. From its menu or toolbar you can then run the following dialogs:
+
+@li A non-derived wxDialog
+@li A derived dialog
+@li A dialog containing a large number of controls
+@li An uncentred dialog
+@li A dialog demonstrating the use of object references and ID ranges
+@li A dialog that contains a custom class
+@li A dialog with platform-specific features
+@li A dialog demonstrating wxArtProvider
+@li A dialog saying "VARIABLE EXPANSION ISN'T IMPLEMENTED CURRENTLY" :/

 
 @sampledir{xrc}
 
 
 @sampledir{xrc}