X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a3465294781166ac397a6d06170c64f499a24b3f..08a38009580bd3d38d2ea47a90773c69cccaf2fd:/docs/doxygen/utilities.h

diff --git a/docs/doxygen/utilities.h b/docs/doxygen/utilities.h
index 40c3293d28..a677f98c9c 100644
--- a/docs/doxygen/utilities.h
+++ b/docs/doxygen/utilities.h
@@ -8,7 +8,16 @@
 
 /*!
 
- @page utilities_page Utilities and libraries supplied with wxWidgets
+ @page utilities_page Utilities and samples supplied with wxWidgets
+
+ @li @ref utils
+ @li @ref samples
+
+
+ <hr>
+
+
+ @section utils Utilities
 
  In addition to the @ref libraries_page, some
  additional utilities are supplied in the @c utils hierarchy.
@@ -38,4 +47,559 @@
  On some systems, the Xnest window does not synchronise with the
  'skin' window. This program can be found in @c utils/emulator.
 
+
+
+
+ @section samples wxWidgets samples
+ 
+ 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.
+ 
+ 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:
+ 
+ \begin{twocollist}\itemsep=0pt
+ \twocolitem{wxCalendarCtrl}{samplecalendar}
+ \twocolitem{wxListCtrl}{samplelistctrl}
+ \twocolitem{wxTreeCtrl}{sampletreectrl}
+ \twocolitem{wxGrid}{samplegrid}
+ \end{twocollist}
+ 
+ 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.
+ 
+ 
+ @subsection sampleminimal 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.
+ 
+ 
+ @subsection sampleanimate 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 sampleartprovider 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 samplecalendar 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 sampleconfig 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 wxConfig overview for the descriptions of all
+ features of this class.
+ 
+ 
+ @subsection samplecontrols 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:
+ 
+ \begin{twocollist}\itemsep=0pt
+ \twocolitem{wxButton}{wxbutton}
+ \twocolitem{wxBitmapButton}{wxbitmapbutton}
+ \twocolitem{wxCheckBox}{wxcheckbox}
+ \twocolitem{wxChoice}{wxchoice}
+ \twocolitem{wxComboBox}{wxcombobox}
+ \twocolitem{wxGauge}{wxgauge}
+ \twocolitem{wxStaticBox}{wxstaticbox}
+ \twocolitem{wxListBox}{wxlistbox}
+ \twocolitem{wxSpinCtrl}{A spin ctrl with a text field and a `up-down' control}
+ \twocolitem{wxSpinButton}{wxspinbutton}
+ \twocolitem{wxStaticText}{wxstatictext}
+ \twocolitem{wxStaticBitmap}{wxstaticbitmap}
+ \twocolitem{wxRadioBox}{wxradiobox}
+ \twocolitem{wxRadioButton}{wxradiobutton}
+ \twocolitem{wxSlider}{wxslider}
+ \end{twocollist}
+ 
+ 
+ @subsection sampledebugrpt 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 sampledialogs Dialogs sample
+ 
+ This sample shows how to use the common dialogs available from wxWidgets. These
+ dialogs are described in detail in the Common dialogs overview.
+ 
+ 
+ @subsection sampledialup 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 samplednd 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 sampleevent 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 sampleexcept 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 sampleexec 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 samplefont 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 samplegrid Grid sample
+ 
+ TODO.
+ 
+ 
+ @subsection samplehtml 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 sampleimage 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 sampleinternat 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 see also i18n overview.
+ 
+ 
+ @subsection samplelayout 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 samplelistctrl 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 samplemediaplayer 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 samplenotebook 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 samplerender 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 samplescrollsub 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 samplesockets 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 samplesound Sound sample
+ 
+ The @c sound sample shows how to use wxSound for simple
+ audio output (e.g. notifications).
+ 
+ 
+ @subsection samplestatbar 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 sampletaborder 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 sampletext 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 samplethread 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 thread_overview and wxThread.
+ 
+ 
+ @subsection sampletoolbar 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 sampletreectrl 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 samplewidgets 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 samplewizard 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)
+
 */