diff --git a/docs/doxygen/mainpages/samples.h b/docs/doxygen/mainpages/samples.h index 81eaf04106..0b5c3b576a 100644 --- a/docs/doxygen/mainpages/samples.h +++ b/docs/doxygen/mainpages/samples.h @@ -11,15 +11,60 @@ @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 learned +Arguably the best way to learn wxWidgets is by reading the sources of many samples, +or examples, provided with it. Many aspects of wxWidgets programming can be learned 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 80 different samples as part of wxWidgets: the +Notice that all wxWidgets samples mentioned here 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 +https://github.com/wxWidgets/wxWidgets/tree/master/samples/ but you need to +download the source distribution in order to be able to build them (highly +recommended). + +@section page_samples_building Building and running the samples + +Although reading the samples code can be very useful, it may not be sufficient +and often it is even more useful to experiment by making a small change to a +sample and checking how it works when running the sample. + +Before being able to run them, you need to be able build the sample you're +interested in. The right way to do it depends on the way you built wxWidgets +itself (see @ref overview_install for more details): + +- Under Microsoft Windows (MSW): + - If you're using Microsoft Visual C++ compiler (MSVC), you need to + use @c makefile.vc from the directory of the sample to build it. Open + "Developer Command Prompt", navigate to the sample directory and run + nmake -f makefile.vc command with the additional arguments + corresponding to your library build, e.g. @c BUILD=debug. See @ref + msw_build_msvs "MSVS instructions" for more information. + - If you're using MinGW, use @c makefile.gcc in the sample directory in a + similar way. Note that if you use MSYS2 or another Unix-like environment + for building, you should use the Unix instructions below instead. +- Under Unix systems (including macOS): + - If you installed wxWidgets from your distribution binaries, you can use + @c makefile.unx in the sample directory to build it using the version of + wxWidgets already installed on your system. Use make -f + makefile.unx in the sample directory to build it. + - If you built wxWidgets from source using configure, you may use @c + Makefile in the directory with the same name as the sample directory, but + under the @em build directory, i.e. the one where you ran configure, and + @em not under the source directory. Just run @c make to build the sample in + the build directory subdirectory, e.g. @c ~/build/wx/samples/minimal. You + can also build all the samples at once by doing make samples, + but be warned that this might take some time on older and slower machines. + + +@section page_samples_overview Overview of the available samples + +There are currently almost 100 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 @@ -41,23 +86,10 @@ may find the following samples showing the corresponding controls: @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 -https://github.com/wxWidgets/wxWidgets/tree/master/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. - - @section page_samples_access Accessibility Sample