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