+/////////////////////////////////////////////////////////////////////////////
+// Name: samples.h
+// Purpose: Samples page of the Doxygen manual
+// Author: wxWidgets team
+// RCS-ID: $Id: utilities.h 52634 2008-03-20 13:45:17Z VS $
+// Licence: wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+
+@page page_samples Samples supplied with wxWidgets
+
+Probably the best way to learn wxWidgets is by reading the source of some 70+
+samples provided with it. Many aspects of wxWidgets programming can be learnt
+from them, but sometimes it is not simple to just choose the right sample to
+look at. This overview aims at describing what each sample does/demonstrates to
+make it easier to find the relevant one if a simple grep through all sources
+didn't help. They also provide some notes about using the samples and what
+features of wxWidgets are they supposed to test.
+
+There are currently more than 50 different samples as part of wxWidgets and
+this list is not complete. You should start your tour of wxWidgets with the
+minimal sample which is the wxWidgets version of
+"Hello, world!". It shows the basic structure of wxWidgets program and is the
+most commented sample of all - looking at its source code is recommended.
+
+The next most useful samples are probably widgets
+and controls which show many of wxWidgets native and
+generic controls, such as buttons, listboxes, checkboxes, comboboxes etc.
+
+Other, more complicated controls, have their own samples. In this category you
+may find the following samples showing the corresponding controls:
+
+@li wxCalendarCtrl: @ref page_samples_calendar
+@li wxListCtrl: @ref page_samples_listctrl
+@li wxTreeCtrl: @ref page_samples_treectrl
+@li wxGrid: @ref page_samples_grid
+
+Finally, it might be helpful to do a search in the entire sample directory if
+you can't find the sample showing the control you are interested in by
+name. Most classes contained in wxWidgets occur in at least one of the samples.
+
+@beginInvisibleTable
+<tr><td>
+@li @ref page_samples_minimal
+@li @ref page_samples_animate
+@li @ref page_samples_artprovider
+@li @ref page_samples_calendar
+@li @ref page_samples_config
+@li @ref page_samples_controls
+@li @ref page_samples_debugrpt
+@li @ref page_samples_dialogs
+@li @ref page_samples_dialup
+@li @ref page_samples_dnd
+@li @ref page_samples_event
+@li @ref page_samples_except
+@li @ref page_samples_exec
+@li @ref page_samples_font
+@li @ref page_samples_grid
+@li @ref page_samples_html
+@li @ref page_samples_image
+</td><td>
+@li @ref page_samples_internat
+@li @ref page_samples_layout
+@li @ref page_samples_listctrl
+@li @ref page_samples_mediaplayer
+@li @ref page_samples_notebook
+@li @ref page_samples_render
+@li @ref page_samples_scrollsub
+@li @ref page_samples_sockets
+@li @ref page_samples_sound
+@li @ref page_samples_statbar
+@li @ref page_samples_taborder
+@li @ref page_samples_text
+@li @ref page_samples_thread
+@li @ref page_samples_toolbar
+@li @ref page_samples_treectrl
+@li @ref page_samples_widgets
+@li @ref page_samples_wizard
+</td></tr>
+@endTable
+
+
+<hr>
+
+
+
+@section page_samples_minimal Minimal sample
+
+The minimal sample is what most people will know under the term Hello World,
+i.e. a minimal program that doesn't demonstrate anything apart from what is
+needed to write a program that will display a "hello" dialog. This is usually
+a good starting point for learning how to use wxWidgets.
+
+
+@section page_samples_animate Animate sample
+
+The @c animate sample shows how you can use wxAnimationCtrl
+control and shows concept of a platform-dependent animation encapsulated
+in wxAnimation.
+
+
+@section page_samples_artprovider Art provider sample
+
+The @c artprov sample shows how you can customize the look of standard
+wxWidgets dialogs by replacing default bitmaps/icons with your own versions.
+It also shows how you can use wxArtProvider to
+get stock bitmaps for use in your application.
+
+
+@section page_samples_calendar Calendar sample
+
+This font shows the calendar control in action. It
+shows how to configure the control (see the different options in the calendar
+menu) and also how to process the notifications from it.
+
+
+@section page_samples_config Config sample
+
+This sample demonstrates the wxConfig classes in a platform
+independent way, i.e. it uses text based files to store a given configuration under
+Unix and uses the Registry under Windows.
+
+See @ref overview_config for the descriptions of all features of this class.
+
+
+@section page_samples_controls Controls sample
+
+The controls sample is the main test program for most simple controls used in
+wxWidgets. The sample tests their basic functionality, events, placement,
+modification in terms of colour and font as well as the possibility to change
+the controls programmatically, such as adding an item to a list box etc. Apart
+from that, the sample uses a wxNotebook and tests most
+features of this special control (using bitmap in the tabs, using
+wxSizer instances and wxLayoutConstraints within notebook pages, advancing pages
+programmatically and vetoing a page change by intercepting the wxNotebookEvent.
+
+The various controls tested are listed here:
+
+@li wxButton
+@li wxBitmapButton
+@li wxCheckBox
+@li wxChoice
+@li wxComboBox
+@li wxGauge
+@li wxStaticBox
+@li wxListBox
+@li wxSpinCtrl
+@li wxSpinButton
+@li wxStaticText
+@li wxStaticBitmap
+@li wxRadioBox
+@li wxRadioButton
+@li wxSlider
+
+
+@section page_samples_debugrpt DebugRpt sample
+
+This sample shows how to use wxDebugReport class to
+generate a debug report in case of a program crash or otherwise. On start up,
+it proposes to either crash itself (by dereferencing a NULL pointer) or
+generate debug report without doing it. Next it initializes the debug report
+with standard information adding a custom file to it (just a timestamp) and
+allows to view the information gathered using
+wxDebugReportPreview.
+
+For the report processing part of the sample to work you should make available
+a Web server accepting form uploads, otherwise
+wxDebugReportUpload will report an error.
+
+
+@section page_samples_dialogs Dialogs sample
+
+This sample shows how to use the common dialogs available from wxWidgets. These
+dialogs are described in detail in the @ref overview_cmndlg.
+
+
+@section page_samples_dialup Dialup sample
+
+This sample shows the wxDialUpManager
+class. In the status bar, it displays the information gathered through its
+interface: in particular, the current connection status (online or offline) and
+whether the connection is permanent (in which case a string `LAN' appears in
+the third status bar field - but note that you may be on a LAN not
+connected to the Internet, in which case you will not see this) or not.
+
+Using the menu entries, you may also dial or hang up the line if you have a
+modem attached and (this only makes sense for Windows) list the available
+connections.
+
+
+@section page_samples_dnd DnD sample
+
+This sample shows both clipboard and drag and drop in action. It is quite non
+trivial and may be safely used as a basis for implementing the clipboard and
+drag and drop operations in a real-life program.
+
+When you run the sample, its screen is split in several parts. On the top,
+there are two listboxes which show the standard derivations of
+wxDropTarget:
+wxTextDropTarget and
+wxFileDropTarget.
+
+The middle of the sample window is taken by the log window which shows what is
+going on (of course, this only works in debug builds) and may be helpful to see
+the sequence of steps of data transfer.
+
+Finally, the last part is used for dragging text from it to either one of the
+listboxes (only one will accept it) or another application. The last
+functionality available from the main frame is to paste a bitmap from the
+clipboard (or, in the case of the Windows version, also a metafile) - it will be
+shown in a new frame.
+
+So far, everything we mentioned was implemented with minimal amount of code
+using standard wxWidgets classes. The more advanced features are demonstrated
+if you create a shape frame from the main frame menu. A shape is a geometric
+object which has a position, size and color. It models some
+application-specific data in this sample. A shape object supports its own
+private wxDataFormat which means that you may cut and
+paste it or drag and drop (between one and the same or different shapes) from
+one sample instance to another (or the same). However, chances are that no
+other program supports this format and so shapes can also be rendered as
+bitmaps which allows them to be pasted/dropped in many other applications
+(and, under Windows, also as metafiles which are supported by most of Windows
+programs as well - try Write/Wordpad, for example).
+
+Take a look at DnDShapeDataObject class to see how you may use
+wxDataObject to achieve this.
+
+
+@section page_samples_event Event sample
+
+The event sample demonstrates various features of the wxWidgets events. It
+shows using dynamic events and connecting/disconnecting the event handlers
+during run time and also using
+PushEventHandler() and
+PopEventHandler().
+
+
+@section page_samples_except Except(ions) sample
+
+This very simple sample shows how to use C++ exceptions in wxWidgets programs,
+i.e. where to catch the exception which may be thrown by the program code. It
+doesn't do anything very exciting by itself, you need to study its code to
+understand what goes on.
+
+You need to build the library with @c wxUSE_EXCEPTIONS being set to @c 1
+and compile your code with C++ exceptions support to be able to build this
+sample.
+
+
+@section page_samples_exec Exec sample
+
+The exec sample demonstrates the wxExecute and
+wxShell functions. Both of them are used to execute the
+external programs and the sample shows how to do this synchronously (waiting
+until the program terminates) or asynchronously (notification will come later).
+
+It also shows how to capture the output of the child process in both
+synchronous and asynchronous cases and how to kill the processes with
+wxProcess::Kill and test for their existence with
+wxProcess::Exists.
+
+
+@section page_samples_font Font sample
+
+The font sample demonstrates wxFont,
+wxFontEnumerator and
+wxFontMapper classes. It allows you to see the fonts
+available (to wxWidgets) on the computer and shows all characters of the
+chosen font as well.
+
+
+@section page_samples_grid Grid sample
+
+@todo WRITE THIS DESCRIPTION.
+
+
+@section page_samples_html HTML samples
+
+Eight HTML samples (you can find them in directory @c samples/html)
+cover all features of the HTML sub-library.
+
+@li @b Test demonstrates how to create wxHtmlWindow
+and also shows most supported HTML tags.
+
+@li @b Widget shows how you can embed ordinary controls or windows within an
+HTML page. It also nicely explains how to write new tag handlers and extend
+the library to work with unsupported tags.
+
+@li @b About may give you an idea how to write good-looking About boxes.
+
+@li @b Zip demonstrates use of virtual file systems in wxHTML. The zip archives
+handler (ships with wxWidgets) allows you to access HTML pages stored
+in a compressed archive as if they were ordinary files.
+
+@li @b Virtual is yet another virtual file systems demo. This one generates pages at run-time.
+You may find it useful if you need to display some reports in your application.
+
+@li @b Printing explains use of wxHtmlEasyPrinting
+class which serves as as-simple-as-possible interface for printing HTML
+documents without much work. In fact, only few function calls are sufficient.
+
+@li @b Help and @b Helpview are variations on displaying HTML help
+(compatible with MS HTML Help Workshop). @e Help shows how to embed
+wxHtmlHelpController in your application
+while @e Helpview is a simple tool that only pops up the help window and
+displays help books given at command line.
+
+
+@section page_samples_image Image sample
+
+The image sample demonstrates use of the wxImage class
+and shows how to download images in a variety of formats, currently PNG, GIF,
+TIFF, JPEG, BMP, PNM and PCX. The top of the sample shows two rectangles, one
+of which is drawn directly in the window, the other one is drawn into a
+wxBitmap, converted to a wxImage, saved as a PNG image
+and then reloaded from the PNG file again so that conversions between wxImage
+and wxBitmap as well as loading and saving PNG files are tested.
+
+At the bottom of the main frame there is a test for using a monochrome bitmap by
+drawing into a wxMemoryDC. The bitmap is then drawn
+specifying the foreground and background colours with
+wxDC::SetTextForeground and
+wxDC::SetTextBackground (on the left). The
+bitmap is then converted to a wxImage and the foreground colour (black) is
+replaced with red using wxImage::Replace.
+
+This sample also contains the code for testing the image rotation and resizing
+and using raw bitmap access, see the corresponding menu commands.
+
+
+@section page_samples_internat Internat(ionalization) sample
+
+The not very clearly named internat sample demonstrates the wxWidgets
+internationalization (i18n for short from now on) features. To be more
+precise, it only shows localization support, i.e. support for translating the
+program messages into another language while true i18n would also involve
+changing the other aspects of the programs behaviour.
+
+More information about this sample can be found in the @c readme.txt file in
+its directory. Please also see the @ref overview_i18n.
+
+
+@section page_samples_layout Layout sample
+
+The layout sample demonstrates the two different layout systems offered
+by wxWidgets. When starting the program, you will see a frame with some
+controls and some graphics. The controls will change their size whenever
+you resize the entire frame and the exact behaviour of the size changes
+is determined using the wxLayoutConstraints
+class. See also the overview and the
+wxIndividualLayoutConstraint
+class for further information.
+
+The menu in this sample offers two more tests, one showing how to use
+a wxBoxSizer in a simple dialog and the other one
+showing how to use sizers in connection with a wxNotebook
+class. See also wxSizer.
+
+
+@section page_samples_listctrl Listctrl sample
+
+This sample shows the wxListCtrl control. Different modes
+supported by the control (list, icons, small icons, report) may be chosen from
+the menu.
+
+The sample also provides some timings for adding/deleting/sorting a lot of
+(several thousands) items into the control.
+
+
+@section page_samples_mediaplayer Mediaplayer sample
+
+This sample demonstrates how to use all the features of
+wxMediaCtrl and play various types of sound, video,
+and other files.
+
+It replaces the old dynamic sample.
+
+
+@section page_samples_notebook Notebook sample
+
+This samples shows wxBookCtrl family of controls.
+Although initially it was written to demonstrate wxNotebook
+only, it can now be also used to see wxListbook,
+wxChoicebook and wxTreebook in action.
+Test each of the controls, their orientation, images and pages using
+commands through menu.
+
+
+@section page_samples_render Render sample
+
+This sample shows how to replace the default wxWidgets
+renderer and also how to write a shared library
+(DLL) implementing a renderer and load and unload it during the run-time.
+
+
+@section page_samples_scrollsub Scroll subwindow sample
+
+This sample demonstrates use of the wxScrolledWindow
+class including placing subwindows into it and drawing simple graphics. It uses the
+SetTargetWindow method and thus the effect
+of scrolling does not show in the scrolled window itself, but in one of its subwindows.
+
+Additionally, this samples demonstrates how to optimize drawing operations in wxWidgets,
+in particular using the wxWindow::IsExposed method with
+the aim to prevent unnecessary drawing in the window and thus reducing or removing
+flicker on screen.
+
+
+@section page_samples_sockets Sockets sample
+
+The sockets sample demonstrates how to use the communication facilities
+provided by wxSocket. There are two different
+applications in this sample: a server, which is implemented using a
+wxSocketServer object, and a client, which
+is implemented as a wxSocketClient.
+
+The server binds to the local address, using TCP port number 3000,
+sets up an event handler to be notified of incoming connection requests
+(@b wxSOCKET_CONNECTION events), and sits there, waiting for clients
+(@e listening, in socket parlance). For each accepted connection,
+a new wxSocketBase object is created. These
+socket objects are independent from the server that created them, so
+they set up their own event handler, and then request to be notified
+of @b wxSOCKET_INPUT (incoming data) or @b wxSOCKET_LOST
+(connection closed at the remote end) events. In the sample, the event
+handler is the same for all connections; to find out which socket the
+event is addressed to, the GetSocket function
+is used.
+
+Although it might take some time to get used to the event-oriented
+system upon which wxSocket is built, the benefits are many. See, for
+example, that the server application, while being single-threaded
+(and of course without using fork() or ugly select() loops) can handle
+an arbitrary number of connections.
+
+The client starts up unconnected, so you can use the Connect... option
+to specify the address of the server you are going to connect to (the
+TCP port number is hard-coded as 3000). Once connected, a number of
+tests are possible. Currently, three tests are implemented. They show
+how to use the basic IO calls in wxSocketBase,
+such as wxSocketBase::Read, wxSocketBase::Write,
+wxSocketBase::ReadMsg and wxSocketBase::WriteMsg,
+and how to set up the correct IO flags depending on what you are going to
+do. See the comments in the code for more information. Note that because
+both clients and connection objects in the server set up an event handler
+to catch @b wxSOCKET_LOST events, each one is immediately notified
+if the other end closes the connection.
+
+There is also a URL test which shows how to use
+the wxURL class to fetch data from a given URL.
+
+The sockets sample is work in progress. Some things to do:
+
+@li More tests for basic socket functionality.
+@li More tests for protocol classes (wxProtocol and its descendants).
+@li Tests for the recently added (and still in alpha stage) datagram sockets.
+@li New samples which actually do something useful (suggestions accepted).
+
+
+@section page_samples_sound Sound sample
+
+The @c sound sample shows how to use wxSound for simple
+audio output (e.g. notifications).
+
+
+@section page_samples_statbar Statbar sample
+
+This sample shows how to create and use wxStatusBar. Although most of the
+samples have a statusbar, they usually only create a default one and only
+do it once.
+
+Here you can see how to recreate the statusbar (with possibly different number
+of fields) and how to use it to show icons/bitmaps and/or put arbitrary
+controls into it.
+
+
+@section page_samples_taborder Tab order sample
+
+This sample allows to test keyboard navigation (mostly done using the
+@c TAB key, hence the sample name) between different controls.
+It shows the use of wxWindow::MoveBeforeInTabOrder() and
+MoveAfterInTabOrder() methods to change
+the default order of the windows in the navigation chain and of
+wxWindow::Navigate() for moving focus along this
+chain.
+
+
+@section page_samples_text Text sample
+
+This sample demonstrates four features: firstly the use and many variants of
+the wxTextCtrl class (single line, multi line, read only,
+password, ignoring TAB, ignoring ENTER).
+
+Secondly it shows how to intercept a wxKeyEvent in both
+the raw form using the @c EVT_KEY_UP and @c EVT_KEY_DOWN macros and the
+higher level from using the @c EVT_CHAR macro. All characters will be logged
+in a log window at the bottom of the main window. By pressing some of the function
+keys, you can test some actions in the text ctrl as well as get statistics on the
+text ctrls, which is useful for testing if these statistics actually are correct.
+
+Thirdly, on platforms which support it, the sample will offer to copy text to the
+wxClipboard and to paste text from it. The GTK version will
+use the so called PRIMARY SELECTION, which is the pseudo clipboard under X and
+best known from pasting text to the XTerm program.
+
+Last not least: some of the text controls have tooltips and the sample also shows
+how tooltips can be centrally disabled and their latency controlled.
+
+
+@section page_samples_thread Thread sample
+
+This sample demonstrates use of threads in connection with GUI programs.
+There are two fundamentally different ways to use threads in GUI programs and
+either way has to take care of the fact that the GUI library itself usually
+is not multi-threading safe, i.e. that it might crash if two threads try to
+access the GUI class simultaneously. One way to prevent that is have a normal
+GUI program in the main thread and some worker threads which work in the
+background. In order to make communication between the main thread and the
+worker threads possible, wxWidgets offers the wxPostEvent
+function and this sample makes use of this function.
+
+The other way to use a so called Mutex (such as those offered in the wxMutex
+class) that prevent threads from accessing the GUI classes as long as any other
+thread accesses them. For this, wxWidgets has the wxMutexGuiEnter
+and wxMutexGuiLeave functions, both of which are
+used and tested in the sample as well.
+
+See also @ref overview_thread and wxThread.
+
+
+@section page_samples_toolbar Toolbar sample
+
+The toolbar sample shows the wxToolBar class in action.
+
+The following things are demonstrated:
+
+@li Creating the toolbar using wxToolBar::AddTool and wxToolBar::AddControl: see
+ MyApp::InitToolbar in the sample.
+@li Using @c EVT_UPDATE_UI handler for automatically enabling/disabling
+ toolbar buttons without having to explicitly call EnableTool. This is done
+ in MyFrame::OnUpdateCopyAndCut.
+@li Using wxToolBar::DeleteTool and wxToolBar::InsertTool to dynamically update the
+ toolbar.
+
+Some buttons in the main toolbar are check buttons, i.e. they stay checked when
+pressed. On the platforms which support it, the sample also adds a combobox
+to the toolbar showing how you can use arbitrary controls and not only buttons
+in it.
+
+If you toggle another toolbar in the sample (using @c Ctrl-A) you will also
+see the radio toolbar buttons in action: the first three buttons form a radio
+group, i.e. checking any of them automatically unchecks the previously
+checked one.
+
+
+@section page_samples_treectrl Treectrl sample
+
+This sample demonstrates using the wxTreeCtrl class. Here
+you may see how to process various notification messages sent by this control
+and also when they occur (by looking at the messages in the text control in
+the bottom part of the frame).
+
+Adding, inserting and deleting items and branches from the tree as well as
+sorting (in default alphabetical order as well as in custom one) is
+demonstrated here as well - try the corresponding menu entries.
+
+
+@section page_samples_widgets Widgets sample
+
+The widgets sample is the main presentation program for most simple and advanced
+native controls and complex generic widgets provided by wxWidgets.
+The sample tests their basic functionality, events, placement, modification
+in terms of colour and font as well as the possibility to change
+the controls programmatically, such as adding an item to a list box etc.
+All widgets are categorized for easy browsing.
+
+
+@section page_samples_wizard Wizard sample
+
+This sample shows the so-called wizard dialog (implemented using
+wxWizard and related classes). It shows almost all
+features supported:
+
+@li Using bitmaps with the wizard and changing them depending on the page
+ shown (notice that wxValidationPage in the sample has a different image from
+ the other ones)
+@li Using TransferDataFromWindow
+ to verify that the data entered is correct before passing to the next page
+ (done in wxValidationPage which forces the user to check a checkbox before
+ continuing).
+@li Using more elaborated techniques to allow returning to the previous
+ page, but not continuing to the next one or vice versa (in wxRadioboxPage)
+@li This (wxRadioboxPage) page also shows how the page may process the
+ @e Cancel button itself instead of relying on the wizard parent to do it.
+@li Normally, the order of the pages in the wizard is known at compile-time,
+ but sometimes it depends on the user choices: wxCheckboxPage shows how to
+ dynamically decide which page to display next (see also
+ wxWizardPage)
+
+*/
projects / wxWidgets.git / commitdiff
