moved the samples in a separate page so it has a summary of all the samples descriptions and so writing references to samples is shorter (@ref page_samples_xxx instead of @ref page_utils_samples_xxx)
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52705 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
parent
e18e78a7cc
commit
dc28cdf8d4
@ -20,6 +20,7 @@
|
||||
@li @subpage page_introduction
|
||||
@li @subpage page_multiplatform
|
||||
@li @subpage page_utils
|
||||
@li @subpage page_samples
|
||||
@li @subpage page_strategies
|
||||
@li @subpage page_libs
|
||||
@li @subpage page_constants
|
||||
|
||||
602
docs/doxygen/mainpages/samples.h
Normal file
602
docs/doxygen/mainpages/samples.h
Normal file
@ -0,0 +1,602 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// 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)
|
||||
|
||||
*/
|
||||
@ -8,602 +8,86 @@
|
||||
|
||||
/**
|
||||
|
||||
@page page_utils Utilities and samples supplied with wxWidgets
|
||||
@page page_utils Utilities supplied with wxWidgets
|
||||
|
||||
@li @ref page_utils_utils
|
||||
@li @ref page_utils_samples
|
||||
In addition to the wxWidgets libraries (see @ref page_libs), some utilities
|
||||
are available to the users in the @c utils hierarchy (even if some of them are
|
||||
explicitely coinceived for wxWidgets maintainance and will probably be of
|
||||
little use to others).
|
||||
|
||||
Please note that these utilities do represent only the utilities developed
|
||||
and maintained by the wxWidgets team.
|
||||
There are lots of other user-contributed and user-maintained packages;
|
||||
see the wxWidgets download page: http://www.wxwidgets.org/downloads
|
||||
or directly http://wxcode.sourceforge.net or http://www.wxcommunity.com/ .
|
||||
|
||||
@li @ref page_utils_emulator
|
||||
@li @ref page_utils_helpgen
|
||||
@li @ref page_utils_helpview
|
||||
@li @ref page_utils_hhp2cached
|
||||
@li @ref page_utils_tex2rtf
|
||||
@li @ref page_utils_wxrc
|
||||
|
||||
|
||||
<hr>
|
||||
|
||||
|
||||
@section page_utils_utils Utilities
|
||||
@section page_utils_emulator Emulator
|
||||
|
||||
In addition to the @ref page_libs, some
|
||||
additional utilities are supplied in the @c utils hierarchy.
|
||||
Xnest-based display emulator for X11-based PDA applications.
|
||||
|
||||
For other user-contributed packages, please see the Contributions page
|
||||
on the wxWidgets Web site http://www.wxwidgets.org.
|
||||
<!-- On some systems, the Xnest window does not synchronise with the
|
||||
'skin' window. THIS ISN'T THE PLACE FOR THIS STATEMENT I THINK -->
|
||||
|
||||
This program can be found in @c utils/emulator.
|
||||
|
||||
|
||||
@subsection page_utils_utils_helpview Helpview
|
||||
@section page_utils_helpgen Helpgen
|
||||
|
||||
Helpgen takes C++ header files and generates a Tex2RTF-compatible
|
||||
documentation file for each class it finds, using comments as appropriate.
|
||||
This is a good way to start a reference for a set of classes.
|
||||
|
||||
Helpgen can be found in @c utils/HelpGen.
|
||||
|
||||
|
||||
@section page_utils_helpview Helpview
|
||||
|
||||
Helpview is a program for displaying wxWidgets HTML
|
||||
Help files. In many cases, you may wish to use the wxWidgets HTML
|
||||
Help classes from within your application, but this provides a
|
||||
handy stand-alone viewer. See @ref overview_html for more details.
|
||||
You can find it in @c samples/html/helpview.
|
||||
|
||||
@subsection page_utils_utils_tex2rtf Tex2RTF
|
||||
You can find Helpview in @c utils/helpview.
|
||||
|
||||
|
||||
@section page_utils_hhp2cached HHP2Cached
|
||||
|
||||
This utility creates a "cached" version of a @c .hhp file; using cached @c .hhp
|
||||
files in wxHtmlHelpController can drammatically improve the performances
|
||||
of the help viewer. See wxHtmlHelpController for more details.
|
||||
|
||||
You can find HHP2Cached in @c utils/helpview.
|
||||
|
||||
|
||||
@section page_utils_tex2rtf Tex2RTF
|
||||
|
||||
Supplied with wxWidgets is a utility called Tex2RTF for
|
||||
converting @e LaTeX manuals HTML, MS HTML Help, wxHTML Help, RTF, and Windows
|
||||
Help RTF formats. Tex2RTF was used for the wxWidgets manuals and can be used
|
||||
independently by authors wishing to create on-line and printed manuals from the
|
||||
same @e LaTeX source. Please see the separate documentation for Tex2RTF.
|
||||
|
||||
You can find it under @c utils/tex2rtf.
|
||||
|
||||
@subsection page_utils_utils_helpgen Helpgen
|
||||
|
||||
Helpgen takes C++ header files and generates a Tex2RTF-compatible
|
||||
documentation file for each class it finds, using comments as appropriate.
|
||||
This is a good way to start a reference for a set of classes.
|
||||
Helpgen can be found in @c utils/HelpGen.
|
||||
@section page_utils_wxrc WxRC
|
||||
|
||||
@subsection page_utils_utils_emulator Emulator
|
||||
This utility allows the user to compile @e binary versions of their XRC files,
|
||||
which are compressed and can be loaded faster than plain XRC files.
|
||||
See @ref overview_xrc for more info.
|
||||
|
||||
Xnest-based display emulator for X11-based PDA applications.
|
||||
On some systems, the Xnest window does not synchronise with the
|
||||
'skin' window. This program can be found in @c utils/emulator.
|
||||
You can find it under @c utils/wxrc.
|
||||
|
||||
|
||||
|
||||
|
||||
@section page_utils_samples 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:
|
||||
|
||||
@li wxCalendarCtrl: @ref page_utils_samples_calendar
|
||||
@li wxListCtrl: @ref page_utils_samples_listctrl
|
||||
@li wxTreeCtrl: @ref page_utils_samples_treectrl
|
||||
@li wxGrid: @ref page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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().
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_samples_grid Grid sample
|
||||
|
||||
TODO.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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).
|
||||
|
||||
|
||||
@subsection page_utils_samples_sound Sound sample
|
||||
|
||||
The @c sound sample shows how to use wxSound for simple
|
||||
audio output (e.g. notifications).
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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.
|
||||
|
||||
|
||||
@subsection page_utils_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)
|
||||
|
||||
*/
|
||||
|
||||
@ -38,7 +38,7 @@ displayed one page at a time. wxWidgets has five variants of this control:
|
||||
@li wxTreebook: controlled by a wxTreeCtrl
|
||||
@li wxToolbook: controlled by a wxToolBar
|
||||
|
||||
See the @ref page_utils_samples_notebook for an example of wxBookCtrl usage.
|
||||
See the @ref page_samples_notebook for an example of wxBookCtrl usage.
|
||||
|
||||
|
||||
@section overview_bookctrl_bestbookctrl Best Book
|
||||
|
||||
@ -12,7 +12,7 @@
|
||||
|
||||
Classes: wxDataObject, wxClipboard, wxDataFormat, wxDropSource, wxDropTarget
|
||||
|
||||
See also: @ref overview_dnd and @ref page_utils_samples_dnd
|
||||
See also: @ref overview_dnd and @ref page_samples_dnd
|
||||
|
||||
This overview discusses data transfer through clipboard or drag and drop.
|
||||
In wxWidgets, these two ways to transfer data (either between different
|
||||
|
||||
@ -16,7 +16,7 @@
|
||||
Note that @c wxUSE_DRAG_AND_DROP must be defined in @c setup.h in order
|
||||
to use drag and drop in wxWidgets.
|
||||
|
||||
See also: @ref overview_dataobject and @ref page_utils_samples_dnd.
|
||||
See also: @ref overview_dataobject and @ref page_samples_dnd.
|
||||
|
||||
It may be noted that data transfer to and from the clipboard is quite
|
||||
similar to data transfer with drag and drop and the code to implement
|
||||
|
||||
@ -95,7 +95,7 @@
|
||||
Finally, if you don't like using macros for static initialization of the event
|
||||
tables you may also use wxEvtHandler::Connect to
|
||||
connect the events to the handlers dynamically, during run-time. See the
|
||||
@ref page_utils_samples_event for an example of doing it.
|
||||
@ref page_samples_event for an example of doing it.
|
||||
|
||||
|
||||
|
||||
@ -342,7 +342,7 @@
|
||||
You can ignore the @e value parameter of the DECLARE_EVENT_TYPE macro
|
||||
since it is used only for backwards compatibility with wxWidgets 2.0.x based
|
||||
applications where you have to give the event type ID an explicit value.
|
||||
See also the @ref page_utils_samples_event for an example of code
|
||||
See also the @ref page_samples_event for an example of code
|
||||
defining and working with the custom event types.
|
||||
|
||||
|
||||
|
||||
@ -80,7 +80,7 @@
|
||||
course, it would be fairly useless if it tried to determine these mappings by
|
||||
itself, so, instead, it (optionally) asks the user and remembers his answers
|
||||
so that the next time the program will automatically choose the correct font.
|
||||
All these topics are illustrated by the @ref page_utils_samples_font;
|
||||
All these topics are illustrated by the @ref page_samples_font;
|
||||
please refer to it and the documentation of the classes mentioned here for
|
||||
further explanations.
|
||||
|
||||
|
||||
@ -84,7 +84,7 @@ translated special key names such as Backspace, End, Insert, etc.
|
||||
@see
|
||||
@li The gettext Manual: http://www.gnu.org/software/gettext/manual/gettext.html
|
||||
@li @ref overview_nonenglish - It focuses on handling charsets related problems.
|
||||
@li @ref page_utils_samples_internat - Shows you how all this looks in practice.
|
||||
@li @ref page_samples_internat - Shows you how all this looks in practice.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user