From 08a38009580bd3d38d2ea47a90773c69cccaf2fd Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Tue, 19 Feb 2008 23:04:18 +0000 Subject: [PATCH] added wxWidgets samples git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@51929 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/utilities.h | 566 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 565 insertions(+), 1 deletion(-) 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 + + +
+ + + @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) + */