X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/42efa4987cf7b07cd8d5ed10036b770abe98f0c2..7447d53c35249d42128d6243c90998f03882859a:/docs/doxygen/mainpages/utilities.h diff --git a/docs/doxygen/mainpages/utilities.h b/docs/doxygen/mainpages/utilities.h index 74369912f5..a332e15577 100644 --- a/docs/doxygen/mainpages/utilities.h +++ b/docs/doxygen/mainpages/utilities.h @@ -3,608 +3,87 @@ // Purpose: Utilities page of the Doxygen manual // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// -/*! - - @page page_utils Utilities and samples supplied with wxWidgets - - @li @ref page_utils_utils - @li @ref page_utils_samples - - -
- - - @section page_utils_utils Utilities - - In addition to the @ref page_libs, some - additional utilities are supplied in the @c utils hierarchy. - - For other user-contributed packages, please see the Contributions page - on the wxWidgets Web site http://www.wxwidgets.org. - - - @subsection page_utils_utils_helpview Helpview - - Helpview is a program for displaying wxWidgets HTML - Help files. In many cases, you may wish to use the wxWidgets HTML - Help classes from within your application, but this provides a - handy stand-alone viewer. See @ref overview_html for more details. - You can find it in @c samples/html/helpview. - - @subsection page_utils_utils_tex2rtf Tex2RTF - - Supplied with wxWidgets is a utility called Tex2RTF for - converting @e LaTeX manuals HTML, MS HTML Help, wxHTML Help, RTF, and Windows - Help RTF formats. Tex2RTF was used for the wxWidgets manuals and can be used - independently by authors wishing to create on-line and printed manuals from the - same @e LaTeX source. Please see the separate documentation for Tex2RTF. - You can find it under @c utils/tex2rtf. - - @subsection page_utils_utils_helpgen Helpgen - - Helpgen takes C++ header files and generates a Tex2RTF-compatible - documentation file for each class it finds, using comments as appropriate. - This is a good way to start a reference for a set of classes. - Helpgen can be found in @c utils/HelpGen. - - @subsection page_utils_utils_emulator Emulator - - Xnest-based display emulator for X11-based PDA applications. - On some systems, the Xnest window does not synchronise with the - 'skin' window. This program can be found in @c utils/emulator. - - - - - @section page_utils_samples Samples - - Probably the best way to learn wxWidgets is by reading the source of some 50+ - samples provided with it. Many aspects of wxWidgets programming can be learnt - from them, but sometimes it is not simple to just choose the right sample to - look at. This overview aims at describing what each sample does/demonstrates to - make it easier to find the relevant one if a simple grep through all sources - didn't help. They also provide some notes about using the samples and what - features of wxWidgets are they supposed to test. - - There are currently more than 50 different samples as part of wxWidgets and - this list is not complete. You should start your tour of wxWidgets with the - minimal sample which is the wxWidgets version of - "Hello, world!". It shows the basic structure of wxWidgets program and is the - most commented sample of all - looking at its source code is recommended. - - The next most useful samples are probably widgets - and controls which show many of wxWidgets native and - generic controls, such as buttons, listboxes, checkboxes, comboboxes etc. - - Other, more complicated controls, have their own samples. In this category you - may find the following samples showing the corresponding controls: - - @li wxCalendarCtrl: @ref page_utils_samples_calendar - @li wxListCtrl: @ref page_utils_samples_listctrl - @li wxTreeCtrl: @ref page_utils_samples_treectrl - @li wxGrid: @ref page_utils_samples_grid - - Finally, it might be helpful to do a search in the entire sample directory if - you can't find the sample showing the control you are interested in by - name. Most classes contained in wxWidgets occur in at least one of the samples. - - - @subsection page_utils_samples_minimal Minimal sample - - The minimal sample is what most people will know under the term Hello World, - i.e. a minimal program that doesn't demonstrate anything apart from what is - needed to write a program that will display a "hello" dialog. This is usually - a good starting point for learning how to use wxWidgets. - - - @subsection page_utils_samples_animate Animate sample - - The @c animate sample shows how you can use wxAnimationCtrl - control and shows concept of a platform-dependent animation encapsulated - in wxAnimation. - - - @subsection page_utils_samples_artprovider Art provider sample - - The @c artprov sample shows how you can customize the look of standard - wxWidgets dialogs by replacing default bitmaps/icons with your own versions. - It also shows how you can use wxArtProvider to - get stock bitmaps for use in your application. - - - @subsection page_utils_samples_calendar Calendar sample - - This font shows the calendar control in action. It - shows how to configure the control (see the different options in the calendar - menu) and also how to process the notifications from it. - - - @subsection page_utils_samples_config Config sample - - This sample demonstrates the wxConfig classes in a platform - independent way, i.e. it uses text based files to store a given configuration under - Unix and uses the Registry under Windows. - - See wxConfig overview for the descriptions of all - features of this class. - - - @subsection page_utils_samples_controls Controls sample - - The controls sample is the main test program for most simple controls used in - wxWidgets. The sample tests their basic functionality, events, placement, - modification in terms of colour and font as well as the possibility to change - the controls programmatically, such as adding an item to a list box etc. Apart - from that, the sample uses a wxNotebook and tests most - features of this special control (using bitmap in the tabs, using - wxSizer instances and wxLayoutConstraints within notebook pages, advancing pages - programmatically and vetoing a page change by intercepting the wxNotebookEvent. - - The various controls tested are listed here: - - @li wxButton - @li wxBitmapButton - @li wxCheckBox - @li wxChoice - @li wxComboBox - @li wxGauge - @li wxStaticBox - @li wxListBox - @li wxSpinCtrl - @li wxSpinButton - @li wxStaticText - @li wxStaticBitmap - @li wxRadioBox - @li wxRadioButton - @li wxSlider - - - @subsection page_utils_samples_debugrpt DebugRpt sample - - This sample shows how to use wxDebugReport class to - generate a debug report in case of a program crash or otherwise. On start up, - it proposes to either crash itself (by dereferencing a NULL pointer) or - generate debug report without doing it. Next it initializes the debug report - with standard information adding a custom file to it (just a timestamp) and - allows to view the information gathered using - wxDebugReportPreview. - - For the report processing part of the sample to work you should make available - a Web server accepting form uploads, otherwise - wxDebugReportUpload will report an error. - - - @subsection page_utils_samples_dialogs Dialogs sample - - This sample shows how to use the common dialogs available from wxWidgets. These - dialogs are described in detail in the Common dialogs overview. - - - @subsection page_utils_samples_dialup Dialup sample - - This sample shows the wxDialUpManager - class. In the status bar, it displays the information gathered through its - interface: in particular, the current connection status (online or offline) and - whether the connection is permanent (in which case a string `LAN' appears in - the third status bar field - but note that you may be on a LAN not - connected to the Internet, in which case you will not see this) or not. - - Using the menu entries, you may also dial or hang up the line if you have a - modem attached and (this only makes sense for Windows) list the available - connections. - - - @subsection page_utils_samples_dnd DnD sample - - This sample shows both clipboard and drag and drop in action. It is quite non - trivial and may be safely used as a basis for implementing the clipboard and - drag and drop operations in a real-life program. - - When you run the sample, its screen is split in several parts. On the top, - there are two listboxes which show the standard derivations of - wxDropTarget: - wxTextDropTarget and - wxFileDropTarget. - - The middle of the sample window is taken by the log window which shows what is - going on (of course, this only works in debug builds) and may be helpful to see - the sequence of steps of data transfer. - - Finally, the last part is used for dragging text from it to either one of the - listboxes (only one will accept it) or another application. The last - functionality available from the main frame is to paste a bitmap from the - clipboard (or, in the case of the Windows version, also a metafile) - it will be - shown in a new frame. - - So far, everything we mentioned was implemented with minimal amount of code - using standard wxWidgets classes. The more advanced features are demonstrated - if you create a shape frame from the main frame menu. A shape is a geometric - object which has a position, size and color. It models some - application-specific data in this sample. A shape object supports its own - private wxDataFormat which means that you may cut and - paste it or drag and drop (between one and the same or different shapes) from - one sample instance to another (or the same). However, chances are that no - other program supports this format and so shapes can also be rendered as - bitmaps which allows them to be pasted/dropped in many other applications - (and, under Windows, also as metafiles which are supported by most of Windows - programs as well - try Write/Wordpad, for example). - - Take a look at DnDShapeDataObject class to see how you may use - wxDataObject to achieve this. - - - @subsection page_utils_samples_event Event sample - - The event sample demonstrates various features of the wxWidgets events. It - shows using dynamic events and connecting/disconnecting the event handlers - during run time and also using - PushEventHandler() and - PopEventHandler(). - - - @subsection page_utils_samples_except Except(ions) sample - - This very simple sample shows how to use C++ exceptions in wxWidgets programs, - i.e. where to catch the exception which may be thrown by the program code. It - doesn't do anything very exciting by itself, you need to study its code to - understand what goes on. - - You need to build the library with @c wxUSE_EXCEPTIONS being set to @c 1 - and compile your code with C++ exceptions support to be able to build this - sample. - - - @subsection page_utils_samples_exec Exec sample - - The exec sample demonstrates the wxExecute and - wxShell functions. Both of them are used to execute the - external programs and the sample shows how to do this synchronously (waiting - until the program terminates) or asynchronously (notification will come later). - - It also shows how to capture the output of the child process in both - synchronous and asynchronous cases and how to kill the processes with - wxProcess::Kill and test for their existence with - wxProcess::Exists. - - - @subsection page_utils_samples_font Font sample - - The font sample demonstrates wxFont, - wxFontEnumerator and - wxFontMapper classes. It allows you to see the fonts - available (to wxWidgets) on the computer and shows all characters of the - chosen font as well. - - - @subsection page_utils_samples_grid Grid sample - - TODO. - - - @subsection page_utils_samples_html HTML samples - - Eight HTML samples (you can find them in directory @c samples/html) - cover all features of the HTML sub-library. - - @li @b Test demonstrates how to create wxHtmlWindow - and also shows most supported HTML tags. - - @li @b Widget shows how you can embed ordinary controls or windows within an - HTML page. It also nicely explains how to write new tag handlers and extend - the library to work with unsupported tags. - - @li @b About may give you an idea how to write good-looking About boxes. - - @li @b Zip demonstrates use of virtual file systems in wxHTML. The zip archives - handler (ships with wxWidgets) allows you to access HTML pages stored - in a compressed archive as if they were ordinary files. - - @li @b Virtual is yet another virtual file systems demo. This one generates pages at run-time. - You may find it useful if you need to display some reports in your application. - - @li @b Printing explains use of wxHtmlEasyPrinting - class which serves as as-simple-as-possible interface for printing HTML - documents without much work. In fact, only few function calls are sufficient. - - @li @b Help and @b Helpview are variations on displaying HTML help - (compatible with MS HTML Help Workshop). @e Help shows how to embed - wxHtmlHelpController in your application - while @e Helpview is a simple tool that only pops up the help window and - displays help books given at command line. - - - @subsection page_utils_samples_image Image sample - - The image sample demonstrates use of the wxImage class - and shows how to download images in a variety of formats, currently PNG, GIF, - TIFF, JPEG, BMP, PNM and PCX. The top of the sample shows two rectangles, one - of which is drawn directly in the window, the other one is drawn into a - wxBitmap, converted to a wxImage, saved as a PNG image - and then reloaded from the PNG file again so that conversions between wxImage - and wxBitmap as well as loading and saving PNG files are tested. - - At the bottom of the main frame there is a test for using a monochrome bitmap by - drawing into a wxMemoryDC. The bitmap is then drawn - specifying the foreground and background colours with - wxDC::SetTextForeground and - wxDC::SetTextBackground (on the left). The - bitmap is then converted to a wxImage and the foreground colour (black) is - replaced with red using wxImage::Replace. - - This sample also contains the code for testing the image rotation and resizing - and using raw bitmap access, see the corresponding menu commands. - - - @subsection page_utils_samples_internat Internat(ionalization) sample - - The not very clearly named internat sample demonstrates the wxWidgets - internationalization (i18n for short from now on) features. To be more - precise, it only shows localization support, i.e. support for translating the - program messages into another language while true i18n would also involve - changing the other aspects of the programs behaviour. - - More information about this sample can be found in the @c readme.txt file in - its directory. Please see also i18n overview. - - - @subsection page_utils_samples_layout Layout sample - - The layout sample demonstrates the two different layout systems offered - by wxWidgets. When starting the program, you will see a frame with some - controls and some graphics. The controls will change their size whenever - you resize the entire frame and the exact behaviour of the size changes - is determined using the wxLayoutConstraints - class. See also the overview and the - wxIndividualLayoutConstraint - class for further information. - - The menu in this sample offers two more tests, one showing how to use - a wxBoxSizer in a simple dialog and the other one - showing how to use sizers in connection with a wxNotebook - class. See also wxSizer. - - - @subsection page_utils_samples_listctrl Listctrl sample - - This sample shows the wxListCtrl control. Different modes - supported by the control (list, icons, small icons, report) may be chosen from - the menu. - - The sample also provides some timings for adding/deleting/sorting a lot of - (several thousands) items into the control. - - - @subsection page_utils_samples_mediaplayer Mediaplayer sample - - This sample demonstrates how to use all the features of - wxMediaCtrl and play various types of sound, video, - and other files. - - It replaces the old dynamic sample. - - - @subsection page_utils_samples_notebook Notebook sample - - This samples shows wxBookCtrl family of controls. - Although initially it was written to demonstrate wxNotebook - only, it can now be also used to see wxListbook, - wxChoicebook and wxTreebook in action. - Test each of the controls, their orientation, images and pages using - commands through menu. - - - @subsection page_utils_samples_render Render sample - - This sample shows how to replace the default wxWidgets - renderer and also how to write a shared library - (DLL) implementing a renderer and load and unload it during the run-time. - - - @subsection page_utils_samples_scrollsub Scroll subwindow sample - - This sample demonstrates use of the wxScrolledWindow - class including placing subwindows into it and drawing simple graphics. It uses the - SetTargetWindow method and thus the effect - of scrolling does not show in the scrolled window itself, but in one of its subwindows. - - Additionally, this samples demonstrates how to optimize drawing operations in wxWidgets, - in particular using the wxWindow::IsExposed method with - the aim to prevent unnecessary drawing in the window and thus reducing or removing - flicker on screen. - - - @subsection page_utils_samples_sockets Sockets sample - - The sockets sample demonstrates how to use the communication facilities - provided by wxSocket. There are two different - applications in this sample: a server, which is implemented using a - wxSocketServer object, and a client, which - is implemented as a wxSocketClient. - - The server binds to the local address, using TCP port number 3000, - sets up an event handler to be notified of incoming connection requests - (@b wxSOCKET_CONNECTION events), and sits there, waiting for clients - (@e listening, in socket parlance). For each accepted connection, - a new wxSocketBase object is created. These - socket objects are independent from the server that created them, so - they set up their own event handler, and then request to be notified - of @b wxSOCKET_INPUT (incoming data) or @b wxSOCKET_LOST - (connection closed at the remote end) events. In the sample, the event - handler is the same for all connections; to find out which socket the - event is addressed to, the GetSocket function - is used. - - Although it might take some time to get used to the event-oriented - system upon which wxSocket is built, the benefits are many. See, for - example, that the server application, while being single-threaded - (and of course without using fork() or ugly select() loops) can handle - an arbitrary number of connections. - - The client starts up unconnected, so you can use the Connect... option - to specify the address of the server you are going to connect to (the - TCP port number is hard-coded as 3000). Once connected, a number of - tests are possible. Currently, three tests are implemented. They show - how to use the basic IO calls in wxSocketBase, - such as wxSocketBase::Read, wxSocketBase::Write, - wxSocketBase::ReadMsg and wxSocketBase::WriteMsg, - and how to set up the correct IO flags depending on what you are going to - do. See the comments in the code for more information. Note that because - both clients and connection objects in the server set up an event handler - to catch @b wxSOCKET_LOST events, each one is immediately notified - if the other end closes the connection. - - There is also a URL test which shows how to use - the wxURL class to fetch data from a given URL. - - The sockets sample is work in progress. Some things to do: - - @li More tests for basic socket functionality. - @li More tests for protocol classes (wxProtocol and its descendants). - @li Tests for the recently added (and still in alpha stage) datagram sockets. - @li New samples which actually do something useful (suggestions accepted). - - - @subsection page_utils_samples_sound Sound sample - - The @c sound sample shows how to use wxSound for simple - audio output (e.g. notifications). - - - @subsection page_utils_samples_statbar Statbar sample - - This sample shows how to create and use wxStatusBar. Although most of the - samples have a statusbar, they usually only create a default one and only - do it once. - - Here you can see how to recreate the statusbar (with possibly different number - of fields) and how to use it to show icons/bitmaps and/or put arbitrary - controls into it. - - - @subsection page_utils_samples_taborder Tab order sample - - This sample allows to test keyboard navigation (mostly done using the - @c TAB key, hence the sample name) between different controls. - It shows the use of wxWindow::MoveBeforeInTabOrder() and - MoveAfterInTabOrder() methods to change - the default order of the windows in the navigation chain and of - wxWindow::Navigate() for moving focus along this - chain. - - - @subsection page_utils_samples_text Text sample - - This sample demonstrates four features: firstly the use and many variants of - the wxTextCtrl class (single line, multi line, read only, - password, ignoring TAB, ignoring ENTER). - - Secondly it shows how to intercept a wxKeyEvent in both - the raw form using the @c EVT_KEY_UP and @c EVT_KEY_DOWN macros and the - higher level from using the @c EVT_CHAR macro. All characters will be logged - in a log window at the bottom of the main window. By pressing some of the function - keys, you can test some actions in the text ctrl as well as get statistics on the - text ctrls, which is useful for testing if these statistics actually are correct. - - Thirdly, on platforms which support it, the sample will offer to copy text to the - wxClipboard and to paste text from it. The GTK version will - use the so called PRIMARY SELECTION, which is the pseudo clipboard under X and - best known from pasting text to the XTerm program. - - Last not least: some of the text controls have tooltips and the sample also shows - how tooltips can be centrally disabled and their latency controlled. - - - @subsection page_utils_samples_thread Thread sample - - This sample demonstrates use of threads in connection with GUI programs. - There are two fundamentally different ways to use threads in GUI programs and - either way has to take care of the fact that the GUI library itself usually - is not multi-threading safe, i.e. that it might crash if two threads try to - access the GUI class simultaneously. One way to prevent that is have a normal - GUI program in the main thread and some worker threads which work in the - background. In order to make communication between the main thread and the - worker threads possible, wxWidgets offers the wxPostEvent - function and this sample makes use of this function. - - The other way to use a so called Mutex (such as those offered in the wxMutex - class) that prevent threads from accessing the GUI classes as long as any other - thread accesses them. For this, wxWidgets has the wxMutexGuiEnter - and wxMutexGuiLeave functions, both of which are - used and tested in the sample as well. - - See also @ref overview_thread and wxThread. - - - @subsection page_utils_samples_toolbar Toolbar sample - - The toolbar sample shows the wxToolBar class in action. - - The following things are demonstrated: - - @li Creating the toolbar using wxToolBar::AddTool and wxToolBar::AddControl: see - MyApp::InitToolbar in the sample. - @li Using @c EVT_UPDATE_UI handler for automatically enabling/disabling - toolbar buttons without having to explicitly call EnableTool. This is done - in MyFrame::OnUpdateCopyAndCut. - @li Using wxToolBar::DeleteTool and wxToolBar::InsertTool to dynamically update the - toolbar. - - Some buttons in the main toolbar are check buttons, i.e. they stay checked when - pressed. On the platforms which support it, the sample also adds a combobox - to the toolbar showing how you can use arbitrary controls and not only buttons - in it. - - If you toggle another toolbar in the sample (using @c Ctrl-A) you will also - see the radio toolbar buttons in action: the first three buttons form a radio - group, i.e. checking any of them automatically unchecks the previously - checked one. - - - @subsection page_utils_samples_treectrl Treectrl sample - - This sample demonstrates using the wxTreeCtrl class. Here - you may see how to process various notification messages sent by this control - and also when they occur (by looking at the messages in the text control in - the bottom part of the frame). - - Adding, inserting and deleting items and branches from the tree as well as - sorting (in default alphabetical order as well as in custom one) is - demonstrated here as well - try the corresponding menu entries. - - - @subsection page_utils_samples_widgets Widgets sample - - The widgets sample is the main presentation program for most simple and advanced - native controls and complex generic widgets provided by wxWidgets. - The sample tests their basic functionality, events, placement, modification - in terms of colour and font as well as the possibility to change - the controls programmatically, such as adding an item to a list box etc. - All widgets are categorized for easy browsing. - - - @subsection page_utils_samples_wizard Wizard sample - - This sample shows the so-called wizard dialog (implemented using - wxWizard and related classes). It shows almost all - features supported: - - @li Using bitmaps with the wizard and changing them depending on the page - shown (notice that wxValidationPage in the sample has a different image from - the other ones) - @li Using TransferDataFromWindow - to verify that the data entered is correct before passing to the next page - (done in wxValidationPage which forces the user to check a checkbox before - continuing). - @li Using more elaborated techniques to allow returning to the previous - page, but not continuing to the next one or vice versa (in wxRadioboxPage) - @li This (wxRadioboxPage) page also shows how the page may process the - @e Cancel button itself instead of relying on the wizard parent to do it. - @li Normally, the order of the pages in the wizard is known at compile-time, - but sometimes it depends on the user choices: wxCheckboxPage shows how to - dynamically decide which page to display next (see also - wxWizardPage) +/** + +@page page_utils Utilities Overview + +In addition to the wxWidgets libraries (see @ref page_libs), some utilities +are available to the users in the @c utils hierarchy (even if some of them are +explicitly conceived for wxWidgets maintainance and will probably be of +little use to others). + +Please note that these utilities do represent only the utilities developed +and maintained by the wxWidgets team. +There are lots of other user-contributed and user-maintained packages; +see the wxWidgets download page: http://www.wxwidgets.org/downloads +or directly http://wxcode.sourceforge.net or http://www.wxcommunity.com/ . + +@li @ref page_utils_emulator +@li @ref page_utils_helpview +@li @ref page_utils_hhp2cached +@li @ref page_utils_ifacecheck +@li @ref page_utils_wxrc + + +
+ + +@section page_utils_emulator Emulator + +Xnest-based display emulator for X11-based PDA applications. + + + +This program can be found in @c utils/emulator. + + +@section page_utils_helpview Help Viewer + +Helpview is a program for displaying wxWidgets HTML Help files. +In many cases, you may wish to use the wxWidgets HTML +Help classes from within your application, but this provides a +handy stand-alone viewer. See @ref overview_html for more details. + +You can find Helpview in @c utils/helpview. + + +@section page_utils_hhp2cached HHP2Cached + +This utility creates a "cached" version of a @c .hhp file; using cached @c .hhp +files in wxHtmlHelpController can drammatically improve the performances +of the help viewer. See wxHtmlHelpController for more details. + +You can find HHP2Cached in @c utils/hhp2cached. + + +@section page_utils_ifacecheck Interface checker + +This utility compares the wxWidgets real interface contained in the @c include +hierarchy with the wxWidgets interface used for documentation purposes and +kept in the @c interface hierarchy. + +Ifacecheck warns about incoherences (mainly wrong prototype signatures) and +can even correct them automatically. It uses the XML outputs of the gccxml utility +(see http://www.gccxml.org) and of the Doxygen utility (see http://www.doxygen.org) +to do the comparisons. + +It's explicitly designed for wxWidgets documentation needs and is probably of little +use for anything else than wxWidgets docs reviewing. + +You can find it in @c utils/ifacecheck. + + +@section page_utils_wxrc wxWidgets XML Resource Compiler + +This utility allows the user to compile @e binary versions of their XRC files, +which are compressed and can be loaded faster than plain XRC files. +See @ref overview_xrc for more info. + +You can find it under @c utils/wxrc. */ +