X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b4e87ec32c0870a8dfa377199b2616d8eac9647a..520200fd10b80c1d759311ed345789f5fe048ca5:/docs/latex/wx/tsamples.tex diff --git a/docs/latex/wx/tsamples.tex b/docs/latex/wx/tsamples.tex index dc27d24dfc..588932885d 100644 --- a/docs/latex/wx/tsamples.tex +++ b/docs/latex/wx/tsamples.tex @@ -6,7 +6,7 @@ %% Created: 02.11.99 %% RCS-ID: $Id$ %% Copyright: (c) wxWindows team -%% Licence: wxWindows licence +%% License: wxWindows license %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % NB: please keep the subsections in alphabetic order! @@ -51,6 +51,13 @@ 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 wxWindows. +\subsection{Art provider sample}\label{sampleartprovider} + +The {\tt artprov} sample shows how you can customize the look of standard +wxWindows 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{Calendar sample}\label{samplecalendar} This font shows the \helpref{calendar control}{wxcalendarctrl} in action. It @@ -61,8 +68,8 @@ menu) and also how to process the notifications from it. This sample demonstrates the use of the \helpref{wxCheckListBox}{wxchecklistbox} class intercepting check, select and double click events. It also tests the -use of various methods modifiying the control, such as by deleting items -from it or inserting new once (these fucntions are actually implememted in +use of various methods modifying the control, such as by deleting items +from it or inserting new once (these functions are actually implemented in the parent class \helpref{wxListBox}{wxlistbox} so the sample tests that class as well). The layout of the dialog is created using a \helpref{wxBoxSizer}{wxboxsizer} demonstrating a simple dynamic layout. @@ -70,7 +77,7 @@ demonstrating a simple dynamic layout. \subsection{Config sample}\label{sampleconfig} This sample demonstrates the \helpref{wxConfig}{wxconfigbase} classes in a platform -indepedent way, i.e. it uses text based files to store a given configuration under +independent way, i.e. it uses text based files to store a given configuration under Unix and uses the Registry under Windows. See \helpref{wxConfig overview}{wxconfigoverview} for the descriptions of all @@ -83,9 +90,9 @@ wxWindows. 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 item to a list box etc. Apart from that, the sample uses a \helpref{wxNotebook}{wxnotebook} and tests most -fetaures of this special control (using bitmap in the tabs, using +features of this special control (using bitmap in the tabs, using \helpref{wxSizers}{wxsizer} and \helpref{constraints}{wxlayoutconstraints} within -notebook pages, advanving pages programmatically and vetoing a page change +notebook pages, advancing pages programmatically and vetoing a page change by intercepting the \helpref{wxNotebookEvent}{wxnotebookevent}. The various controls tested are listed here: @@ -111,60 +118,26 @@ The various controls tested are listed here: \subsection{Database sample}\label{sampledb} The database sample is a small test program showing how to use the ODBC -classes written by Remstar Intl. These classes are documented in a separate -manual available from the wxWindows homepage. Obviously, this sample -requires a database with ODBC support to be correctly installed on your -system. +classes written by Remstar Intl. Obviously, this sample requires a +database with ODBC support to be correctly installed on your system. \subsection{Dialogs sample}\label{sampledialogs} This sample shows how to use the common dialogs available from wxWindows. These -dialogs are desrcibed in details in the \helpref{Common dialogs overview}{commondialogsoverview}. +dialogs are described in details in the \helpref{Common dialogs overview}{commondialogsoverview}. -\subsection{Dynamic sample}\label{sampledynamic} +\subsection{Dialup sample}\label{sampledialup} -This sample is a very small sample that demonstrates the use of the -\helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. This method -should be used whenever it is not known at compile time, which control -will receive which event or which controls are actually going to be in -a dialog or frame. This is most typically the case for any scripting -languge that would work as a wrapper for wxWindows or programs where -forms or similar datagrams can be created by the uses. - -\subsection{Exec sample}\label{sampleexec} +This sample shows \helpref{wxDialUpManager}{wxdialupmanager} +class. It displays in the status bar 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 have be on a LAN not +connected to the Internet, in which case you will not see this) or not. -The exec sample demonstrates the \helpref{wxExecute}{wxexecute} and -\helpref{wxShell}{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). - -\subsection{Scroll subwindow sample}\label{samplescrollsub} - -This sample demonstrates the use of the \helpref{wxScrolledWindow}{wxscrolledwindow} -class including placing subwindows into it and drawing simple graphics. It uses the -\helpref{SetTargetWindow}{wxscrolledwindowsettargetwindow} 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 wxWindows, -in particular using the \helpref{wxWindow::IsExposed}{wxwindowisexposed} method with -the aim to prevent unnecessary drawing in the window and thus reducing or removing -flicker on screen. - -\subsection{Rotate sample}\label{samplerotate} - -This is a simple example which demonstrates how to rotate an image with -the \helpref{wxImage::Rotate}{wximagerotate} method. The rotation can -be done without interpolation (left mouse button) which will be faster, -or with interpolation (right mouse button) which is slower but gives -better results. - -\subsection{Font sample}\label{samplefont} - -The font sample demonstrates \helpref{wxFont}{wxfont}, -\helpref{wxFontEnumerator}{wxfontenumerator} and -\helpref{wxFontMapper}{wxfontmapper} classes. It allows you to see the fonts -available (to wxWindows) on the computer and shows all characters of the -chosen font as well. +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{DnD sample}\label{samplednd} @@ -204,6 +177,48 @@ programs as well - try Write/Wordpad, for example). Take a look at DnDShapeDataObject class to see how you may use \helpref{wxDataObject}{wxdataobject} to achieve this. +\subsection{Dynamic sample}\label{sampledynamic} + +This sample is a very small sample that demonstrates the use of the +\helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. This method +should be used whenever it is not known at compile time, which control +will receive which event or which controls are actually going to be in +a dialog or frame. This is most typically the case for any scripting +language that would work as a wrapper for wxWindows or programs where +forms or similar datagrams can be created by the uses. + +See also the \helpref{event sample}{sampleevent} + +\subsection{Event sample}\label{sampleevent} + +The event sample demonstrates various features of the wxWindows events. It +shows using dynamic events and connecting/disconnecting the event handlers +during the run time and also using +\helpref{PushEventHandler()}{wxwindowpusheventhandler} and +\helpref{PopEventHandler()}{wxwindowpopeventhandler}. + +It replaces the old dynamic sample. + +\subsection{Exec sample}\label{sampleexec} + +The exec sample demonstrates the \helpref{wxExecute}{wxexecute} and +\helpref{wxShell}{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 +\helpref{wxProcess::Kill}{wxprocesskill} and test for their existence with +\helpref{wxProcess::Exists}{wxprocessexists}. + +\subsection{Font sample}\label{samplefont} + +The font sample demonstrates \helpref{wxFont}{wxfont}, +\helpref{wxFontEnumerator}{wxfontenumerator} and +\helpref{wxFontMapper}{wxfontmapper} classes. It allows you to see the fonts +available (to wxWindows) on the computer and shows all characters of the +chosen font as well. + \subsection{Grid sample}\label{samplegrid} TODO. @@ -213,7 +228,7 @@ TODO. Eight HTML samples (you can find them in directory {\tt samples/html}) cover all features of HTML sub-library. -{\bf Test} demonstrates how to create \helpref{wxHtmlWindow}{wxhtmlwindow} +{\bf Test} demonstrates how to create \helpref{wxHtmlWindow}{wxhtmlwindow} and also shows most of supported HTML tags. {\bf Widget} shows how you can embed ordinary controls or windows within @@ -226,15 +241,15 @@ the library to work with unsupported tags. handler (ships with wxWindows) allows you to access HTML pages stored in compressed archive as if they were ordinary files. -{\bf Virtual} is yet another VFS demo. This one generates pages at run-time. +{\bf 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. -{\bf Printing} explains use of \helpref{wxHtmlEasyPrinting}{wxhtmleasyprinting} +{\bf Printing} explains use of \helpref{wxHtmlEasyPrinting}{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. {\bf Help} and {\bf Helpview} are variations on displaying HTML help -(compatible with MS HTML Help Workshop). {\it Help} shows how to embed +(compatible with MS HTML Help Workshop). {\it Help} shows how to embed \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller} in your application while {\it Helpview} is simple tool that only pops up help window and displays help books given at command line. @@ -244,7 +259,7 @@ displays help books given at command line. The image sample demonstrates the use of the \helpref{wxImage}{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 to rectangles, one -of which is drawn directly in the window, the other one is drawn into a +of which is drawn directly in the window, the other one is drawn into a \helpref{wxBitmap}{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 save PNG files are tested. @@ -257,20 +272,31 @@ specifying the foreground and background colours with bitmap is then converted to a wxImage and the foreground colour (black) is replaced with red using \helpref{wxImage::Replace}{wximagereplace}. +\subsection{Internat(ionalization) sample}\label{sampleinternat} + +The not very clearly named internat sample demonstrates the wxWindows +internatationalization (i18n for short from now on) features. To be more +precise, it only shows localization support, i.e. support for translating the +program messages in 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 {\tt readme.txt} file in +its directory. Please see also \helpref{i18n overview}{internationalization}. + \subsection{Layout sample}\label{samplelayout} The layout sample demonstrates the two different layout systems offered by wxWindows. 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 \helpref{wxLayoutConstraints}{wxlayoutconstraints} -class. See also the \helpref{overview}{constraintsoverview} and the -\helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint} +is determined using the \helpref{wxLayoutConstraints}{wxlayoutconstraints} +class. See also the \helpref{overview}{constraintsoverview} and the +\helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint} class for further information. The menu in this sample offers two more tests, one showing how to use a \helpref{wxBoxSizer}{wxboxsizer} in a simple dialog and the other one -showing how to use sizers in connection with a \helpref{wxNotebook}{wxnotebook} +showing how to use sizers in connection with a \helpref{wxNotebook}{wxnotebook} class. See also \helpref{wxNotebookSizer}{wxnotebooksizer} and \helpref{wxSizer}{wxsizer}. @@ -283,26 +309,46 @@ the menu. The sample also provides some timings for adding/deleting/sorting a lot of (several thousands) controls into the control. +\subsection{Rotate sample}\label{samplerotate} + +This is a simple example which demonstrates how to rotate an image with +the \helpref{wxImage::Rotate}{wximagerotate} method. The rotation can +be done without interpolation (left mouse button) which will be faster, +or with interpolation (right mouse button) which is slower but gives +better results. + +\subsection{Scroll subwindow sample}\label{samplescrollsub} + +This sample demonstrates the use of the \helpref{wxScrolledWindow}{wxscrolledwindow} +class including placing subwindows into it and drawing simple graphics. It uses the +\helpref{SetTargetWindow}{wxscrolledwindowsettargetwindow} 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 wxWindows, +in particular using the \helpref{wxWindow::IsExposed}{wxwindowisexposed} method with +the aim to prevent unnecessary drawing in the window and thus reducing or removing +flicker on screen. + \subsection{Sockets sample}\label{samplesockets} The sockets sample demonstrates how to use the communication facilities provided by \helpref{wxSocket}{wxsocketbase}. There are two different -applications in this sample: a server, which is implemented as a -\helpref{wxSocketServer}{wxsocketserver} object, and a client, which is -implemented with \helpref{wxSocketClient}{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 -({\bf wxSOCKET\_CONNECTION} event), and stands there, waiting (listening -in the socket parlance) for clients. For each incoming client, a new -\helpref{wxSocketBase}{wxsocketbase} object is created, which represents -the connection. Connections are independent from the server that created -them, so they set up their own event handler, and stay awaiting for -{\bf wxSOCKET\_INPUT} (incoming data) or {\bf wxSOCKET\_LOST} (connection -closed at the remote end) events. This event handler is the same for all -connections, and demonstrates how to determine which socket the event -is addressed to by using the \helpref{Socket}{wxsocketeventsocket} function -in the \helpref{wxSocketEvent}{wxsocketevent} class. +applications in this sample: a server, which is implemented using a +\helpref{wxSocketServer}{wxsocketserver} object, and a client, which +is implemented as a \helpref{wxSocketClient}{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 +({\bf wxSOCKET\_CONNECTION} events), and stands there, waiting for clients +({\it listening} in the socket parlance). For each accepted connection, +a new \helpref{wxSocketBase}{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 {\bf wxSOCKET\_INPUT} (incoming data) or {\bf 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 \helpref{GetSocket}{wxsocketeventgetsocket} 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 @@ -315,24 +361,23 @@ 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 \helpref{wxSocketBase}{wxsocketbase}, -such as \helpref{Read}{wxsocketbaseread}, \helpref{Write}{wxsocketbasewrite}, +such as \helpref{Read}{wxsocketbaseread}, \helpref{Write}{wxsocketbasewrite}, \helpref{ReadMsg}{wxsocketbasereadmsg} and \helpref{WriteMsg}{wxsocketbasewritemsg}, 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 (a lengthy explanation -on socket flags is available in \helpref{SetFlags}{wxsocketbasesetflags}). -Note that because both clients and connection objects in the server set -up an event handler to catch {\bf wxSOCKET\_LOST} events, each one is -immediately notified if the other end closes the connection. +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 {\bf wxSOCKET\_LOST} events, each one is immediately notified +if the other end closes the connection. -There is also an URL test which demonstrates how to use the \helpref{wxURL}{wxurl} -class. +There is also an URL test which shows how to use +the \helpref{wxURL}{wxurl} class to fetch data from a given URL. -The sockets sample is work in progress. Coming soon: +The sockets sample is work in progress. Some things to do: \begin{itemize}\itemsep=0pt \item More tests for basic socket functionality. \item More tests for protocol classes (wxProtocol and its descendants). -\item Tests for the recently added datagram socket classes. +\item Tests for the recently added (and still in alpha stage) datagram sockets. \item New samples which actually do something useful (suggestions accepted). \end{itemize} @@ -354,15 +399,15 @@ password, ignoring TAB, ignoring ENTER). Secondly it shows how to intercept a \helpref{wxKeyEvent}{wxkeyevent} in both the raw form using the {\tt EVT\_KEY\_UP} and {\tt EVT\_KEY\_DOWN} macros and the -higherlevel from using the {\tt EVT\_CHAR} macro. All characters will be logged +higher level from using the {\tt 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 statitics on the -text ctrls, which is useful for testing if these statitics actually are correct. +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 +Thirdly, on platforms which support it, the sample will offer to copy text to the \helpref{wxClipboard}{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. +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. @@ -376,12 +421,12 @@ 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, wxWindows offers the \helpref{wxPostEvent}{wxpostevent} +worker threads possible, wxWindows offers the \helpref{wxPostEvent}{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 \helpref{wxMutex}{wxmutex} +The other way to use a so called Mutex (such as those offered in the \helpref{wxMutex}{wxmutex} class) that prevent threads from accessing the GUI classes as long as any other -thread accesses them. For this, wxWindows has the \helpref{wxMutexGuiEnter}{wxmutexguienter} +thread accesses them. For this, wxWindows has the \helpref{wxMutexGuiEnter}{wxmutexguienter} and \helpref{wxMutexGuiLeave}{wxmutexguileave} functions, both of which are used and tested in the sample as well. @@ -398,13 +443,23 @@ The following things are demonstrated: and \helpref{wxToolBar::AddControl}{wxtoolbaraddcontrol}: see MyApp::InitToolbar in the sample. \item Using {\tt EVT\_UPDATE\_UI} handler for automatically enabling/disabling -toolbar buttons without having to explicitly call EnableTool. This is is done +toolbar buttons without having to explicitly call EnableTool. This is done in MyFrame::OnUpdateCopyAndCut. \item Using \helpref{wxToolBar::DeleteTool}{wxtoolbardeletetool} and \helpref{wxToolBar::InsertTool}{wxtoolbarinserttool} to dynamically update the toolbar. \end{itemize} +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 add 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 {\tt Ctrl-A}) you will also +see the radio toolbar buttons in action: the first three buttons form a radio +group, that is checking any of them automatically unchecks the previously +checked one. + \subsection{Treectrl sample}\label{sampletreectrl} This sample demonstrates using \helpref{wxTreeCtrl}{wxtreectrl} class. Here @@ -416,3 +471,27 @@ 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{Wizard sample}\label{samplewizard} + +This sample shows so-called wizard dialog (implemented using +\helpref{wxWizard}{wxwizard} and related classes). It shows almost all +features supported: + +\begin{itemize}\itemsep=0pt +\item 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) +\item Using \helpref{TransferDataFromWindow}{wxwindowtransferdatafromwindow} +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). +\item Using more elaborated techniques to allow returning to the previous +page, but not continuing to the next one or vice versa (in wxRadioboxPage) +\item This (wxRadioboxPage) page also shows how the page may process {\tt +Cancel} button itself instead of relying on the wizard parent to do it. +\item 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 +\helpref{wxWizardPage}{wxwizardpage}) +\end{itemize} +