]> git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/mainpages/samples.h
Explicitly specify target names for all configurations in VC10 projects.
[wxWidgets.git] / docs / doxygen / mainpages / samples.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: samples.h
3 // Purpose: Samples page of the Doxygen manual
4 // Author: wxWidgets team
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
7
8 /**
9
10 @page page_samples Samples Overview
11
12 @tableofcontents
13
14 Probably the best way to learn wxWidgets is by reading the source of some 80+
15 samples provided with it. Many aspects of wxWidgets programming can be learnt
16 from them, but sometimes it is not simple to just choose the right sample to
17 look at. This overview aims at describing what each sample does/demonstrates to
18 make it easier to find the relevant one if a simple grep through all sources
19 didn't help. They also provide some notes about using the samples and what
20 features of wxWidgets are they supposed to test.
21
22 There are currently more than 80 different samples as part of wxWidgets: the
23 list in this page is not complete! You should start your tour of wxWidgets with
24 the @ref page_samples_minimal which is the wxWidgets version of "Hello,
25 world!". It shows the basic structure of wxWidgets program and is the most
26 commented sample of all - looking at its source code is recommended.
27
28 The next most useful sample is @ref page_samples_widgets which shows many of
29 wxWidgets controls, such as buttons, text entry zones, list boxes, check boxes,
30 combo boxes etc. It is organized in many different source files, one per each
31 control, which makes it easier to study it, and also allows to change various
32 control styles and call its methods interactively.
33
34 Other, more complicated controls, have their own samples. In this category you
35 may find the following samples showing the corresponding controls:
36
37 @li wxCalendarCtrl: @ref page_samples_calendar
38 @li wxListCtrl: @ref page_samples_listctrl
39 @li wxTreeCtrl: @ref page_samples_treectrl
40 @li wxGrid: @ref page_samples_grid
41 @li wxDataViewCtrl: @ref page_samples_dataview
42 @li wxWebView: @ref page_samples_webview
43
44 Notice that all wxWidgets samples mentioned above can be found in @c samples
45 subdirectory of the library distribution. When a @c foobar sample is mentioned
46 below, its sources can be found in @c samples/foobar directory of your
47 wxWidgets tree. If you installed wxWidgets from a binary package, you might not
48 have this directory. In this case, you may view the samples online at
49 http://svn.wxwidgets.org/viewvc/wx/wxWidgets/trunk/samples/ but you need to
50 download the source distribution in order to be able to build them (highly
51 recommended).
52
53 Final advice is to do a search in the entire samples directory if you can't
54 find the sample showing the control you are interested in by name. Most classes
55 contained in wxWidgets occur in at least one of the samples.
56
57 @todo Write descriptions for the samples who description started with
58 "This sample demonstrates", they are semi-auto generated.
59
60
61
62 @section page_samples_access Accessibility Sample
63
64 This sample shows how you can use the wxAccessible classes in a
65 simple GUI program.
66
67 @buildwith{wxUSE_ACCESSIBILITY}
68
69 @sampledir{access}
70
71 @section page_samples_animate Animation Sample
72
73 This sample shows how you can use wxAnimationCtrl
74 control and shows concept of a platform-dependent animation encapsulated
75 in wxAnimation.
76
77 @sampledir{animate}
78
79 @section page_samples_artprov Art Provider Sample
80
81 This sample shows how you can customize the look of standard
82 wxWidgets dialogs by replacing default bitmaps/icons with your own versions.
83 It also shows how you can use wxArtProvider to
84 get stock bitmaps for use in your application.
85
86 @sampledir{artprov}
87
88 @section page_samples_aui Advanced User Interface Sample
89
90 @sampleabout{@ref overview_aui "AUI classes"}
91
92 @sampledir{aui}
93
94 @section page_samples_calendar Calendar Sample
95
96 This sample shows the calendar control in action. It
97 shows how to configure the control (see the different options in the calendar
98 menu) and also how to process the notifications from it.
99
100 @sampledir{calendar}
101
102 @section page_samples_caret Caret Sample
103
104 @sampleabout{wxCaret}
105
106 @sampledir{caret}
107
108 @section page_samples_collpane Collapsible Pane Sample
109
110 @sampleabout{wxCollapsiblePane}
111
112 @sampledir{collpane}
113
114 @section page_samples_combo Combo Sample
115
116 @sampleabout{wxComboBox\, wxComboCtrl and wxOwnerDrawnComboBox etc}
117
118 @sampledir{combo}
119
120 @section page_samples_config Configuration Sample
121
122 This sample demonstrates the wxConfig classes in a platform
123 independent way, i.e. it uses text based files to store a given configuration under
124 Unix and uses the Registry under Windows.
125
126 See @ref overview_config for the descriptions of all features of this class.
127
128 @sampledir{config}
129
130 @section page_samples_console Console Program Sample
131
132 @sampleabout{a console program}
133
134 @sampledir{console}
135
136 @section page_samples_controls Controls Sample
137
138 The controls sample is the main test program for most simple controls used in
139 wxWidgets. The sample tests their basic functionality, events, placement,
140 modification in terms of colour and font as well as the possibility to change
141 the controls programmatically, such as adding an item to a list box etc. Apart
142 from that, the sample uses a wxNotebook and tests most
143 features of this special control (using bitmap in the tabs, using
144 wxSizer instances and wxLayoutConstraints within notebook pages, advancing pages
145 programmatically and vetoing a page change by intercepting the wxNotebookEvent.
146
147 The various controls tested are listed here:
148
149 @li wxButton
150 @li wxBitmapButton
151 @li wxCheckBox
152 @li wxChoice
153 @li wxComboBox
154 @li wxGauge
155 @li wxStaticBox
156 @li wxListBox
157 @li wxSpinCtrl
158 @li wxSpinButton
159 @li wxStaticText
160 @li wxStaticBitmap
161 @li wxRadioBox
162 @li wxRadioButton
163 @li wxSlider
164
165 @sampledir{controls}
166
167 @section page_samples_dataview wxDataViewCtrl Sample
168
169 @sampleabout{wxDataViewCtrl}
170
171 @sampledir{dataview}
172
173 @section page_samples_clipboard Clipboard Sample
174
175 @sampleabout{wxClipboard}
176
177 @sampledir{clipboard}
178
179 @section page_samples_debugrpt Debug Reporter Sample
180
181 This sample shows how to use wxDebugReport class to
182 generate a debug report in case of a program crash or otherwise. On start up,
183 it proposes to either crash itself (by dereferencing a NULL pointer) or
184 generate debug report without doing it. Next it initializes the debug report
185 with standard information adding a custom file to it (just a timestamp) and
186 allows to view the information gathered using
187 wxDebugReportPreview.
188
189 For the report processing part of the sample to work you should make available
190 a Web server accepting form uploads, otherwise
191 wxDebugReportUpload will report an error.
192
193 @buildwith{wxUSE_DEBUGREPORT, wxUSE_ON_FATAL_EXCEPTION}
194
195 @sampledir{debugrpt}
196
197 @section page_samples_dialogs Dialogs Sample
198
199 This sample shows how to use the common dialogs available from wxWidgets. These
200 dialogs are described in detail in the @ref overview_cmndlg.
201
202 In addition to the dialogs accessible from the sample menus, you can also run
203 it with a <code>--progress=style</code> command line option to show a
204 wxProgressDialog with the given style (try 0 for the default style) on program
205 startup, before the main window is shown.
206
207 @sampledir{dialogs}
208
209 @section page_samples_dialup Dialup Sample
210
211 This sample shows the wxDialUpManager
212 class. In the status bar, it displays the information gathered through its
213 interface: in particular, the current connection status (online or offline) and
214 whether the connection is permanent (in which case a string `LAN' appears in
215 the third status bar field - but note that you may be on a LAN not
216 connected to the Internet, in which case you will not see this) or not.
217
218 Using the menu entries, you may also dial or hang up the line if you have a
219 modem attached and (this only makes sense for Windows) list the available
220 connections.
221
222 @sampledir{dialup}
223
224 @section page_samples_display Display Sample
225
226 @sampleabout{wxDisplay}
227
228 @sampledir{display}
229
230 @section page_samples_dnd Drag & Drop Sample
231
232 This sample shows both clipboard and drag and drop in action. It is quite non
233 trivial and may be safely used as a basis for implementing the clipboard and
234 drag and drop operations in a real-life program.
235
236 When you run the sample, its screen is split in several parts. On the top,
237 there are two listboxes which show the standard derivations of
238 wxDropTarget:
239 wxTextDropTarget and
240 wxFileDropTarget.
241
242 The middle of the sample window is taken by the log window which shows what is
243 going on (of course, this only works in debug builds) and may be helpful to see
244 the sequence of steps of data transfer.
245
246 Finally, the last part is used for dragging text from it to either one of the
247 listboxes (only one will accept it) or another application. The last
248 functionality available from the main frame is to paste a bitmap from the
249 clipboard (or, in the case of the Windows version, also a metafile) - it will be
250 shown in a new frame.
251
252 So far, everything we mentioned was implemented with minimal amount of code
253 using standard wxWidgets classes. The more advanced features are demonstrated
254 if you create a shape frame from the main frame menu. A shape is a geometric
255 object which has a position, size and color. It models some
256 application-specific data in this sample. A shape object supports its own
257 private wxDataFormat which means that you may cut and
258 paste it or drag and drop (between one and the same or different shapes) from
259 one sample instance to another (or the same). However, chances are that no
260 other program supports this format and so shapes can also be rendered as
261 bitmaps which allows them to be pasted/dropped in many other applications
262 (and, under Windows, also as metafiles which are supported by most of Windows
263 programs as well - try Write/Wordpad, for example).
264
265 Take a look at DnDShapeDataObject class to see how you may use
266 wxDataObject to achieve this.
267
268 @sampledir{dnd}
269
270 @section page_samples_docview Document/View Sample
271
272 @sampleabout{@ref overview_docview}
273
274 @sampledir{docview}
275
276 @see @sample{mdi}
277
278 @section page_samples_dragimag Drag Image Sample
279
280 @sampleabout{wxDragImage}
281
282 @sampledir{dragimag}
283
284 @section page_samples_drawing Drawing Sample
285
286 @sampleabout{the drawing ability of wxDC}
287
288 @sampledir{drawing}
289
290 @section page_samples_erase Erase Event Sample
291
292 @sampleabout{wxEraseEvent}
293
294 @sampledir{erase}
295
296 @section page_samples_event Event Sample
297
298 This sample demonstrates various features of the wxWidgets events. It
299 shows how to dynamic events and connecting/disconnecting the event handlers
300 during run time by using wxEvtHandler::Connect() and wxEvtHandler::Disconnect(),
301 and also how to use wxWindow::PushEventHandler() and wxWindow::PopEventHandler().
302
303 @sampledir{event}
304
305 @section page_samples_except Exception Sample
306
307 This very simple sample shows how to use C++ exceptions in wxWidgets programs,
308 i.e. where to catch the exception which may be thrown by the program code. It
309 doesn't do anything very exciting by itself, you need to study its code to
310 understand what goes on.
311
312 <b>Build Note:</b>
313 You need to build the library with @c wxUSE_EXCEPTIONS being set to @c 1
314 and compile your code with C++ exceptions support to be able to build this
315 sample.
316
317 @sampledir{except}
318
319 @section page_samples_exec External Program Execution Sample
320
321 The exec sample demonstrates the wxExecute and
322 wxShell functions. Both of them are used to execute the
323 external programs and the sample shows how to do this synchronously (waiting
324 until the program terminates) or asynchronously (notification will come later).
325
326 It also shows how to capture the output of the child process in both
327 synchronous and asynchronous cases and how to kill the processes with
328 wxProcess::Kill() and test for their existence with
329 wxProcess::Exists().
330
331 @sampledir{exec}
332
333 @section page_samples_flash Flash Sample
334
335 The flash sample demonstrates embedding of Adobe Flash into a wxWidgets
336 program. Currently it only works under Windows as it uses the Flash ActiveX
337 control to achieve this but we hope to be able to extend it to also work under
338 other platforms in the future. The sample also currently requires Microsoft
339 Visual C++ compiler as it uses COM support extensions specific to this
340 compiler.
341
342 The sample comes with 2 Flash files (SWF), showing a simple Flash animation
343 which can be controlled using the "Play", "Stop" and "Back"/"Forward" buttons
344 in the sample as well as a Flash form which shows how Flash and wxWidgets
345 program can exchange data: calling "GetText" function without arguments returns
346 the text of the text control defined inside Flash and calling "SetText" with an
347 argument sets the control contents to the given string. Finally clicking on the
348 button generates an event which is caught by the C++ program.
349
350 @section page_samples_font Font Sample
351
352 The font sample demonstrates wxFont,
353 wxFontEnumerator and
354 wxFontMapper classes. It allows you to see the fonts
355 available (to wxWidgets) on the computer and shows all characters of the
356 chosen font as well.
357
358 @sampledir{font}
359
360 @section page_samples_grid Grid Sample
361
362 @sampleabout{wxGrid}
363
364 @sampledir{grid}
365
366 @section page_samples_help Help Sample
367
368 @sampleabout{wxHelpController}
369
370 @sampledir{help}
371
372 @section page_samples_html HTML Sample
373
374 Eight HTML samples cover all features of the HTML sub-library.
375
376 @li @b Test demonstrates how to create wxHtmlWindow
377 and also shows most supported HTML tags.
378
379 @li @b Widget shows how you can embed ordinary controls or windows within an
380 HTML page. It also nicely explains how to write new tag handlers and extend
381 the library to work with unsupported tags.
382
383 @li @b About may give you an idea how to write good-looking About boxes.
384
385 @li @b Zip demonstrates use of virtual file systems in wxHTML. The zip archives
386 handler (ships with wxWidgets) allows you to access HTML pages stored
387 in a compressed archive as if they were ordinary files.
388
389 @li @b Virtual is yet another virtual file systems demo. This one generates pages at run-time.
390 You may find it useful if you need to display some reports in your application.
391
392 @li @b Printing explains use of wxHtmlEasyPrinting
393 class which serves as as-simple-as-possible interface for printing HTML
394 documents without much work. In fact, only few function calls are sufficient.
395
396 @li @b Help and @b Helpview are variations on displaying HTML help
397 (compatible with MS HTML Help Workshop). @e Help shows how to embed
398 wxHtmlHelpController in your application
399 while @e Helpview is a simple tool that only pops up the help window and
400 displays help books given at command line.
401
402 @sampledir{html}
403
404 @section page_samples_htlbox HTML List Box Sample
405
406 @sampleabout{wxHtmlListBox}
407
408 @sampledir{htlbox}
409
410 @section page_samples_image Image Sample
411
412 The image sample demonstrates use of the wxImage class
413 and shows how to download images in a variety of formats, currently PNG, GIF,
414 TIFF, JPEG, BMP, PNM and PCX. The top of the sample shows two rectangles, one
415 of which is drawn directly in the window, the other one is drawn into a
416 wxBitmap, converted to a wxImage, saved as a PNG image
417 and then reloaded from the PNG file again so that conversions between wxImage
418 and wxBitmap as well as loading and saving PNG files are tested.
419
420 At the bottom of the main frame there is a test for using a monochrome bitmap by
421 drawing into a wxMemoryDC. The bitmap is then drawn
422 specifying the foreground and background colours with
423 wxDC::SetTextForeground() and
424 wxDC::SetTextBackground() (on the left). The
425 bitmap is then converted to a wxImage and the foreground colour (black) is
426 replaced with red using wxImage::Replace().
427
428 This sample also contains the code for testing the image rotation and resizing
429 and using raw bitmap access, see the corresponding menu commands.
430
431 @sampledir{image}
432
433 @section page_samples_internat Internationalization Sample
434
435 The not very clearly named internat sample demonstrates the wxWidgets
436 internationalization (i18n for short from now on) features. To be more
437 precise, it only shows localization support, i.e. support for translating the
438 program messages into another language while true i18n would also involve
439 changing the other aspects of the program's behaviour.
440
441 More information about this sample can be found in the @c readme.txt file in
442 its directory. Please also see the @ref overview_i18n overview.
443
444 @sampledir{internat}
445
446 @section page_samples_ipc Connection Sample
447
448 @sampleabout{wxConnection}
449
450 @sampledir{ipc}
451
452 @section page_samples_joytest Joystick Sample
453
454 @sampleabout{wxJoystick}
455
456 @sampledir{joytest}
457
458 @section page_samples_keyboard Key Event Sample
459
460 @sampleabout{wxKeyEvent}
461
462 This sample can be used to interactively test the events produced by pressing
463 various keyboard keys. It also shows the interaction between accelerators and
464 the normal keyboard events (which are overridden by any defined accelerators)
465 and finally allows to test that not skipping an event in EVT_KEY_DOWN handler
466 suppresses the subsequent EVT_CHAR event.
467
468 @sampledir{keyboard}
469
470 @section page_samples_layout Layout Sample
471
472 The layout sample demonstrates the two different layout systems offered
473 by wxWidgets. When starting the program, you will see a frame with some
474 controls and some graphics. The controls will change their size whenever
475 you resize the entire frame and the exact behaviour of the size changes
476 is determined using the wxLayoutConstraints
477 class. See also the overview and the
478 wxIndividualLayoutConstraint
479 class for further information.
480
481 The menu in this sample offers two more tests, one showing how to use
482 a wxBoxSizer in a simple dialog and the other one
483 showing how to use sizers in connection with a wxNotebook
484 class. See also wxSizer.
485
486 @sampledir{layout}
487
488 @section page_samples_listctrl List Control Sample
489
490 This sample shows the wxListCtrl control. Different modes
491 supported by the control (list, icons, small icons, report) may be chosen from
492 the menu.
493
494 The sample also provides some timings for adding/deleting/sorting a lot of
495 (several thousands) items into the control.
496
497 @sampledir{listctrl}
498
499 @section page_samples_mdi MDI Sample
500
501 @sampleabout{MDI}
502
503 @see @sample{docview}
504
505 @sampledir{mdi}
506
507 @section page_samples_mediaplayer Mediaplayer Sample
508
509 This sample demonstrates how to use all the features of
510 wxMediaCtrl and play various types of sound, video,
511 and other files.
512
513 It replaces the old @c dynamic sample.
514
515 @sampledir{mediaplayer}
516
517 @section page_samples_memcheck Memory Checking Sample
518
519 @sampleabout{memory tracing using wxDebugContext}
520
521 @sampledir{memcheck}
522
523 @buildwith{wxUSE_MEMORY_TRACING, wxUSE_DEBUG_CONTEXT}
524
525 @section page_samples_menu Menu Sample
526
527 @sampleabout{wxMenu classes}
528
529 @sampledir{menu}
530
531 @section page_samples_mfc MFC Sample
532
533 @sampleabout{how to mix MFC and wxWidgets code}
534 It pops up an initial wxWidgets frame, with a menu item
535 that allows a new MFC window to be created.
536
537 For build instructions please read IMPORTANT NOTES in @c mfctest.cpp.
538
539 @onlyfor{wxmsw}
540
541 @sampledir{mfc}
542
543 @section page_samples_minimal Minimal Sample
544
545 The minimal sample is what most people will know under the term Hello World,
546 i.e. a minimal program that doesn't demonstrate anything apart from what is
547 needed to write a program that will display a "hello" dialog. This is usually
548 a good starting point for learning how to use wxWidgets.
549
550 @sampledir{minimal}
551
552 @section page_samples_nativdlg Native Windows Dialog Sample
553
554 @sampleabout{native windows dialog}
555
556 @onlyfor{wxmsw}
557
558 @sampledir{nativdlg}
559
560 @section page_samples_notebook Notebook Sample
561
562 This samples shows wxBookCtrl family of controls.
563 Although initially it was written to demonstrate wxNotebook
564 only, it can now be also used to see wxListbook,
565 wxChoicebook, wxTreebook and wxToolbook in action.
566 Test each of the controls, their orientation, images and pages using
567 commands through the menu.
568
569 @sampledir{notebook}
570
571 @section page_samples_oleauto OLE Automation Sample
572
573 @sampleabout{OLE automation using wxAutomationObject}
574
575 @onlyfor{wxmsw}
576
577 @sampledir{oleauto}
578
579 @section page_samples_opengl OpenGL Sample
580
581 @sampleabout{wxGLCanvas}
582
583 @li @b cube Draws a cube to demonstrate how to write a basic wxWidgets OpenGL program.
584 Arrow keys rotate the cube. Space bar toggles spinning.
585 @li @b isosurf Draws a surface by reading coordinates from a DAT file.
586 @li @b penguin Draws a rotatable penguin by reading data from a DXF file.
587
588 @sampledir{opengl}
589
590 @section page_samples_ownerdrw Owner-drawn Sample
591
592 @sampleabout{owner-drawn wxMenuItem\, wxCheckList and wxListBox}
593
594 <!--It's weird that it doesn't need <wx/ownerdrw.h> and class wxOwnerDrawn!-->
595
596 @sampledir{ownerdrw}
597
598 @section page_samples_popup Popup Transient Window Sample
599
600 @sampleabout{wxPopupTransientWindow}
601
602 @sampledir{popup}
603
604 @section page_samples_power Power Management Sample
605
606 @sampleabout{wxWidgets power management}
607
608 @see wxPowerEvent
609
610 @sampledir{power}
611
612 @section page_samples_printing Printing Sample
613
614 @sampleabout{printing}
615
616 @see @ref overview_printing, @ref overview_unixprinting
617
618 @buildwith{wxUSE_PRINTING_ARCHITECTURE}
619
620 @sampledir{printing}
621
622 @section page_samples_propgrid wxPropertyGrid Sample
623
624 Sample application has following additional examples of custom properties:
625 - wxFontDataProperty ( edits wxFontData )
626 - wxPointProperty ( edits wxPoint )
627 - wxSizeProperty ( edits wxSize )
628 - wxAdvImageFileProperty ( like wxImageFileProperty, but also has a drop-down
629 for recent image selection )
630 - wxDirsProperty ( edits a wxArrayString consisting of directory strings)
631 - wxArrayDoubleProperty ( edits wxArrayDouble )
632
633 @sampleabout{wxPropertyGrid}
634
635 @sampledir{propgrid}
636
637 @section page_samples_regtest Registry Sample
638
639 @sampleabout{wxRegKey}
640
641 <!--Its directory name doesn't seem to be proper.-->
642
643 @onlyfor{wxmsw}
644
645 @sampledir{regtest}
646
647 @section page_samples_render Render Sample
648
649 This sample shows how to replace the default wxWidgets
650 renderer and also how to write a shared library
651 (DLL) implementing a renderer and load and unload it during the run-time.
652
653 @sampledir{render}
654
655 @section page_samples_richtext wxRichTextCtrl Sample
656
657 @sampleabout{wxRichTextCtrl}
658
659 @sampledir{richtext}
660
661 @section page_samples_sashtest Sash Sample
662
663 @sampleabout{wxSashWindow classes}
664
665 @sampledir{sashtest}
666
667 @section page_samples_scroll Scroll Window Sample
668
669 @sampleabout{wxScrolledWindow}
670
671 This sample demonstrates use of the ::wxScrolledWindow
672 class including placing subwindows into it and drawing simple graphics. It uses
673 the SetTargetWindow method and thus the effect of scrolling does not show in
674 the scrolled window itself, but in one of its subwindows.
675
676 Additionally, this samples demonstrates how to optimize drawing operations in
677 wxWidgets, in particular using the wxWindow::IsExposed() method with the aim to
678 prevent unnecessary drawing in the window and thus reducing or removing flicker
679 on screen.
680
681 @sampledir{scroll}
682
683 @section page_samples_shaped Shaped Window Sample
684
685 @sampleabout{how to implement a shaped or transparent window\, and a window showing/hiding with effect}
686
687 @see wxTopLevelWindow::SetShape(), wxTopLevelWindow::SetTransparent(),
688 wxWindow::ShowWithEffect(), wxWindow::HideWithEffect()
689
690 @sampledir{shaped}
691
692 @section page_samples_sockets Sockets Sample
693
694 The sockets sample demonstrates how to use the communication facilities
695 provided by wxSocket. There are two different
696 applications in this sample: a server, which is implemented using a
697 wxSocketServer object, and a client, which
698 is implemented as a wxSocketClient.
699
700 The server binds to the local address, using TCP port number 3000,
701 sets up an event handler to be notified of incoming connection requests
702 (@b wxSOCKET_CONNECTION events), and sits there, waiting for clients
703 (@e listening, in socket parlance). For each accepted connection,
704 a new wxSocketBase object is created. These
705 socket objects are independent from the server that created them, so
706 they set up their own event handler, and then request to be notified
707 of @b wxSOCKET_INPUT (incoming data) or @b wxSOCKET_LOST
708 (connection closed at the remote end) events. In the sample, the event
709 handler is the same for all connections; to find out which socket the
710 event is addressed to, the GetSocket function
711 is used.
712
713 Although it might take some time to get used to the event-oriented
714 system upon which wxSocket is built, the benefits are many. See, for
715 example, that the server application, while being single-threaded
716 (and of course without using fork() or ugly select() loops) can handle
717 an arbitrary number of connections.
718
719 The client starts up unconnected, so you can use the Connect... option
720 to specify the address of the server you are going to connect to (the
721 TCP port number is hard-coded as 3000). Once connected, a number of
722 tests are possible. Currently, three tests are implemented. They show
723 how to use the basic IO calls in wxSocketBase,
724 such as wxSocketBase::Read(), wxSocketBase::Write(),
725 wxSocketBase::ReadMsg() and wxSocketBase::WriteMsg(),
726 and how to set up the correct IO flags depending on what you are going to
727 do. See the comments in the code for more information. Note that because
728 both clients and connection objects in the server set up an event handler
729 to catch @b wxSOCKET_LOST events, each one is immediately notified
730 if the other end closes the connection.
731
732 There is also a URL test which shows how to use
733 the wxURL class to fetch data from a given URL.
734
735 The sockets sample is work in progress. Some things to do:
736
737 @li More tests for basic socket functionality.
738 @li More tests for protocol classes (wxProtocol and its descendants).
739 @li Tests for the recently added (and still in alpha stage) datagram sockets.
740 @li New samples which actually do something useful (suggestions accepted).
741
742 @sampledir{sockets}
743
744 @section page_samples_sound Sound Sample
745
746 The @c sound sample shows how to use wxSound for simple
747 audio output (e.g. notifications).
748
749 @sampledir{sound}
750
751 @section page_samples_splash Splash Screen Sample
752
753 @sampleabout{wxSplashScreen}
754
755 @sampledir{splash}
756
757 @section page_samples_splitter Splitter Window Sample
758
759 @sampleabout{wxSplitterWindow}
760
761 @sampledir{splitter}
762
763 @section page_samples_statbar Status Bar Sample
764
765 This sample shows how to create and use wxStatusBar. Although most of the
766 samples have a statusbar, they usually only create a default one and only
767 do it once.
768
769 Here you can see how to recreate the statusbar (with possibly different number
770 of fields) and how to use it to show icons/bitmaps and/or put arbitrary
771 controls into it.
772
773 @sampledir{statbar}
774
775 @section page_samples_stc wxStyledTextCtrl Sample
776
777 @sampleabout{wxStyledTextCtrl}
778
779 @sampledir{stc}
780
781 @section page_samples_svg SVG Sample
782
783 @sampleabout{wxSVGFileDC}
784
785 @sampledir{svg}
786
787 @section page_samples_taborder Tab Order Sample
788
789 This sample allows to test keyboard navigation (mostly done using the
790 @c TAB key, hence the sample name) between different controls.
791 It shows the use of wxWindow::MoveBeforeInTabOrder() and
792 MoveAfterInTabOrder() methods to change
793 the default order of the windows in the navigation chain and of
794 wxWindow::Navigate() for moving focus along this
795 chain.
796
797 @sampledir{taborder}
798
799 @section page_samples_taskbar Task Bar Icon Sample
800
801 @sampleabout{wxTaskBarIcon}
802
803 @sampledir{taskbar}
804
805 @section page_samples_text Text Sample
806
807 This sample demonstrates four features: firstly the use and many variants of
808 the wxTextCtrl class (single line, multi line, read only,
809 password, ignoring TAB, ignoring ENTER).
810
811 Secondly it shows how to intercept a wxKeyEvent in both
812 the raw form using the @c EVT_KEY_UP and @c EVT_KEY_DOWN macros and the
813 higher level from using the @c EVT_CHAR macro. All characters will be logged
814 in a log window at the bottom of the main window. By pressing some of the function
815 keys, you can test some actions in the text ctrl as well as get statistics on the
816 text ctrls, which is useful for testing if these statistics actually are correct.
817
818 Thirdly, on platforms which support it, the sample will offer to copy text to the
819 wxClipboard and to paste text from it. The GTK version will
820 use the so called PRIMARY SELECTION, which is the pseudo clipboard under X and
821 best known from pasting text to the XTerm program.
822
823 Last but not least: some of the text controls have tooltips and the sample also
824 shows how tooltips can be centrally disabled and their latency controlled.
825
826 @sampledir{text}
827
828 @section page_samples_thread Thread Sample
829
830 This sample demonstrates use of threads in connection with GUI programs.
831
832 There are two fundamentally different ways to use threads in GUI programs and
833 either way has to take care of the fact that the GUI library itself usually
834 is not multi-threading safe, i.e. that it might crash if two threads try to
835 access the GUI class simultaneously.
836
837 One way to prevent that is have a normal GUI program in the main thread and some
838 worker threads which work in the background. In order to make communication between
839 the main thread and the worker threads possible, wxWidgets offers the ::wxQueueEvent
840 function and this sample demonstrates its usage.
841
842 The other way is to use a ::wxMutexGuiEnter and ::wxMutexGuiLeave functions, but
843 this is not currently shown in the sample.
844
845 See also @ref overview_thread and wxThread.
846
847 @sampledir{thread}
848
849 @section page_samples_toolbar Tool Bar Sample
850
851 The toolbar sample shows the wxToolBar class in action.
852
853 The following things are demonstrated:
854
855 @li Creating the toolbar using wxToolBar::AddTool() and wxToolBar::AddControl(): see
856 MyApp::InitToolbar() in the sample.
857 @li Using @c EVT_UPDATE_UI handler for automatically enabling/disabling
858 toolbar buttons without having to explicitly call EnableTool. This is done
859 in MyFrame::OnUpdateCopyAndCut().
860 @li Using wxToolBar::DeleteTool() and wxToolBar::InsertTool() to dynamically update the
861 toolbar.
862
863 Some buttons in the main toolbar are check buttons, i.e. they stay checked when
864 pressed. On the platforms which support it, the sample also adds a combobox
865 to the toolbar showing how you can use arbitrary controls and not only buttons
866 in it.
867
868 If you toggle another toolbar in the sample (using @c Ctrl-A) you will also
869 see the radio toolbar buttons in action: the first three buttons form a radio
870 group, i.e. checking any of them automatically unchecks the previously
871 checked one.
872
873 @sampledir{toolbar}
874
875 @section page_samples_treectrl wxTreeCtrl Sample
876
877 This sample demonstrates using the wxTreeCtrl class. Here
878 you may see how to process various notification messages sent by this control
879 and also when they occur (by looking at the messages in the text control in
880 the bottom part of the frame).
881
882 Adding, inserting and deleting items and branches from the tree as well as
883 sorting (in default alphabetical order as well as in custom one) is
884 demonstrated here as well - try the corresponding menu entries.
885
886 @sampledir{treectrl}
887
888 @section page_samples_typetest Types Sample
889
890 @sampleabout{wxWidgets types}
891
892 @todo This sample isn't very didactive; it's more than a set of tests rather
893 than a sample and thus should be rewritten with CppUnit and moved under "tests"
894
895 @sampledir{typetest}
896
897 @section page_samples_uiaction wxUIActionSimulator Sample
898
899 @sampleabout{wxUIActionSimulator}
900
901 This sample shows some features of wxUIActionSimulator class. When a simulation
902 is run using its menu items, you can see that the button is pressed
903 programmatically and the characters generated by the program appear in the text
904 control.
905
906 @sampledir{uiaction}
907
908 @section page_samples_validate Validator Sample
909
910 @sampleabout{wxValidator}
911
912 @sampledir{validate}
913
914 @section page_samples_vscroll VScrolled Window Sample
915
916 @sampleabout{wxVScrolledWindow}
917
918 @sampledir{vscroll}
919
920 @section page_samples_webview wxWebView Sample
921
922 The wxWebView sample demonstarates the various capabilities of the wxWebView
923 control. It is set up as a simple single window web broswer, but with support
924 for many of the more complex wxWebView features, including browsing through
925 archives.
926
927 @sampledir{webview}
928
929 @section page_samples_widgets Widgets Sample
930
931 The widgets sample is the main presentation program for most simple and advanced
932 native controls and complex generic widgets provided by wxWidgets.
933 The sample tests their basic functionality, events, placement, modification
934 in terms of colour and font as well as the possibility to change
935 the controls programmatically, such as adding an item to a list box etc.
936 All widgets are categorized for easy browsing.
937
938 @sampledir{widgets}
939
940 @section page_samples_wizard Wizard Sample
941
942 This sample shows the so-called wizard dialog (implemented using
943 wxWizard and related classes). It shows almost all
944 features supported:
945
946 @li Using bitmaps with the wizard and changing them depending on the page
947 shown (notice that wxValidationPage in the sample has a different image from
948 the other ones)
949 @li Using TransferDataFromWindow
950 to verify that the data entered is correct before passing to the next page
951 (done in wxValidationPage which forces the user to check a checkbox before
952 continuing).
953 @li Using more elaborated techniques to allow returning to the previous
954 page, but not continuing to the next one or vice versa (in wxRadioboxPage)
955 @li This (wxRadioboxPage) page also shows how the page may process the
956 @e Cancel button itself instead of relying on the wizard parent to do it.
957 @li Normally, the order of the pages in the wizard is known at compile-time,
958 but sometimes it depends on the user choices: wxCheckboxPage shows how to
959 dynamically decide which page to display next (see also
960 wxWizardPage)
961
962 @sampledir{wizard}
963
964 @section page_samples_wrapsizer wxWrapSizer Sample
965
966 @sampleabout{wxWrapSizer}
967
968 @sampledir{wrapsizer}
969
970 @section page_samples_xrc XRC Sample
971
972 This sample shows how to use the various features of the @ref overview_xrc to
973 create the gui of your program. It starts by loading and showing a frame and
974 other resources. From its menu or toolbar you can then run the following dialogs:
975
976 @li A non-derived wxDialog
977 @li A derived dialog
978 @li A dialog containing a large number of controls
979 @li An uncentred dialog
980 @li A dialog demonstrating the use of object references and ID ranges
981 @li A dialog that contains a custom class
982 @li A dialog with platform-specific features
983 @li A dialog demonstrating wxArtProvider
984 @li A dialog saying "VARIABLE EXPANSION ISN'T IMPLEMENTED CURRENTLY" :/
985
986 @sampledir{xrc}
987
988 */
989