From: Bryan Petty Date: Sat, 3 Nov 2012 18:34:10 +0000 (+0000) Subject: Finished adding @tableofcontents to all overviews in the manual. X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/831e1028def2ce21063298e396451b672c1255d9 Finished adding @tableofcontents to all overviews in the manual. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@72877 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/docs/doxygen/overviews/app.h b/docs/doxygen/overviews/app.h index 443e4dd0ed..14e941b155 100644 --- a/docs/doxygen/overviews/app.h +++ b/docs/doxygen/overviews/app.h @@ -12,10 +12,6 @@ @tableofcontents - - -@section overview_app_intro Introduction - A wxWidgets application does not have a @e main procedure; the equivalent is the wxApp::OnInit member defined for a class derived from wxApp. @@ -129,4 +125,3 @@ int MyApp::OnExit() @endcode */ - diff --git a/docs/doxygen/overviews/container.h b/docs/doxygen/overviews/container.h index 023ab9d77b..83f092a555 100644 --- a/docs/doxygen/overviews/container.h +++ b/docs/doxygen/overviews/container.h @@ -12,12 +12,6 @@ @tableofcontents -@see @ref group_class_containers - - - -@section overview_container_intro Overview - For historical reasons, wxWidgets uses custom container classes internally. This was unfortunately unavoidable during a long time when the standard library wasn't widely available and can't be easily changed even now that it is for @@ -50,6 +44,8 @@ it isn't and only use legacy wxWidgets containers such as wxArray and wxList when you must, i.e. when you use a wxWidgets function taking or returning a container of such type. +@see @ref group_class_containers + @section overview_container_legacy Legacy Classes diff --git a/docs/doxygen/overviews/cpprttidisabled.h b/docs/doxygen/overviews/cpprttidisabled.h index 90ae5f6063..824aba7f19 100644 --- a/docs/doxygen/overviews/cpprttidisabled.h +++ b/docs/doxygen/overviews/cpprttidisabled.h @@ -12,12 +12,6 @@ @tableofcontents -@see @ref overview_rtti, wxEvtHandler::Bind(), wxAny - - - -@section overview_cpp_rtti_disabled_intro Introduction - @note C++ RTTI is usually enabled by default in most wxWidgets builds. If you do not know if your build has C++ RTTI enabled or not, then it probably is enabled, and you should not worry about anything mentioned in this @@ -34,6 +28,8 @@ is a shared library or DLL build. More specifically, a template class instance created in one physical binary may not be recognized as its correct type when used in another one. +@see @ref overview_rtti, wxEvtHandler::Bind(), wxAny + @section overview_cpp_rtti_disabled_bind Bind() Issues diff --git a/docs/doxygen/overviews/eventhandling.h b/docs/doxygen/overviews/eventhandling.h index 098c7efafa..405b3e1f36 100644 --- a/docs/doxygen/overviews/eventhandling.h +++ b/docs/doxygen/overviews/eventhandling.h @@ -10,19 +10,7 @@ @page overview_events Events and Event Handling -Related classes: wxEvtHandler, wxWindow, wxEvent - -@li @ref overview_events_introduction -@li @ref overview_events_eventhandling -@li @ref overview_events_processing -@li @ref overview_events_custom -@li @ref overview_events_misc - - -
- - -@section overview_events_introduction Introduction to Events +@tableofcontents Like with all the other GUI frameworks, the control of flow in wxWidgets applications is event-based: the program normally performs most of its actions @@ -57,6 +45,9 @@ To be more precise, each event is described by: event), checking the event source object or its id allows to distinguish between them. +@see wxEvtHandler, wxWindow, wxEvent + + @section overview_events_eventhandling Event Handling @@ -872,11 +863,10 @@ your identifiers don't conflict accidentally. -@subsection overview_events_list List of wxWidgets events +@subsection overview_events_list List of wxWidgets Events For the full list of event classes, please see the @ref group_class_events "event classes group page". */ - diff --git a/docs/doxygen/overviews/exceptions.h b/docs/doxygen/overviews/exceptions.h index 83192f0cf0..80bbbeff30 100644 --- a/docs/doxygen/overviews/exceptions.h +++ b/docs/doxygen/overviews/exceptions.h @@ -10,15 +10,7 @@ @page overview_exceptions C++ Exceptions -@li @ref overview_exceptions_introduction -@li @ref overview_exceptions_strategies -@li @ref overview_exceptions_tech - - -
- - -@section overview_exceptions_introduction Introduction +@tableofcontents wxWidgets had been started long before the exceptions were introduced in C++ so it is not very surprising that it is not built around using them as some more @@ -34,7 +26,8 @@ safe to use the exceptions in the user code and the library tries to help you with this. -@section overview_exceptions_strategies Strategies for exceptions handling + +@section overview_exceptions_strategies Strategies for Exception Handling There are several choice for using the exceptions in wxWidgets programs. First of all, you may not use them at all. As stated above, the library doesn't throw diff --git a/docs/doxygen/overviews/file.h b/docs/doxygen/overviews/file.h index 0f31fc3838..d3a2828a29 100644 --- a/docs/doxygen/overviews/file.h +++ b/docs/doxygen/overviews/file.h @@ -10,9 +10,7 @@ @page overview_file File Classes and Functions -Classes: wxFile, wxDir, wxTempFile, wxTextFile - -Functions: see @ref group_funcmacro_file. +@tableofcontents wxWidgets provides some functions and classes to facilitate working with files. As usual, the accent is put on cross-platform features which explains, for @@ -38,5 +36,6 @@ wxDir is a helper class for enumerating the files or subdirectories of a directory. It may be used to enumerate all files, only files satisfying the given template mask or only non-hidden files. -*/ +@see wxFile, wxDir, wxTempFile, wxTextFile, @ref group_funcmacro_file +*/ diff --git a/docs/doxygen/overviews/filesystem.h b/docs/doxygen/overviews/filesystem.h index 2dc02cb717..fea388a134 100644 --- a/docs/doxygen/overviews/filesystem.h +++ b/docs/doxygen/overviews/filesystem.h @@ -10,21 +10,15 @@ @page overview_fs wxFileSystem Overview -The wxHTML library uses a @b virtual file systems mechanism -similar to the one used in Midnight Commander, Dos Navigator, -FAR or almost any modern file manager. It allows the user to access -data stored in archives as if they were ordinary files. On-the-fly -generated files that exist only in memory are also supported. +@tableofcontents -@li @ref overview_fs_classes -@li @ref overview_fs_locations -@li @ref overview_fs_combined -@li @ref overview_fs_wxhtmlfs -@li @ref overview_fs_init +The wxHTML library uses a @b virtual file system mechanism similar to the one +used in Midnight Commander, Dos Navigator, FAR or almost any modern file +manager. It allows the user to access data stored in archives as if they were +ordinary files. On-the-fly generated files that exist only in memory are also +supported. -
- @section overview_fs_classes Classes @@ -113,4 +107,3 @@ bool MyApp::OnInit() @endcode */ - diff --git a/docs/doxygen/overviews/font.h b/docs/doxygen/overviews/font.h index bd95c95bbe..379698d586 100644 --- a/docs/doxygen/overviews/font.h +++ b/docs/doxygen/overviews/font.h @@ -10,19 +10,11 @@ @page overview_font wxFont Overview -Class: wxFont, wxFontDialog +@tableofcontents -@li @ref overview_font_intro -@li @ref overview_font_nativeinfo - -
- - -@section overview_font_intro Introduction - -A font is an object which determines the appearance of text, primarily -when drawing text to a window or device context. A font is determined by -the following parameters (not all of them have to be specified, of course): +A font is an object which determines the appearance of text, primarily when +drawing text to a window or device context. A font is determined by the +following parameters (not all of them have to be specified, of course): @beginDefList @itemdef{Point size, This is the standard way of referring to text size.} @@ -54,16 +46,18 @@ standard Windows fonts, or if allowing the user to specify a face name, store the family name with any file that might be transported to a different Windows machine or other platform. -@note There is currently a difference between the appearance - of fonts on the two platforms, if the mapping mode is anything other than - wxMM_TEXT. Under X, font size is always specified in points. Under MS - Windows, the unit for text is points but the text is scaled according to the - current mapping mode. However, user scaling on a device context will also - scale fonts under both environments. +@see wxFont, wxFontDialog + +@note There is currently a difference between the appearance of fonts on the + two platforms, if the mapping mode is anything other than wxMM_TEXT. + Under X, font size is always specified in points. Under MS Windows, the + unit for text is points but the text is scaled according to the current + mapping mode. However, user scaling on a device context will also scale + fonts under both environments. -@section overview_font_nativeinfo Native font information +@section overview_font_nativeinfo Native Font Information An alternative way of choosing fonts is to use the native font description. This is the only acceptable solution if the user is allowed to choose the font @@ -83,4 +77,3 @@ are available for all the ports and should be used to make your program work correctly when they are implemented later. */ - diff --git a/docs/doxygen/overviews/fontencoding.h b/docs/doxygen/overviews/fontencoding.h index 7775d313fb..09b679b3b8 100644 --- a/docs/doxygen/overviews/fontencoding.h +++ b/docs/doxygen/overviews/fontencoding.h @@ -10,6 +10,8 @@ @page overview_fontencoding Font Encodings +@tableofcontents + wxWidgets has support for multiple font encodings. By encoding we mean here the mapping between the character codes and the @@ -20,10 +22,10 @@ letters of foreign alphabets and here other encodings come into play. Please note that we will only discuss 8-bit fonts here and not Unicode (see @ref overview_unicode). -Font encoding support is ensured by several classes: -wxFont itself, but also wxFontEnumerator and wxFontMapper. wxFont encoding -support is reflected by a (new) constructor parameter @e encoding which takes -one of the following values (elements of enumeration type @c wxFontEncoding): +Font encoding support is ensured by several classes: wxFont itself, but also +wxFontEnumerator and wxFontMapper. wxFont encoding support is reflected by a +(new) constructor parameter @e encoding which takes one of the following values +(elements of enumeration type @c wxFontEncoding): @beginDefList @itemdef{wxFONTENCODING_SYSTEM, @@ -63,26 +65,23 @@ written in Cyrillic) are different on different platforms and because the fonts in the given encoding might just not be installed (this is especially a problem with Unix, or, in general, non-Win32 systems). -To clarify, the wxFontEnumerator -class may be used to enumerate both all available encodings and to find the -facename(s) in which the given encoding exists. If you can find the font in -the correct encoding with wxFontEnumerator then your troubles are over, but, -unfortunately, sometimes this is not enough. For example, there is no standard -way (that I know of, please tell me if you do!) to find a font on a Windows system -for KOI8 encoding (only for WinCyrillic one which is quite different), so -wxFontEnumerator will never return one, even if the user has installed a KOI8 -font on his system. +To clarify, the wxFontEnumerator class may be used to enumerate both all +available encodings and to find the facename(s) in which the given encoding +exists. If you can find the font in the correct encoding with wxFontEnumerator +then your troubles are over, but, unfortunately, sometimes this is not enough. +For example, there is no standard way (that I know of, please tell me if you +do!) to find a font on a Windows system for KOI8 encoding (only for WinCyrillic +one which is quite different), so wxFontEnumerator will never return one, even +if the user has installed a KOI8 font on his system. To solve this problem, a wxFontMapper class is provided. -This class stores the mapping between the encodings and the font face -names which support them in wxConfigBase object. -Of course, it would be fairly useless if it tried to determine these mappings by -itself, so, instead, it (optionally) asks the user and remembers his answers -so that the next time the program will automatically choose the correct font. -All these topics are illustrated by the @ref page_samples_font; -please refer to it and the documentation of the classes mentioned here for -further explanations. +This class stores the mapping between the encodings and the font face names +which support them in wxConfigBase object. Of course, it would be fairly +useless if it tried to determine these mappings by itself, so, instead, it +(optionally) asks the user and remembers his answers so that the next time the +program will automatically choose the correct font. All these topics are +illustrated by the @ref page_samples_font; please refer to it and the +documentation of the classes mentioned here for further explanations. */ - diff --git a/docs/doxygen/overviews/grid.h b/docs/doxygen/overviews/grid.h index 70b886d17a..d37678d374 100644 --- a/docs/doxygen/overviews/grid.h +++ b/docs/doxygen/overviews/grid.h @@ -10,67 +10,57 @@ @page overview_grid wxGrid Overview -Classes: wxGrid - -@li @ref overview_grid_intro -@li @ref overview_grid_simpleexample -@li @ref overview_grid_complexexample -@li @ref overview_grid_classrelations -@li @ref overview_grid_keyboardmouse - - -
- - -@section overview_grid_intro Introduction +@tableofcontents wxGrid and its related classes are used for displaying and editing tabular data. wxGrid supports custom attributes for the table cells, allowing to completely customize its appearance and uses a separate grid table -(wxGridTableBase-derived) class for the data management meaning that it -can be used to display arbitrary amounts of data. +(wxGridTableBase-derived) class for the data management meaning that it can be +used to display arbitrary amounts of data. + + -@section overview_grid_simpleexample Getting started: a simple example +@section overview_grid_simpleexample Getting Started -For simple applications you need only refer to the wxGrid class in your -code. This example shows how you might create a grid in a frame or -dialog constructor and illustrates some of the formatting functions. +For simple applications you need only refer to the wxGrid class in your code. +This example shows how you might create a grid in a frame or dialog constructor +and illustrates some of the formatting functions. @code - // Create a wxGrid object - - grid = new wxGrid( this, - -1, - wxPoint( 0, 0 ), - wxSize( 400, 300 ) ); - - // Then we call CreateGrid to set the dimensions of the grid - // (100 rows and 10 columns in this example) - grid->CreateGrid( 100, 10 ); - - // We can set the sizes of individual rows and columns - // in pixels - grid->SetRowSize( 0, 60 ); - grid->SetColSize( 0, 120 ); - - // And set grid cell contents as strings - grid->SetCellValue( 0, 0, "wxGrid is good" ); - - // We can specify that some cells are read->only - grid->SetCellValue( 0, 3, "This is read->only" ); - grid->SetReadOnly( 0, 3 ); - - // Colours can be specified for grid cell contents - grid->SetCellValue(3, 3, "green on grey"); - grid->SetCellTextColour(3, 3, *wxGREEN); - grid->SetCellBackgroundColour(3, 3, *wxLIGHT_GREY); - - // We can specify the some cells will store numeric - // values rather than strings. Here we set grid column 5 - // to hold floating point values displayed with width of 6 - // and precision of 2 - grid->SetColFormatFloat(5, 6, 2); - grid->SetCellValue(0, 6, "3.1415"); +// Create a wxGrid object + +grid = new wxGrid( this, + -1, + wxPoint( 0, 0 ), + wxSize( 400, 300 ) ); + +// Then we call CreateGrid to set the dimensions of the grid +// (100 rows and 10 columns in this example) +grid->CreateGrid( 100, 10 ); + +// We can set the sizes of individual rows and columns +// in pixels +grid->SetRowSize( 0, 60 ); +grid->SetColSize( 0, 120 ); + +// And set grid cell contents as strings +grid->SetCellValue( 0, 0, "wxGrid is good" ); + +// We can specify that some cells are read->only +grid->SetCellValue( 0, 3, "This is read->only" ); +grid->SetReadOnly( 0, 3 ); + +// Colours can be specified for grid cell contents +grid->SetCellValue(3, 3, "green on grey"); +grid->SetCellTextColour(3, 3, *wxGREEN); +grid->SetCellBackgroundColour(3, 3, *wxLIGHT_GREY); + +// We can specify the some cells will store numeric +// values rather than strings. Here we set grid column 5 +// to hold floating point values displayed with width of 6 +// and precision of 2 +grid->SetColFormatFloat(5, 6, 2); +grid->SetCellValue(0, 6, "3.1415"); @endcode Here is a list of classes related to wxGrid: @@ -113,21 +103,9 @@ Here is a list of classes related to wxGrid: @li wxGridTypeRegistry: Contains information about the data types supported by the grid. -@section overview_grid_complexexample A more complex example - -@todo To be written - - -@section overview_grid_classrelations How the wxGrid classes relate to each other - -@todo To be written - - -@section overview_grid_keyboardmouse Keyboard and mouse actions -@todo To be written -@section overview_grid_resizing Column and row sizes +@section overview_grid_resizing Column and Row Sizes @b NB: This section will discuss the resizing of wxGrid rows only to avoid repetitions but everything in it also applies to grid columns, just replace @c diff --git a/docs/doxygen/overviews/helloworld.h b/docs/doxygen/overviews/helloworld.h index ff5c20d287..12c8ae1cfb 100644 --- a/docs/doxygen/overviews/helloworld.h +++ b/docs/doxygen/overviews/helloworld.h @@ -10,20 +10,22 @@ @page overview_helloworld Hello World Example +@tableofcontents + This page shows a very simple wxWidgets program that can be used as a skeleton for your own code. While it does nothing very useful, it introduces a couple of important concepts and explains how to write a working wxWidgets application. -First, you have to include wxWidgets' header files, of course. This can -be done on a file by file basis (such as @c wx/window.h) or using one -global include (@c wx/wx.h) which includes most of the commonly needed headers -(although not all of them as there are simply too many wxWidgets headers to -pull in all of them). For the platforms with support for precompiled headers, -as indicated by @c WX_PRECOMP, this global header is already included by @c -wx/wxprec.h so we only include it for the other ones: +First, you have to include wxWidgets' header files, of course. This can be done +on a file by file basis (such as @c wx/window.h) or using one global include +(@c wx/wx.h) which includes most of the commonly needed headers (although not +all of them as there are simply too many wxWidgets headers to pull in all of +them). For the platforms with support for precompiled headers, as indicated by +@c WX_PRECOMP, this global header is already included by @c wx/wxprec.h so we +only include it for the other ones: @code -// wxWidgets "Hello world" Program +// wxWidgets "Hello world" Program // For compilers that support precompilation, includes "wx/wx.h". #include @@ -45,17 +47,16 @@ public: }; @endcode -The main window is created by deriving a class from wxFrame and -giving it a menu and a status bar in its constructor. Also, any class -that wishes to respond to any "event" (such as mouse clicks or -messages from the menu or a button) must declare an event table -using the macro below. +The main window is created by deriving a class from wxFrame and giving it a +menu and a status bar in its constructor. Also, any class that wishes to +respond to any "event" (such as mouse clicks or messages from the menu or a +button) must declare an event table using the macro below. -Finally, the way to react to such events must be done in "handlers". -In our sample, we react to three menu items, one for our custom menu -command and two for the standard "Exit" and "About" commands (any program -should normally implement the latter two). Notice that these handlers -don't need to be neither virtual nor public. +Finally, the way to react to such events must be done in "handlers". In our +sample, we react to three menu items, one for our custom menu command and two +for the standard "Exit" and "About" commands (any program should normally +implement the latter two). Notice that these handlers don't need to be neither +virtual nor public. @code class MyFrame: public wxFrame @@ -83,20 +84,20 @@ enum }; @endcode -Notice that you don't need to define identifiers for the "About" and "Exit" -We then proceed to actually implement an event table in which the events -are routed to their respective handler functions in the class MyFrame. +Notice that you don't need to define identifiers for the "About" and "Exit". We +then proceed to actually implement an event table in which the events are +routed to their respective handler functions in the class MyFrame. -There are predefined macros for routing all common events, ranging from -the selection of a list box entry to a resize event when a user resizes -a window on the screen. If @c wxID_ANY is given as the ID, the given handler will be -invoked for any event of the specified type, so that you could add just -one entry in the event table for all menu commands or all button commands etc. +There are predefined macros for routing all common events, ranging from the +selection of a list box entry to a resize event when a user resizes a window on +the screen. If @c wxID_ANY is given as the ID, the given handler will be +invoked for any event of the specified type, so that you could add just one +entry in the event table for all menu commands or all button commands etc. -The origin of the event can still be distinguished in the event handler as -the (only) parameter in an event handler is a reference to a wxEvent object, -which holds various information about the event (such as the ID of and a -pointer to the class, which emitted the event). +The origin of the event can still be distinguished in the event handler as the +(only) parameter in an event handler is a reference to a wxEvent object, which +holds various information about the event (such as the ID of and a pointer to +the class, which emitted the event). @code wxBEGIN_EVENT_TABLE(MyFrame, wxFrame) @@ -106,31 +107,32 @@ wxBEGIN_EVENT_TABLE(MyFrame, wxFrame) wxEND_EVENT_TABLE() @endcode -As in all programs there must be a "main" function. Under wxWidgets main is implemented -using this macro, which creates an application instance and starts the program. +As in all programs there must be a "main" function. Under wxWidgets main is +implemented using this macro, which creates an application instance and starts +the program. @code wxIMPLEMENT_APP(MyApp) @endcode -As mentioned above, wxApp::OnInit() is called upon startup and should be -used to initialize the program, maybe showing a "splash screen" and creating -the main window (or several). The frame should get a title bar text ("Hello World") -and a position and start-up size. One frame can also be declared to be the -top window. Returning @true indicates a successful initialization. +As mentioned above, wxApp::OnInit() is called upon startup and should be used +to initialize the program, maybe showing a "splash screen" and creating the +main window (or several). The frame should get a title bar text ("Hello World") +and a position and start-up size. One frame can also be declared to be the top +window. Returning @true indicates a successful initialization. @code bool MyApp::OnInit() { - MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) ); + MyFrame *frame = new MyFrame( "Hello World", wxPoint(50, 50), wxSize(450, 340) ); frame->Show( true ); return true; } @endcode -In the constructor of the main window (or later on) we create a menu with our menu -items as well as a status bar to be shown at the bottom of the main window. Both have -to be associated with the frame with respective calls. +In the constructor of the main window (or later on) we create a menu with our +menu items as well as a status bar to be shown at the bottom of the main +window. Both have to be associated with the frame with respective calls. @code MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size) @@ -188,6 +190,7 @@ void MyFrame::OnAbout(wxCommandEvent& event) The implementation of custom menu command handler may perform whatever task your program needs to do, in this case we will simply show a message from it as befits a hello world example: + @code void MyFrame::OnHello(wxCommandEvent& event) { @@ -196,8 +199,9 @@ void MyFrame::OnHello(wxCommandEvent& event) @endcode Here is the entire program that can be copied and pasted: + @code -// wxWidgets "Hello world" Program +// wxWidgets "Hello world" Program // For compilers that support precompilation, includes "wx/wx.h". #include @@ -240,7 +244,7 @@ wxIMPLEMENT_APP(MyApp); bool MyApp::OnInit() { - MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) ); + MyFrame *frame = new MyFrame( "Hello World", wxPoint(50, 50), wxSize(450, 340) ); frame->Show( true ); return true; } @@ -285,4 +289,3 @@ void MyFrame::OnHello(wxCommandEvent& event) @endcode */ - diff --git a/docs/doxygen/overviews/html.h b/docs/doxygen/overviews/html.h index 370001478c..9c3d8bcbb0 100644 --- a/docs/doxygen/overviews/html.h +++ b/docs/doxygen/overviews/html.h @@ -10,6 +10,8 @@ @page overview_html wxHTML Overview +@tableofcontents + The wxHTML library provides classes for parsing and displaying HTML. It is not intended to be a high-end HTML browser. If you are looking for something like that try . @@ -27,36 +29,27 @@ See @c src/html/m_*.cpp files for details. There is a generic wxHtmlParser class, independent of wxHtmlWindow. -@li @ref overview_html_quickstart -@li @ref overview_html_printing -@li @ref overview_html_helpformats -@li @ref overview_html_filters -@li @ref overview_html_cells -@li @ref overview_html_handlers -@li @ref overview_html_supptags - - -
-@section overview_html_quickstart wxHTML quick start +@section overview_html_quickstart wxHTML Quick Start @subsection overview_html_quickstart_disphtml Displaying HTML First of all, you must include @c wx/wxhtml.h. -Class wxHtmlWindow (derived from ::wxScrolledWindow) is used to display HTML documents. +Class wxHtmlWindow (derived from ::wxScrolledWindow) is used to display HTML +documents. It has two important methods: wxHtmlWindow::LoadPage and wxHtmlWindow::SetPage. LoadPage loads and displays HTML file while SetPage displays directly the passed @b string. See the example: @code - mywin -> LoadPage("test.htm"); - mywin -> SetPage("htmlbody" - "h1Error/h1" - "Some error occurred :-H)" - "/body/hmtl"); +mywin->LoadPage("test.htm"); +mywin->SetPage("htmlbody" + "h1Error/h1" + "Some error occurred :-H)" + "/body/hmtl"); @endcode @subsection overview_html_quickstart_settingup Setting up wxHtmlWindow @@ -71,9 +64,9 @@ wxHtmlWindow::SetRelatedFrame and wxHtmlWindow::SetRelatedStatusBar. See the example: @code - html = new wxHtmlWindow(this); - html -> SetRelatedFrame(this, "HTML : %%s"); - html -> SetRelatedStatusBar(0); +html = new wxHtmlWindow(this); +html->SetRelatedFrame(this, "HTML : %%s"); +html->SetRelatedStatusBar(0); @endcode The first command associates the HTML object with its parent frame @@ -101,32 +94,33 @@ The last two functions are used to store user customization info wxConfig stuff @section overview_html_printing HTML Printing -The wxHTML library provides printing facilities with several levels of complexity. -The easiest way to print an HTML document is to use the wxHtmlEasyPrinting class. +The wxHTML library provides printing facilities with several levels of +complexity. The easiest way to print an HTML document is to use the +wxHtmlEasyPrinting class. -It lets you print HTML documents with only one command and you don't have to worry -about deriving from the wxPrintout class at all. It is only a simple wrapper around the -wxHtmlPrintout, normal wxWidgets printout class. +It lets you print HTML documents with only one command and you don't have to +worry about deriving from the wxPrintout class at all. It is only a simple +wrapper around the wxHtmlPrintout, normal wxWidgets printout class. And finally there is the low level class wxHtmlDCRenderer which you can use to -render HTML into a rectangular area on any DC. +render HTML into a rectangular area on any DC. It supports rendering into +multiple rectangles with the same width. The most common use of this is placing +one rectangle on each page or printing into two columns. -It supports rendering into multiple rectangles with the same -width. (The most common use of this is placing one rectangle on each page or -printing into two columns.) @section overview_html_helpformats Help Files Format -wxHTML library can be used to show an help manual to the user; in fact, it supports -natively (through wxHtmlHelpController) a reduced version of MS HTML Workshop format. +wxHTML library can be used to show an help manual to the user; in fact, it +supports natively (through wxHtmlHelpController) a reduced version of MS HTML +Workshop format. A @b book consists of three files: the header file, the contents file and the index file. -You can make a regular zip archive of these files, plus the HTML and any -image files, for wxHTML (or helpview) to read; and the @c ".zip" file can -optionally be renamed to @c ".htb". +You can make a regular zip archive of these files, plus the HTML and any image +files, for wxHTML (or helpview) to read; and the @c ".zip" file can optionally +be renamed to @c ".htb". @subsection overview_html_helpformats_hhp Header file (.hhp) @@ -159,56 +153,54 @@ It contains exactly one list (@c <ul>....@c </ul> statement): @code
    - -
  • +
  • -
  • +
  • -... + ... @endcode -You can modify value attributes of param tags. -The topic name is name of chapter/topic as is displayed in -contents, filename.htm is the HTML page name (relative to the @c ".hhp" file) -and numeric_id is optional - it is used only when you use wxHtmlHelpController::Display(int). +You can modify value attributes of param tags. The topic name is name +of chapter/topic as is displayed in contents, filename.htm is the HTML +page name (relative to the @c ".hhp" file) and numeric_id is optional, +it is used only when you use wxHtmlHelpController::Display(int). -Items in the list may be nested - one @c <li> statement may contain a @c <ul> sub-statement: +Items in the list may be nested - one @c <li> statement may contain a +@c <ul> sub-statement: @code
      - -
    • - - - +
    • + + +
      • - ... + ...
      - -
    • - - - -... - +
    • + + + + ...
    @endcode -@subsection overview_html_helpformats_hhk Index file (.hhk) +@subsection overview_html_helpformats_hhk Index Files (.hhk) + +Index files have same format as contents files except that ID params are +ignored and sublists are @b not allowed. -Index files have same format as contents files except that ID params are ignored -and sublists are @b not allowed. @section overview_html_filters Input Filters @@ -221,6 +213,7 @@ To make a file type known to wxHtmlWindow you must create a wxHtmlFilter filter register it using wxHtmlWindow::AddFilter. + @section overview_html_cells Cells and Containers This article describes mechanism used by wxHtmlWinParser and @@ -262,20 +255,18 @@ to the parent container. See explanation: There clearly must be same number of calls to OpenContainer as to CloseContainer. -@subsubsection overview_html_cells_conttaghandler_example Example - -This code creates a new paragraph (container at same depth level) -with "Hello, world!": +This code creates a new paragraph (container at same depth level) with +"Hello, world!": @code -m_WParser -> CloseContainer(); -c = m_WParser -> OpenContainer(); +m_WParser->CloseContainer(); +c = m_WParser->OpenContainer(); -m_WParser -> AddText("Hello, "); -m_WParser -> AddText("world!"); +m_WParser->AddText("Hello, "); +m_WParser->AddText("world!"); -m_WParser -> CloseContainer(); -m_WParser -> OpenContainer(); +m_WParser->CloseContainer(); +m_WParser->OpenContainer(); @endcode and here is image of the situation: @@ -286,14 +277,14 @@ You can see that there was an opened container before the code was executed. We closed it, created our own container, then closed our container and opened new container. -The result was that we had @e same depth level after executing. -This is general rule that should be followed by tag handlers: -leave depth level of containers unmodified (in other words, number of -OpenContainer and CloseContainer calls should be same within -wxHtmlTagHandler::HandleTag's body). +The result was that we had @e same depth level after executing. This is general +rule that should be followed by tag handlers: leave depth level of containers +unmodified (in other words, number of OpenContainer and CloseContainer calls +should be same within wxHtmlTagHandler::HandleTag's body). + +Notice that it would be usually better to use wxHtmlContainerCell::InsertCell +instead of adding text to the parser directly. -Notice that it would be usually better to use wxHtmlContainerCell::InsertCell instead -of adding text to the parser directly. @section overview_html_handlers Tag Handlers @@ -427,19 +418,22 @@ See macros reference: @endcode -@section overview_html_supptags Tags supported by wxHTML + +@section overview_html_supptags Supported HTML Tags wxHTML is not full implementation of HTML standard. Instead, it supports most common tags so that it is possible to display @e simple HTML documents with it. -(For example it works fine with pages created in Netscape Composer or generated by tex2rtf). +(For example it works fine with pages created in Netscape Composer or generated +by tex2rtf). -Following tables list all tags known to wxHTML, together with supported parameters. +Following tables list all tags known to wxHTML, together with supported +parameters. -A tag has general form of @c tagname param_1 param_2 ... param_n where param_i is -either @c paramname="paramvalue" or @c paramname=paramvalue - these two are equivalent. -Unless stated otherwise, wxHTML is case-insensitive. +A tag has general form of @c tagname param_1 param_2 ... param_n where param_i +is either @c paramname="paramvalue" or @c paramname=paramvalue - these two are +equivalent. Unless stated otherwise, wxHTML is case-insensitive. -@subsection overview_html_supptags_commonvalues Table of common parameter values +@subsection overview_html_supptags_commonvalues Common Parameter Values We will use these substitutions in tags descriptions: @@ -484,7 +478,7 @@ We will use these substitutions in tags descriptions: @endcode -@subsection overview_html_supptags_list List of supported tags +@subsection overview_html_supptags_list List of Supported Tags @code A NAME=[string] @@ -577,18 +571,18 @@ U UL @endcode -@subsection overview_html_suppstyles_list List of supported styles +@subsection overview_html_suppstyles_list Supported Styles wxHTML doesn't really have CSS support but it does support a few simple styles: you can use @c "text-align", @c "width", @c "vertical-align" and @c "background" with all elements and for @c SPAN elements a few other styles are additionally recognized: - - @c color - - @c font-family - - @c font-size (only in point units) - - @c font-style (only "oblique", "italic" and "normal" values are supported) - - @c font-weight (only "bold" and "normal" values are supported) - - @c text-decoration (only "underline" value is supported) -*/ +- @c color +- @c font-family +- @c font-size (only in point units) +- @c font-style (only "oblique", "italic" and "normal" values are supported) +- @c font-weight (only "bold" and "normal" values are supported) +- @c text-decoration (only "underline" value is supported) +*/ diff --git a/docs/doxygen/overviews/internationalization.h b/docs/doxygen/overviews/internationalization.h index 1c923bbf54..2af1d2a224 100644 --- a/docs/doxygen/overviews/internationalization.h +++ b/docs/doxygen/overviews/internationalization.h @@ -10,13 +10,7 @@ @page overview_i18n Internationalization -@li @ref overview_i18n_intro -@li @ref overview_i18n_menuaccel - -
    - - -@section overview_i18n_intro Introduction +@tableofcontents Although internationalization of an application (i18n for short) involves far more than just translating its text messages to another message - date, time @@ -70,6 +64,7 @@ Translating your application involves several steps: given language: see wxLocale. + @section overview_i18n_menuaccel Translating Menu Accelerators If you translate the accelerator modifier names (Ctrl, Alt and Shift) in your @@ -87,4 +82,3 @@ translated special key names such as Backspace, End, Insert, etc. @li @ref page_samples_internat - Shows you how all this looks in practice. */ - diff --git a/docs/doxygen/overviews/ipc.h b/docs/doxygen/overviews/ipc.h index 3948cc5319..4f23c3566e 100644 --- a/docs/doxygen/overviews/ipc.h +++ b/docs/doxygen/overviews/ipc.h @@ -10,15 +10,7 @@ @page overview_ipc Interprocess Communication -Classes: wxServer, wxConnection, wxClient - -@li @ref overview_ipc_datatransfer -@li @ref overview_ipc_examples -@li @ref overview_ipc_dde - - -
    - +@tableofcontents wxWidgets has a number of different classes to help with interprocess communication and network programming. This section only discusses one family @@ -216,4 +208,3 @@ connection->StartAdvise("Item"); @endcode */ - diff --git a/docs/doxygen/overviews/listctrl.h b/docs/doxygen/overviews/listctrl.h index 376046477a..e053ecbd35 100644 --- a/docs/doxygen/overviews/listctrl.h +++ b/docs/doxygen/overviews/listctrl.h @@ -10,9 +10,10 @@ @page overview_listctrl wxListCtrl Overview -Classes: wxListCtrl, wxImageList +@tableofcontents -@todo Sorry, this topic hasn't been written yet. +@todo The wxListCtrl topic overview still needs to be written, sorry. -*/ +@see wxListCtrl, wxImageList, wxListItem +*/ diff --git a/docs/doxygen/overviews/log.h b/docs/doxygen/overviews/log.h index 916343b8c2..ecd4f2b9f8 100644 --- a/docs/doxygen/overviews/log.h +++ b/docs/doxygen/overviews/log.h @@ -8,22 +8,9 @@ /** -@page overview_log wxLog Classes Overview +@page overview_log Logging Overview -Classes: wxLog, wxLogStderr, wxLogStream, wxLogTextCtrl, wxLogWindow, wxLogGui, wxLogNull, wxLogBuffer, - wxLogChain, wxLogInterposer, wxLogInterposerTemp, wxStreamToTextRedirector, wxLogFormatter - -Table of contents: -@li @ref overview_log_introduction -@li @ref overview_log_enable -@li @ref overview_log_targets -@li @ref overview_log_mt -@li @ref overview_log_customize -@li @ref overview_log_tracemasks -
    - - -@section overview_log_introduction Introduction +@tableofcontents This is a general overview of logging classes provided by wxWidgets. The word logging here has a broad sense, including all of the program output, not only @@ -75,6 +62,8 @@ of arguments or a variable argument list pointer. Here are all of them: this function takes a trace mask as the first argument which allows to further restrict the amount of messages generated. +@see @ref group_funcmacro_log "Logging Functions and Macros" + The usage of these functions should be fairly straightforward, however it may be asked why not use the other logging facilities, such as C standard stdio functions or C++ streams. The short answer is that they're all very good @@ -111,6 +100,7 @@ classes are. Some of advantages in using wxWidgets log functions are: about data file writing error. + @section overview_log_enable Log Messages Selection By default, most log messages are enabled. In particular, this means that @@ -141,24 +131,28 @@ you could give it the value "MyProgram" by default and re-define it as "MyProgram/DB" in the module working with the database and "MyProgram/DB/Trans" in its part managing the transactions. Then you could use wxLog::SetComponentLevel() in the following ways: - @code - // disable all database error messages, everybody knows databases never - // fail anyhow - wxLog::SetComponentLevel("MyProgram/DB", wxLOG_FatalError); - // but enable tracing for the transactions as somehow our changes don't - // get committed sometimes - wxLog::SetComponentLevel("MyProgram/DB/Trans", wxLOG_Trace); +@code +// disable all database error messages, everybody knows databases never +// fail anyhow +wxLog::SetComponentLevel("MyProgram/DB", wxLOG_FatalError); + +// but enable tracing for the transactions as somehow our changes don't +// get committed sometimes +wxLog::SetComponentLevel("MyProgram/DB/Trans", wxLOG_Trace); + +// also enable tracing messages from wxWidgets dynamic module loading +// mechanism +wxLog::SetComponentLevel("wx/base/module", wxLOG_Trace); +@endcode - // also enable tracing messages from wxWidgets dynamic module loading - // mechanism - wxLog::SetComponentLevel("wx/base/module", wxLOG_Trace); - @endcode Notice that the log level set explicitly for the transactions code overrides the log level of the parent component but that all other database code subcomponents inherit its setting by default and so won't generate any log messages at all. + + @section overview_log_targets Log Targets After having enumerated all the functions which are normally used to log the @@ -170,8 +164,9 @@ from wxLog. As such, it implements the virtual functions of the base class which are called when a message is logged. Only one log target is @e active at any moment, this is the one used by @ref group_funcmacro_log "wxLogXXX() functions". The normal usage of a log object (i.e. object of a class derived from wxLog) is -to install it as the active target with a call to @e SetActiveTarget() and it will be used -automatically by all subsequent calls to @ref group_funcmacro_log "wxLogXXX() functions". +to install it as the active target with a call to @e SetActiveTarget() and it +will be used automatically by all subsequent calls to +@ref group_funcmacro_log "wxLogXXX() functions". To create a new log target class you only need to derive it from wxLog and override one or several of wxLog::DoLogRecord(), wxLog::DoLogTextAtLevel() and @@ -184,7 +179,6 @@ formatting. Finally, it is enough to override wxLog::DoLogText() if you only want to redirect the log messages and the destination doesn't depend on the message log level. - There are some predefined classes deriving from wxLog and which might be helpful to see how you can create a new log target class and, of course, may also be used without any change. There are: @@ -222,12 +216,15 @@ also be used without any change. There are: wxLogMessage("..."); // ok @endcode +@see @ref group_class_logging "Logging Classes" + The log targets can also be combined: for example you may wish to redirect the messages somewhere else (for example, to a log file) but also process them as normally. For this the wxLogChain, wxLogInterposer, and wxLogInterposerTemp can be used. + @section overview_log_mt Logging in Multi-Threaded Applications Starting with wxWidgets 2.9.1, logging functions can be safely called from any @@ -247,6 +244,7 @@ affect the current thread, i.e. logging messages may still be generated by the other threads after a call to @c EnableLogging(false). + @section overview_log_customize Logging Customization To completely change the logging behaviour you may define a custom log target. @@ -294,7 +292,7 @@ The @e dialog sample illustrates this approach by defining a custom log target customizing the dialog used by wxLogGui for the single messages. -@section overview_log_tracemasks Using trace masks +@section overview_log_tracemasks Using Trace Masks Notice that the use of log trace masks is hardly necessary any longer in current wxWidgets version as the same effect can be achieved by using @@ -328,4 +326,3 @@ wxLog::AddTraceMask( wxTRACE_OleCalls ); The standard trace masks are given in wxLogTrace() documentation. */ - diff --git a/docs/doxygen/overviews/mbconvclasses.h b/docs/doxygen/overviews/mbconvclasses.h index cd761c61cd..b26e5015a0 100644 --- a/docs/doxygen/overviews/mbconvclasses.h +++ b/docs/doxygen/overviews/mbconvclasses.h @@ -10,23 +10,14 @@ @page overview_mbconv wxMBConv Overview -Classes: wxMBConv, wxMBConvLibc, wxMBConvUTF7, wxMBConvUTF8, wxCSConv, - wxMBConvUTF16, wxMBConvUTF32 +@tableofcontents The wxMBConv classes in wxWidgets enable an Unicode-aware application to easily convert between Unicode and the variety of 8-bit encoding systems still in use. -@li @ref overview_mbconv_need -@li @ref overview_mbconv_string -@li @ref overview_mbconv_classes -@li @ref overview_mbconv_objects -@li @ref overview_mbconv_csconv -@li @ref overview_mbconv_converting -@li @ref overview_mbconv_buffers +@see @ref group_class_conv -
    - @section overview_mbconv_need Background: The Need for Conversion @@ -190,4 +181,3 @@ reflects the correct return value of cWX2MB (either char* or wxCharBuffer), except for the const. */ - diff --git a/docs/doxygen/overviews/nonenglish.h b/docs/doxygen/overviews/nonenglish.h index 37fc8cae43..dd2e04d70e 100644 --- a/docs/doxygen/overviews/nonenglish.h +++ b/docs/doxygen/overviews/nonenglish.h @@ -10,16 +10,7 @@ @page overview_nonenglish Writing Non-English Applications - -@li @ref overview_nonenglish_locales -@li @ref overview_nonenglish_strings -@li @ref overview_nonenglish_fontmapping -@li @ref overview_nonenglish_converting -@li @ref overview_nonenglish_help - - -
    - +@tableofcontents This article describes how to write applications that communicate with the user in a language other than English. Unfortunately many languages use different @@ -39,6 +30,7 @@ In the following text, wherever @e iso8859-2 and @e windows-1250 are used, any encodings are meant and any encodings may be substituted there. + @section overview_nonenglish_locales Locales The best way to ensure correctly displayed texts in a GUI across platforms is @@ -174,4 +166,3 @@ This additional entry tells the HTML help controller what encoding is used in contents and index tables. */ - diff --git a/docs/doxygen/overviews/persistence.h b/docs/doxygen/overviews/persistence.h index 220e9611b9..47128f81c1 100644 --- a/docs/doxygen/overviews/persistence.h +++ b/docs/doxygen/overviews/persistence.h @@ -12,6 +12,8 @@ @page overview_persistence Persistent Objects Overview +@tableofcontents + Persistent objects are simply the objects which automatically save their state when they are destroyed and restore it when they are recreated, even during another program invocation. @@ -23,53 +25,56 @@ persistence is implemented in a non-intrusive way so that the original object class doesn't need to be modified at all in order to add support for saving and restoring its properties. -The persistence framework involves - - wxPersistenceManager which all persistent objects register themselves with. - This class handles actual saving and restoring of persistent data as well as - various global aspects of persistence, e.g. it can be used to disable - restoring the saved data. - - wxPersistentObject is the base class for all persistent objects or, rather, - adaptors for the persistent objects as this class main purpose is to provide - the bridge between the original class -- which has no special persistence - support -- and wxPersistenceManager, - - wxPersistentWindow<> which derives from wxPersistentObject and implements some - of its methods using wxWindow-specific functionality. Notably, - wxPersistenceManager handles the destruction of persistent windows - automatically implicitly while it has to be done explicitly for the - arbitrary persistent objects. - - wxCreatePersistentObject() function which is used to create the - appropriate persistence adapter for the object. +The persistence framework includes the following components: + +- wxPersistenceManager which all persistent objects register themselves with. + This class handles actual saving and restoring of persistent data as well as + various global aspects of persistence, e.g. it can be used to disable + restoring the saved data. +- wxPersistentObject is the base class for all persistent objects or, rather, + adaptors for the persistent objects as this class main purpose is to provide + the bridge between the original class -- which has no special persistence + support -- and wxPersistenceManager, +- wxPersistentWindow<> which derives from wxPersistentObject and implements some + of its methods using wxWindow-specific functionality. Notably, + wxPersistenceManager handles the destruction of persistent windows + automatically implicitly while it has to be done explicitly for the + arbitrary persistent objects. +- wxCreatePersistentObject() function which is used to create the + appropriate persistence adapter for the object. @section persistence_using Using Persistent Windows wxWidgets has built-in support for a (constantly growing) number of controls. Currently the following classes are supported: - - wxTopLevelWindow (and hence wxFrame and wxDialog) - - wxBookCtrlBase, i.e. wxNotebook, wxListbook, wxToolbook and wxChoicebook - - wxTreebook + +- wxTopLevelWindow (and hence wxFrame and wxDialog) +- wxBookCtrlBase (i.e. wxNotebook, wxListbook, wxToolbook and wxChoicebook) +- wxTreebook To automatically save and restore the properties of the windows of classes -listed above you need to - - -# Set a unique name for the window using wxWindow::SetName(): this step is - important as the name is used in the configuration file and so must be - unique among all windows of the same class. - -# Call wxPersistenceManager::Register() at any moment after creating the - window and then wxPersistenceManager::Restore() when the settings may be - restored (which can't be always done immediately, e.g. often the window - needs to be populated first). If settings can be restored immediately after - the window creation, as is often the case for wxTopLevelWindow, for - example, then wxPersistenceManager::RegisterAndRestore() can be used to do - both at once. - -# If you do not want the settings for the window to be saved (for example - the changes to the dialog size are usually not saved if the dialog was - cancelled), you need to call wxPersistenceManager::Unregister() manually. - Otherwise the settings will be automatically saved when the control itself - is destroyed. +listed above you need to: + +-# Set a unique name for the window using wxWindow::SetName(): this step is + important as the name is used in the configuration file and so must be + unique among all windows of the same class. +-# Call wxPersistenceManager::Register() at any moment after creating the + window and then wxPersistenceManager::Restore() when the settings may be + restored (which can't be always done immediately, e.g. often the window + needs to be populated first). If settings can be restored immediately after + the window creation, as is often the case for wxTopLevelWindow, for + example, then wxPersistenceManager::RegisterAndRestore() can be used to do + both at once. +-# If you do not want the settings for the window to be saved (for example + the changes to the dialog size are usually not saved if the dialog was + cancelled), you need to call wxPersistenceManager::Unregister() manually. + Otherwise the settings will be automatically saved when the control itself + is destroyed. Example of using a notebook control which automatically remembers the last open page: + @code wxNotebook *book = new wxNotebook(parent, wxID_ANY); book->SetName("MyBook"); // do not use the default name @@ -89,15 +94,15 @@ page: User-defined classes can be easily integrated with wxPersistenceManager. To add support for your custom class @c MyWidget you just need to: - -# Define a new @c MyPersistentWidget class inheriting from - wxPersistentWindow. - -# Implement its pure virtual GetKind() method returning a unique string - identifying all @c MyWidget objects, typically something like @c "widget" - -# Implement its pure virtual Save() and Restore() methods to actually save - and restore the widget settings using wxPersistentObject::SaveValue() and - wxPersistentObject::RestoreValue() methods. - -# Define wxCreatePersistentObject() overload taking @c MyWidget * and - returning a new @c MyPersistentWidget object. +-# Define a new @c MyPersistentWidget class inheriting from + wxPersistentWindow. +-# Implement its pure virtual GetKind() method returning a unique string + identifying all @c MyWidget objects, typically something like @c "widget" +-# Implement its pure virtual Save() and Restore() methods to actually save + and restore the widget settings using wxPersistentObject::SaveValue() and + wxPersistentObject::RestoreValue() methods. +-# Define wxCreatePersistentObject() overload taking @c MyWidget * and + returning a new @c MyPersistentWidget object. If you want to add persistence support for a class not deriving from wxWindow, you need to derive @c MyPersistentWidget directly from wxPersistentObject and @@ -106,5 +111,4 @@ Additionally, you must ensure that wxPersistenceManager::SaveAndUnregister() is called when your object is destroyed as this can be only done automatically for windows. - */ - +*/ diff --git a/docs/doxygen/overviews/printing.h b/docs/doxygen/overviews/printing.h index 05b72195dc..7f7850c8ab 100644 --- a/docs/doxygen/overviews/printing.h +++ b/docs/doxygen/overviews/printing.h @@ -10,33 +10,7 @@ @page overview_printing Printing Framework Overview -Classes: -@li wxPrintout -@li wxPrinter -@li wxPrintPreview -@li wxPrinterDC -@li wxPostScriptDC -@li wxPrintDialog -@li wxPrintData -@li wxPrintDialogData -@li wxPageSetupDialog -@li wxPageSetupDialogData - - -@li @ref overview_printing_printout -@li @ref overview_printing_printer -@li @ref overview_printing_printpreview -@li @ref overview_printing_printerdc -@li @ref overview_printing_postscriptdc -@li @ref overview_printing_printdialog -@li @ref overview_printing_printdata -@li @ref overview_printing_printdialogdata -@li @ref overview_printing_pagesetupdialog -@li @ref overview_printing_pagesetupdialogdata - - -
    - +@tableofcontents The printing framework relies on the application to provide classes whose member functions can respond to particular requests, such as 'print this page' @@ -53,6 +27,8 @@ A brief description of each class's role and how they work together follows. For the special case of printing under Unix, where various different printing backends have to be offered, please have a look at @ref overview_unixprinting. +@see @ref group_class_printing + @section overview_printing_printout wxPrintout @@ -227,4 +203,3 @@ range (from the wxPrintDialogData) or the paper size and/or page orientation (from the wxPageSetupDialogData). */ - diff --git a/docs/doxygen/overviews/propgrid.h b/docs/doxygen/overviews/propgrid.h index 7cb6692a71..fd44284491 100644 --- a/docs/doxygen/overviews/propgrid.h +++ b/docs/doxygen/overviews/propgrid.h @@ -10,42 +10,22 @@ @page overview_propgrid wxPropertyGrid Overview -Key Classes: -@li wxPGProperty -@li wxPropertyGrid -@li wxPropertyGridEvent -@li wxPropertyGridManager -@li wxPropertyGridPage - - wxPropertyGrid is a specialized grid for editing properties - in other -words name = value pairs. List of ready-to-use property classes include -strings, numbers, flag sets, fonts, colours and many others. It is possible, -for example, to categorize properties, set up a complete tree-hierarchy, -add more than two columns, and set arbitrary per-property attributes. - - As this version of wxPropertyGrid has some backward-incompatible changes -from version 1.4, everybody who need to maintain custom property classes -should carefully read final section in @ref propgrid_compat. - -@li @ref propgrid_basics -@li @ref propgrid_categories -@li @ref propgrid_parentprops -@li @ref propgrid_enumandflags -@li @ref propgrid_advprops -@li @ref propgrid_processingvalues -@li @ref propgrid_iterating -@li @ref propgrid_events -@li @ref propgrid_tooltipandhint -@li @ref propgrid_validating -@li @ref propgrid_populating -@li @ref propgrid_cellrender -@li @ref propgrid_keyhandling -@li @ref propgrid_customizing -@li @ref propgrid_usage2 -@li @ref propgrid_subclassing -@li @ref propgrid_misc -@li @ref propgrid_proplist -@li @ref propgrid_compat +@tableofcontents + +wxPropertyGrid is a specialized grid for editing properties - in other words +name = value pairs. List of ready-to-use property classes include strings, +numbers, flag sets, fonts, colours and many others. It is possible, for +example, to categorize properties, set up a complete tree-hierarchy, add more +than two columns, and set arbitrary per-property attributes. + +As this version of wxPropertyGrid has some backward-incompatible changes from +version 1.4, everybody who need to maintain custom property classes should +carefully read final section in @ref propgrid_compat. + +@see wxPropertyGrid, wxPropertyGridEvent, wxPropertyGridManager, + wxPropertyGridPage, wxPGProperty + + @section propgrid_basics Creating and Populating wxPropertyGrid diff --git a/docs/doxygen/overviews/python.h b/docs/doxygen/overviews/python.h index 04dde37b1d..113cee52b6 100644 --- a/docs/doxygen/overviews/python.h +++ b/docs/doxygen/overviews/python.h @@ -10,20 +10,11 @@ @page overview_python wxPython Overview +@tableofcontents + This topic was written by Robin Dunn, author of the wxPython wrapper. -@li @ref overview_python_what -@li @ref overview_python_why -@li @ref overview_python_othergui -@li @ref overview_python_using -@li @ref overview_python_classes -@li @ref overview_python_help - - -
    - - @section overview_python_what What is wxPython? wxPython is a blending of the wxWidgets GUI classes and the Python programming @@ -466,4 +457,3 @@ Or you can send mail directly to the list using this address: wxpython-users@lists.wxwidgets.org */ - diff --git a/docs/doxygen/overviews/refcount.h b/docs/doxygen/overviews/refcount.h index 90f392ff3b..bcddbd5e7d 100644 --- a/docs/doxygen/overviews/refcount.h +++ b/docs/doxygen/overviews/refcount.h @@ -10,17 +10,7 @@ @page overview_refcount Reference Counting -@li @ref overview_refcount_ignore -@li @ref overview_refcount_equality -@li @ref overview_refcount_destruct -@li @ref overview_refcount_list -@li @ref overview_refcount_object - - -
    - - -@section overview_refcount_ignore Why You Shouldn't Care About It +@tableofcontents Many wxWidgets objects use a technique known as reference counting, also known as copy on write (COW). This means that when an object is @@ -97,20 +87,20 @@ operators and copy constructors since they are reference-counted: Note that the list above reports the objects which are reference counted in all ports of wxWidgets; some ports may use this technique also for other classes. -All the objects implement a function @b IsOk() to test if they are referencing valid -data; when the objects are in uninitialized state, you can only use the @b IsOk() getter; -trying to call any other getter, e.g. wxBrush::GetStyle() on the ::wxNullBrush object, -will result in an assert failure in debug builds. +All the objects implement a function @b IsOk() to test if they are referencing +valid data; when the objects are in uninitialized state, you can only use the +@b IsOk() getter; trying to call any other getter, e.g. wxBrush::GetStyle() on +the ::wxNullBrush object, will result in an assert failure in debug builds. @section overview_refcount_object Making Your Own Reference Counted Class -Reference counting can be implemented easily using wxObject or using -the intermediate wxRefCounter class directly. -Alternatively, you can also use the wxObjectDataPtr template. +Reference counting can be implemented easily using wxObject or using the +intermediate wxRefCounter class directly. Alternatively, you can also use the +wxObjectDataPtr template. -First, derive a new class from wxRefCounter (or wxObjectRefData when -using a wxObject derived class) and put the memory-consuming data in it. +First, derive a new class from wxRefCounter (or wxObjectRefData when using a +wxObject derived class) and put the memory-consuming data in it. Then derive a new class from wxObject and implement there the public interface which will be seen by the user of your class. You'll probably want to add a @@ -133,4 +123,3 @@ that the modifications won't affect other instances which are eventually sharing your object's data. */ - diff --git a/docs/doxygen/overviews/referencenotes.h b/docs/doxygen/overviews/referencenotes.h index 9c6c6a40c4..42ace33339 100644 --- a/docs/doxygen/overviews/referencenotes.h +++ b/docs/doxygen/overviews/referencenotes.h @@ -10,6 +10,8 @@ @page overview_referencenotes Notes on Using this Reference Manual +@tableofcontents + In the descriptions of the wxWidgets classes and their member functions, note that descriptions of inherited member functions are not duplicated in derived classes unless their behaviour is different. So in using a class such as @@ -20,4 +22,3 @@ value of ::wxDefaultSize and ::wxDefaultPosition, in which case wxWidgets will choose suitable values. */ - diff --git a/docs/doxygen/overviews/resyntax.h b/docs/doxygen/overviews/resyntax.h index acfd276c34..9f4facbde7 100644 --- a/docs/doxygen/overviews/resyntax.h +++ b/docs/doxygen/overviews/resyntax.h @@ -10,26 +10,14 @@ @page overview_resyntax Regular Expressions +@tableofcontents + A regular expression describes strings of characters. It's a pattern that matches certain strings and doesn't match others. -@li @ref overview_resyntax_differentflavors -@li @ref overview_resyntax_syntax -@li @ref overview_resyntax_bracket -@li @ref overview_resyntax_escapes -@li @ref overview_resyntax_metasyntax -@li @ref overview_resyntax_matching -@li @ref overview_resyntax_limits -@li @ref overview_resyntax_bre -@li @ref overview_resyntax_characters - -@see - -@li wxRegEx +@see wxRegEx -
    - @section overview_resyntax_differentflavors Different Flavors of Regular Expressions @@ -662,4 +650,3 @@ Note that the character names are case sensitive. */ - diff --git a/docs/doxygen/overviews/richtextctrl.h b/docs/doxygen/overviews/richtextctrl.h index 9203214d50..120a64791e 100644 --- a/docs/doxygen/overviews/richtextctrl.h +++ b/docs/doxygen/overviews/richtextctrl.h @@ -10,48 +10,7 @@ @page overview_richtextctrl wxRichTextCtrl Overview -@li @ref overview_richtextctrl_classes -@li @ref overview_richtextctrl_intro -@li @ref overview_richtextctrl_example -@li @ref overview_richtextctrl_starting -@li @ref overview_richtextctrl_styles -@li @ref overview_richtextctrl_dialogs -@li @ref overview_richtextctrl_impl -@li @ref overview_richtextctrl_nested_object -@li @ref overview_richtextctrl_context_menus -@li @ref overview_richtextctrl_roadmap - - -
    - - -@section overview_richtextctrl_classes Related Classes - -Major classes: -wxRichTextCtrl, wxRichTextBuffer, wxRichTextEvent - -Helper classes: -wxTextAttr, wxRichTextRange - -File handler classes: -wxRichTextFileHandler, wxRichTextHTMLHandler, wxRichTextXMLHandler - -Style classes: -wxRichTextCharacterStyleDefinition, wxRichTextParagraphStyleDefinition, -wxRichTextListStyleDefinition, wxRichTextStyleSheet - -Additional controls: -wxRichTextStyleComboCtrl, wxRichTextStyleListBox, wxRichTextStyleListCtrl - -Printing classes: -wxRichTextPrinting, wxRichTextPrintout, wxRichTextHeaderFooterData - -Dialog classes: -wxRichTextStyleOrganiserDialog, wxRichTextFormattingDialog, -wxSymbolPickerDialog - - -@section overview_richtextctrl_intro Introduction +@tableofcontents wxRichTextCtrl provides a generic implementation of a rich text editor that can handle different character styles, paragraph formatting, and images. It's aimed @@ -60,9 +19,9 @@ editing, wxStyledTextCtrl is a better choice. Despite its name, it cannot currently read or write RTF (rich text format) files. Instead, it uses its own XML format, and can also read and write plain -text. In future we expect to provide RTF or OpenDocument file capabilities. Custom file formats -can be supported by creating additional file handlers and registering them with -the control. +text. In future we expect to provide RTF or OpenDocument file capabilities. +Custom file formats can be supported by creating additional file handlers and +registering them with the control. wxRichTextCtrl is largely compatible with the wxTextCtrl API, but extends it where necessary. The control can be used where the native rich text @@ -94,6 +53,33 @@ A good way to understand wxRichTextCtrl's capabilities is to compile and run the sample, @c samples/richtext, and browse the code. + +@section overview_richtextctrl_classes Related Classes + +Major classes: +wxRichTextCtrl, wxRichTextBuffer, wxRichTextEvent + +Helper classes: +wxTextAttr, wxRichTextRange + +File handler classes: +wxRichTextFileHandler, wxRichTextHTMLHandler, wxRichTextXMLHandler + +Style classes: +wxRichTextCharacterStyleDefinition, wxRichTextParagraphStyleDefinition, +wxRichTextListStyleDefinition, wxRichTextStyleSheet + +Additional controls: +wxRichTextStyleComboCtrl, wxRichTextStyleListBox, wxRichTextStyleListCtrl + +Printing classes: +wxRichTextPrinting, wxRichTextPrintout, wxRichTextHeaderFooterData + +Dialog classes: +wxRichTextStyleOrganiserDialog, wxRichTextFormattingDialog, +wxSymbolPickerDialog + + @section overview_richtextctrl_example Code Example The following code is an example taken from the sample, and adds text and @@ -416,54 +402,65 @@ objects with the same style where just one would do. So a Defragment function is called when updating the control's display, to ensure that the minimum number of objects is used. + @section overview_richtextctrl_nested_object Nested Objects -wxRichTextCtrl supports nested objects such as text boxes and tables. To achieve -compatibility with the existing API, there is the concept of @e object @e focus. -When the user clicks on a nested text box, the object focus is set to that -container object so all keyboard input and API functions apply to that -container. The application can change the focus using wxRichTextCtrl::SetObjectFocus. -Call this function with a @null parameter to set the focus back to the top-level -object. +wxRichTextCtrl supports nested objects such as text boxes and tables. To +achieve compatibility with the existing API, there is the concept of @e object +@e focus. When the user clicks on a nested text box, the object focus is set to +that container object so all keyboard input and API functions apply to that +container. The application can change the focus using +wxRichTextCtrl::SetObjectFocus. Call this function with a @c null parameter to +set the focus back to the top-level object. An event will be sent to the control when the focus changes. -When the user clicks on the control, wxRichTextCtrl determines which container to set -as the current object focus by calling the found container's overrided wxRichTextObject::AcceptsFocus -function. For example, although a table is a container, it must not itself be -the object focus because there is no text editing at the table level. Instead, a cell -within the table must accept the focus. +When the user clicks on the control, wxRichTextCtrl determines which container +to set as the current object focus by calling the found container's overrided +wxRichTextObject::AcceptsFocus function. For example, although a table is a +container, it must not itself be the object focus because there is no text +editing at the table level. Instead, a cell within the table must accept the +focus. Since with nested objects it is not possible to represent a section with merely a start position and an end position, the class wxRichTextSelection is provided -which stores multiple ranges (for non-contiguous selections such as table cells) and -a pointer to the container object in question. You can pass wxRichTextSelection -to wxRichTextCtrl::SetSelection or get an instance of it from wxRichTextCtrl::GetSelection. - -When selecting multiple objects, such as cell tables, the wxRichTextCtrl dragging handler code calls the -function wxRichTextObject::HandlesChildSelections to determine whether the children -can be individual selections. Currently only table cells can be multiply-selected +which stores multiple ranges (for non-contiguous selections such as table +cells) and a pointer to the container object in question. You can pass +wxRichTextSelection to wxRichTextCtrl::SetSelection or get an instance of it +from wxRichTextCtrl::GetSelection. + +When selecting multiple objects, such as cell tables, the wxRichTextCtrl +dragging handler code calls the function +wxRichTextObject::HandlesChildSelections to determine whether the children can +be individual selections. Currently only table cells can be multiply-selected in this way. -@section overview_richtextctrl_context_menus Context menus and property dialogs -There are three ways you can make use of context menus: you can let wxRichTextCtrl handle everything and provide a basic menu; -you can set your own context menu using wxRichTextCtrl::SetContextMenu but let wxRichTextCtrl handle showing it and adding property items; -or you can override the default context menu behaviour by adding a context menu event handler -to your class in the normal way. +@section overview_richtextctrl_context_menus Context Menus and Property Dialogs -If you right-click over a text box in cell in a table, you may want to edit the properties of -one of these objects - but which properties will you be editing? +There are three ways you can make use of context menus: you can let +wxRichTextCtrl handle everything and provide a basic menu; you can set your own +context menu using wxRichTextCtrl::SetContextMenu but let wxRichTextCtrl handle +showing it and adding property items; or you can override the default context +menu behaviour by adding a context menu event handler to your class in the +normal way. -Well, the default behaviour allows up to three property-editing menu items simultaneously - for the object clicked on, -the container of that object, and the container's parent (depending on whether any of these -objects return @true from their wxRichTextObject::CanEditProperties functions). -If you supply a context menu, add a property command item using the wxID_RICHTEXT_PROPERTIES1 identifier, -so that wxRichTextCtrl can find the position to add command items. The object should -tell the control what label to use by returning a string from wxRichTextObject::GetPropertiesMenuLabel. +If you right-click over a text box in cell in a table, you may want to edit the +properties of one of these objects - but which properties will you be editing? + +Well, the default behaviour allows up to three property-editing menu items +simultaneously - for the object clicked on, the container of that object, and +the container's parent (depending on whether any of these objects return @true +from their wxRichTextObject::CanEditProperties functions). If you supply a +context menu, add a property command item using the wxID_RICHTEXT_PROPERTIES1 +identifier, so that wxRichTextCtrl can find the position to add command items. +The object should tell the control what label to use by returning a string from +wxRichTextObject::GetPropertiesMenuLabel. + +Since there may be several property-editing commands showing, it is recommended +that you don't include the word Properties - just the name of the object, such +as Text Box or Table. -Since there may be several property-editing commands showing, it is recommended that you don't -include the word Properties - just the name of the object, such as Text Box or Table. @section overview_richtextctrl_roadmap Development Roadmap @@ -504,4 +501,3 @@ high level to low level wxDC API is unnecessary. However this would require additions to the wxWidgets API. */ - diff --git a/docs/doxygen/overviews/roughguide.h b/docs/doxygen/overviews/roughguide.h index 227c83a7fa..db27c1c3fa 100644 --- a/docs/doxygen/overviews/roughguide.h +++ b/docs/doxygen/overviews/roughguide.h @@ -10,6 +10,8 @@ @page overview_roughguide A Quick Guide to Writing Applications +@tableofcontents + To set a wxWidgets application going, you will need to derive a wxApp class and override wxApp::OnInit. @@ -54,9 +56,6 @@ platform-independent @ref group_funcmacro_file, and you may find it handy to maintain and search a list of paths using wxPathList. There's many @ref group_funcmacro_misc of operating system methods and other functions. -@see - -@li @ref group_class +@see @ref group_class */ - diff --git a/docs/doxygen/overviews/runtimeclass.h b/docs/doxygen/overviews/runtimeclass.h index 6f6638dc6c..9176c8043a 100644 --- a/docs/doxygen/overviews/runtimeclass.h +++ b/docs/doxygen/overviews/runtimeclass.h @@ -10,20 +10,7 @@ @page overview_rtti Runtime Type Information (RTTI) -@li @ref overview_rtti_intro -@li @ref overview_rtti_classinfo -@li @ref overview_rtti_example - -@see - -@li wxObject -@li wxClassInfo - - -
    - - -@section overview_rtti_intro Introduction +@tableofcontents One of the failings of C++ used to be that no runtime information was provided about a class and its position in the inheritance hierarchy. Another, which @@ -72,6 +59,8 @@ The function wxCreateDynamicObject can be used to construct a new object of a given type, by supplying a string name. If you have a pointer to the wxClassInfo object instead, then you can simply call wxClassInfo::CreateObject. +@see wxObject + @section overview_rtti_classinfo wxClassInfo @@ -93,11 +82,6 @@ You can get the wxClassInfo for a class by using the CLASSINFO macro, e.g. CLASSINFO(wxFrame). You can get the wxClassInfo for an object using wxObject::GetClassInfo. -@see - -@li wxObject -@li wxCreateDynamicObject - @section overview_rtti_example Example @@ -128,4 +112,3 @@ wxFrame::wxFrame() @endcode */ - diff --git a/docs/doxygen/overviews/scrolling.h b/docs/doxygen/overviews/scrolling.h index c28cd77248..a3a70f814c 100644 --- a/docs/doxygen/overviews/scrolling.h +++ b/docs/doxygen/overviews/scrolling.h @@ -10,13 +10,7 @@ @page overview_scrolling Scrolled Windows -Classes: wxWindow, wxScrolledWindow, wxScrollBar - -@li @ref overview_scrolling_model -@li @ref overview_scrolling_example - -
    - +@tableofcontents Scrollbars come in various guises in wxWidgets. All windows have the potential to show a vertical scrollbar and/or a horizontal scrollbar: it is a basic @@ -42,6 +36,8 @@ this, you would derive from wxWindow and implement scrolling yourself. wxGrid is an example of a class that implements its own scrolling, largely because columns and rows can vary in size. +@see wxScrollBar + @section overview_scrolling_model The Scrollbar Model @@ -98,4 +94,3 @@ AdjustScrollbars, which can be called initially and also from your wxSizeEvent handler function. */ - diff --git a/docs/doxygen/overviews/sizer.h b/docs/doxygen/overviews/sizer.h index e551e6af79..a2401c1526 100644 --- a/docs/doxygen/overviews/sizer.h +++ b/docs/doxygen/overviews/sizer.h @@ -10,8 +10,7 @@ @page overview_sizer Sizers Overview -Classes: wxSizer, wxBoxSizer, wxStaticBoxSizer, wxGridSizer, wxFlexGridSizer, - wxGridBagSizer +@tableofcontents Sizers, as represented by the wxSizer class and its descendants in the wxWidgets class hierarchy, have become the method of choice to define the @@ -29,16 +28,10 @@ classes. For information about the wxWidgets resource system, which can describe sizer-based dialogs, see the @ref overview_xrc. -@li @ref overview_sizer_idea -@li @ref overview_sizer_features -@li @ref overview_sizer_hiding -@li @ref overview_sizer_box -@li @ref overview_sizer_types -@li @ref overview_sizer_button +@see wxSizer, wxBoxSizer, wxStaticBoxSizer, wxGridSizer, wxFlexGridSizer, + wxGridBagSizer -
    - @section overview_sizer_idea The Idea Behind Sizers @@ -368,4 +361,3 @@ wxMORE // return wxID_MORE @endcode */ - diff --git a/docs/doxygen/overviews/splitterwindow.h b/docs/doxygen/overviews/splitterwindow.h index 42e6f19d49..17cbfdf965 100644 --- a/docs/doxygen/overviews/splitterwindow.h +++ b/docs/doxygen/overviews/splitterwindow.h @@ -10,12 +10,10 @@ @page overview_splitterwindow wxSplitterWindow Overview -Classes: wxSplitterWindow +@tableofcontents -@li @ref overview_splitterwindow_appearance -@li @ref overview_splitterwindow_example +@see wxSplitterWindow -
    @section overview_splitterwindow_appearance Appearance @@ -80,4 +78,3 @@ void MyFrame::OnUnsplit(wxCommandEvent& event) @endcode */ - diff --git a/docs/doxygen/overviews/stream.h b/docs/doxygen/overviews/stream.h index 683f64f01f..bddc36e83f 100644 --- a/docs/doxygen/overviews/stream.h +++ b/docs/doxygen/overviews/stream.h @@ -8,32 +8,9 @@ /** -@page overview_stream Stream classes overview +@page overview_stream Stream Classes Overview -Classes: -@li wxStreamBase -@li wxStreamBuffer -@li wxInputStream -@li wxOutputStream -@li wxFilterInputStream -@li wxFilterOutputStream -@li wxFileInputStream -@li wxFileOutputStream -@li wxTextInputStream -@li wxTextOutputStream -@li wxDataInputStream -@li wxDataOutputStream - -@li @ref overview_stream_intro -@li @ref overview_stream_example - -
    - - - -@section overview_stream_intro Introduction - -@subsection overview_stream_intro_std wxWidgets and Standard Streams +@tableofcontents wxWidgets provides its own set of stream classes in order to support platforms not providing standard C++ streams implementation and also to make it possible @@ -51,7 +28,8 @@ stream as a standard stream (the converse possibility to use a standard stream as a wxWidgets stream is planned for a future release). -@subsection overview_stream_intro_overview Stream Classes + +@section overview_stream_classes Stream Classes wxStream classes are divided in two main groups: @@ -126,4 +104,3 @@ off_t position = in_stream.TellI(); @endcode */ - diff --git a/docs/doxygen/overviews/string.h b/docs/doxygen/overviews/string.h index 927a208d0e..5f67766e46 100644 --- a/docs/doxygen/overviews/string.h +++ b/docs/doxygen/overviews/string.h @@ -10,22 +10,7 @@ @page overview_string wxString Overview -Classes: wxString, wxArrayString, wxStringTokenizer - -@li @ref overview_string_intro -@li @ref overview_string_internal -@li @ref overview_string_binary -@li @ref overview_string_comparison -@li @ref overview_string_advice -@li @ref overview_string_related -@li @ref overview_string_tuning -@li @ref overview_string_settings - - -
    - - -@section overview_string_intro Introduction +@tableofcontents wxString is a class which represents a Unicode string of arbitrary length and containing arbitrary Unicode characters. @@ -44,7 +29,7 @@ has been done to make existing code using ANSI string literals work as it did in previous versions. -@section overview_string_internal Internal wxString encoding +@section overview_string_internal Internal wxString Encoding Since wxWidgets 3.0 wxString internally uses UTF-16 (with Unicode code units stored in @c wchar_t) under Windows and UTF-8 (with Unicode @@ -246,7 +231,7 @@ For this conversion, the @a wxConvLibc class instance is used. See wxCSConv and wxMBConv. -@subsection overview_string_iterating Iterating wxString's characters +@subsection overview_string_iterating Iterating wxString Characters As previously described, when wxUSE_UNICODE_UTF8==1, wxString internally uses the variable-length UTF8 encoding. @@ -288,7 +273,7 @@ these problems: wxIsEmpty() verifies whether the string is empty (returning case-insensitive string comparison function known either as @c stricmp() or @c strcasecmp() on different platforms. -The @ header also defines ::wxSnprintf and ::wxVsnprintf +The @ header also defines wxSnprintf() and wxVsnprintf() functions which should be used instead of the inherently dangerous standard @c sprintf() and which use @c snprintf() instead which does buffer size checks whenever possible. Of course, you may also use wxString::Printf which is also @@ -391,4 +376,3 @@ also defined, otherwise @c wxUSE_UNICODE_WCHAR is. See also @ref page_wxusedef_important. */ - diff --git a/docs/doxygen/overviews/thread.h b/docs/doxygen/overviews/thread.h index b77bab7f9b..6f065ee853 100644 --- a/docs/doxygen/overviews/thread.h +++ b/docs/doxygen/overviews/thread.h @@ -15,50 +15,52 @@ @page overview_thread Multithreading Overview -Classes: wxThread, wxThreadHelper, wxMutex, wxCriticalSection, wxCondition, wxSemaphore - - -@section overview_thread_intro When to use multiple threads +@tableofcontents wxWidgets provides a complete set of classes encapsulating objects necessary in -multithreaded (MT) programs: the wxThread class itself and different +multi-threaded (MT) applications: the wxThread class itself and different synchronization objects: mutexes (see wxMutex) and critical sections (see -wxCriticalSection) with conditions (see wxCondition). The thread API in +wxCriticalSection) with conditions (see wxCondition). The thread API in wxWidgets resembles to POSIX1.c threads API (a.k.a. pthreads), although several functions have different names and some features inspired by Win32 thread API are there as well. -These classes hopefully make writing MT programs easier and they also -provide some extra error checking (compared to the native - be it Win32 or -Posix - thread API), however it is still a non-trivial undertaking especially -for large projects. -Before starting an MT application (or starting to add MT -features to an existing one) it is worth asking oneself if there is no easier -and safer way to implement the same functionality. -Of course, in some situations threads really make sense (classical example is a -server application which launches a new thread for each new client), but in others -it might be an overkill. -On the other hand, the recent evolution of the computer hardware shows -an important trend towards multi-core systems, which are better exploited using -multiple threads (e.g. you may want to split a long task among as many threads -as many CPU (cores) the system reports; see wxThread::GetCPUCount). +These classes hopefully make writing MT programs easier and they also provide +some extra error checking (compared to the native - be it Win32 or Posix - +thread API), however it is still a non-trivial undertaking especially for large +projects. Before starting an MT application (or starting to add MT features to +an existing one) it is worth asking oneself if there is no easier and safer way +to implement the same functionality. Of course, in some situations threads +really make sense (classical example is a server application which launches a +new thread for each new client), but in others it might be an overkill. On the +other hand, the recent evolution of the computer hardware shows an important +trend towards multi-core systems, which are better exploited using multiple +threads (e.g. you may want to split a long task among as many threads as many +CPU (cores) the system reports; see wxThread::GetCPUCount). To implement non-blocking operations @e without using multiple threads you have two possible implementation choices: + - use wxIdleEvent (e.g. to perform a long calculation while updating a progress dialog) - do everything at once but call wxWindow::Update() or wxApp::YieldFor(wxEVT_CATEGORY_UI) periodically to update the screen. -If instead you choose to use threads in your application, please read also -the following sections of this overview. -@section overview_thread_notes Important notes for multithreaded applications +If instead you choose to use threads in your application, please read the +following section of this overview. + +@see wxThread, wxThreadHelper, wxMutex, wxCriticalSection, wxCondition, + wxSemaphore -When writing a multi-threaded application, it is strongly recommended -that no secondary threads call GUI functions. -The design which uses one GUI thread and several worker threads which communicate -with the main one using @b events is much more robust and will undoubtedly save you -countless problems (example: under Win32 a thread can only access GDI objects such -as pens, brushes, device contexts created by itself and not by the other threads). + + +@section overview_thread_notes Important Notes for Multi-threaded Applications + +When writing a multi-threaded application, it is strongly recommended that +no secondary threads call GUI functions. The design which uses one GUI +thread and several worker threads which communicate with the main one using +@b events is much more robust and will undoubtedly save you countless problems +(example: under Win32 a thread can only access GDI objects such as pens, +brushes, device contexts created by itself and not by the other threads). For communication between secondary threads and the main thread, you may use wxEvtHandler::QueueEvent or its short version ::wxQueueEvent. These functions @@ -66,25 +68,23 @@ have a thread-safe implementation so that they can be used as they are for sending events from one thread to another. However there is no built in method to send messages to the worker threads and you will need to use the available synchronization classes to implement the solution which suits your needs -yourself. In particular, please note that it is not enough to derive -your class from wxThread and wxEvtHandler to send messages to it: in fact, this -does not work at all. -You're instead encouraged to use wxThreadHelper as it greatly simplifies the -communication and the sharing of resources. +yourself. In particular, please note that it is not enough to derive your class +from wxThread and wxEvtHandler to send messages to it: in fact, this does not +work at all. You're instead encouraged to use wxThreadHelper as it greatly +simplifies the communication and the sharing of resources. You should also look at the wxThread docs for important notes about secondary threads and their deletion. -Last, remember that if wxEventLoopBase::YieldFor() is used directly or indirectly -(e.g. through wxProgressDialog) in your code, then you may have both re-entrancy -problems and also problems caused by the processing of events out of order. -To resolve the last problem wxThreadEvent can be used: thanks to its implementation -of the wxThreadEvent::GetEventCategory function wxThreadEvent classes in fact -do not get processed by wxEventLoopBase::YieldFor() unless you specify the -@c wxEVT_CATEGORY_THREAD flag. +Last, remember that if wxEventLoopBase::YieldFor() is used directly or +indirectly (e.g. through wxProgressDialog) in your code, then you may have both +re-entrancy problems and also problems caused by the processing of events out +of order. To resolve the last problem wxThreadEvent can be used: thanks to its +implementation of the wxThreadEvent::GetEventCategory function wxThreadEvent +classes in fact do not get processed by wxEventLoopBase::YieldFor() unless you +specify the @c wxEVT_CATEGORY_THREAD flag. See also the @sample{thread} for a sample showing some simple interactions between the main and secondary threads. */ - diff --git a/docs/doxygen/overviews/tips.h b/docs/doxygen/overviews/tips.h index 304757e8b6..4db5e7c611 100644 --- a/docs/doxygen/overviews/tips.h +++ b/docs/doxygen/overviews/tips.h @@ -10,6 +10,8 @@ @page overview_tips wxTipProvider Overview +@tableofcontents + Many "modern" Windows programs have a feature (some would say annoyance) of presenting the user tips at program startup. While this is probably useless to the advanced users of the program, the experience shows that the tips may be @@ -73,4 +75,3 @@ See the dialogs program in your samples folder for a working example inside a program. */ - diff --git a/docs/doxygen/overviews/toolbar.h b/docs/doxygen/overviews/toolbar.h index 7b10dddea6..840071fafb 100644 --- a/docs/doxygen/overviews/toolbar.h +++ b/docs/doxygen/overviews/toolbar.h @@ -10,16 +10,7 @@ @page overview_toolbar Toolbar Overview -Classes: wxToolBar - -@li @ref overview_toolbar_intro -@li @ref overview_toolbar_library - - -
    - - -@section overview_toolbar_intro Introduction +@tableofcontents The toolbar family of classes allows an application to use toolbars in a variety of configurations and styles. @@ -90,4 +81,3 @@ Include @c "wx/toolbar.h", or if using a class directly, one of: An example of using a toolbar is given in the "toolbar" sample. */ - diff --git a/docs/doxygen/overviews/treectrl.h b/docs/doxygen/overviews/treectrl.h index 9a3f58ec92..330d928870 100644 --- a/docs/doxygen/overviews/treectrl.h +++ b/docs/doxygen/overviews/treectrl.h @@ -10,7 +10,7 @@ @page overview_treectrl wxTreeCtrl Overview -Classes: wxTreeCtrl, wxImageList +@tableofcontents The tree control displays its items in a tree like structure. Each item has its own (optional) icon and a label. An item may be either collapsed (meaning @@ -19,6 +19,8 @@ shown). Each item in the tree is identified by its @c itemId which is of opaque data type wxTreeItemId. You can test whether an item is valid by calling wxTreeItemId::IsOk. +@see wxTreeCtrl, wxImageList + The items text and image may be retrieved and changed with (Get|Set)ItemText and (Get|Set)ItemImage. In fact, an item may even have two images associated with it: the normal one and another one for selected state which is @@ -79,4 +81,3 @@ nothing by default, but it is common to associate them with deleting an item from a tree and inserting a new one into it. */ - diff --git a/docs/doxygen/overviews/unicode.h b/docs/doxygen/overviews/unicode.h index 4e9dbe01ba..2f42904b30 100644 --- a/docs/doxygen/overviews/unicode.h +++ b/docs/doxygen/overviews/unicode.h @@ -10,6 +10,8 @@ @page overview_unicode Unicode Support in wxWidgets +@tableofcontents + This section describes how does wxWidgets support Unicode and how can it affect your programs. @@ -19,14 +21,8 @@ correct any more. Please see @ref overview_changes_unicode for the details of these changes. You can skip the first two sections if you're already familiar with Unicode and -wish to jump directly in the details of its support in the library: -@li @ref overview_unicode_what -@li @ref overview_unicode_encodings -@li @ref overview_unicode_supportin -@li @ref overview_unicode_pitfalls -@li @ref overview_unicode_supportout +wish to jump directly in the details of its support in the library. -
    @section overview_unicode_what What is Unicode? @@ -436,4 +432,3 @@ the return value of any of the functions mentioned in this section to another function directly. */ - diff --git a/docs/doxygen/overviews/unixprinting.h b/docs/doxygen/overviews/unixprinting.h index 2a03eab76b..75134030f3 100644 --- a/docs/doxygen/overviews/unixprinting.h +++ b/docs/doxygen/overviews/unixprinting.h @@ -10,6 +10,8 @@ @page overview_unixprinting Printing Under Unix (GTK+) +@tableofcontents + Printing under Unix has always been a cause of problems as Unix does not provide a standard way to display text and graphics on screen and print it to a printer using the same application programming interface - instead, displaying @@ -43,4 +45,3 @@ code. Note that the application will not require a GTK+ version = 2.10 to be installed in order to run (there will be no dependency on this version). */ - diff --git a/docs/doxygen/overviews/validator.h b/docs/doxygen/overviews/validator.h index 81010b915f..e57cf9564b 100644 --- a/docs/doxygen/overviews/validator.h +++ b/docs/doxygen/overviews/validator.h @@ -10,18 +10,7 @@ @page overview_validator wxValidator Overview -Classes: wxValidator, wxTextValidator, wxGenericValidator, wxIntegerValidator, -wxFloatingPointValidator - -@li @ref overview_validator_intro -@li @ref overview_validator_anatomy -@li @ref overview_validator_dialogs - - -
    - - -@section overview_validator_intro Validator basic concepts +@tableofcontents The aim of the validator concept is to make dialogs very much easier to write. A validator is an object that can be plugged into a control (such as a @@ -63,6 +52,10 @@ giving the error, and the dialog is not dismissed. Note that any wxWindow may have a validator; using the @c wxWS_EX_VALIDATE_RECURSIVELY style (see wxWindow extended styles) you can also implement recursive validation. +@see wxValidator, wxTextValidator, wxGenericValidator, wxIntegerValidator, + wxFloatingPointValidator + + @section overview_validator_anatomy Anatomy of a Validator @@ -147,4 +140,3 @@ the controls setting validators, since validators can't be specified in a dialog resource. */ - diff --git a/docs/doxygen/overviews/windowdeletion.h b/docs/doxygen/overviews/windowdeletion.h index d9443b79ab..c4b5d704ce 100644 --- a/docs/doxygen/overviews/windowdeletion.h +++ b/docs/doxygen/overviews/windowdeletion.h @@ -10,23 +10,15 @@ @page overview_windowdeletion Window Deletion -Classes: wxCloseEvent, wxWindow +@tableofcontents Window deletion can be a confusing subject, so this overview is provided to help make it clear when and how you delete windows, or respond to user requests to close windows. -@li @ref overview_windowdeletion_sequence -@li @ref overview_windowdeletion_close -@li @ref overview_windowdeletion_default -@li @ref overview_windowdeletion_menuexit -@li @ref overview_windowdeletion_exitapp -@li @ref overview_windowdeletion_deletion -@li @ref overview_windowdeletion_windowkinds +@see wxCloseEvent, wxWindow -
    - @section overview_windowdeletion_sequence Sequence of Events During Window Deletion @@ -118,4 +110,3 @@ wish. For consistency, continue to use the wxWindow::Destroy function instead of the @c delete operator when deleting these kinds of windows explicitly. */ - diff --git a/docs/doxygen/overviews/windowids.h b/docs/doxygen/overviews/windowids.h index 7bfc294d06..169383f473 100644 --- a/docs/doxygen/overviews/windowids.h +++ b/docs/doxygen/overviews/windowids.h @@ -10,21 +10,7 @@ @page overview_windowids Window IDs -@li @ref overview_windowids_intro -@li @ref overview_windowids_type -@li @ref overview_windowids_using - -@see - -@li wxIdManager -@li wxWindow::NewControlId -@li wxWindow::UnreserveControlId - - -
    - - -@section overview_windowids_intro Introduction +@tableofcontents Various controls and other parts of wxWidgets need an ID. Sometimes the ID may be directly provided by the user or have a predefined value, such as @@ -50,6 +36,8 @@ one another. This is accomplished by keeping a reference count for each of the IDs that can possibly be returned by wxWindow::NewControlId. Other IDs are not reference counted. +@see wxIdManager, wxWindow::NewControlId(), wxWindow::UnreserveControlId() + @section overview_windowids_type Data Types @@ -85,4 +73,3 @@ This is done already for windows, menu items, and tool bar items. It should only be used in the main thread, as it is not thread safe. */ - diff --git a/docs/doxygen/overviews/windowsizing.h b/docs/doxygen/overviews/windowsizing.h index baf7611eb5..b9db95cbf5 100644 --- a/docs/doxygen/overviews/windowsizing.h +++ b/docs/doxygen/overviews/windowsizing.h @@ -10,16 +10,13 @@ @page overview_windowsizing Window Sizing Overview +@tableofcontents + It can sometimes be confusing to keep track of the various size-related attributes of a wxWindow, how they relate to each other, and how they interact with sizers. This document will attempt to clear the fog a little, and give some simple explanations of things. -@li @ref overview_windowsizing_glossary -@li @ref overview_windowsizing_func - - -
    @section overview_windowsizing_glossary Glossary @@ -121,4 +118,3 @@ some simple explanations of things. the default @c EVT_SIZE handler for container windows. */ - diff --git a/docs/doxygen/overviews/windowstyles.h b/docs/doxygen/overviews/windowstyles.h index 25e4141618..12d2bd8246 100644 --- a/docs/doxygen/overviews/windowstyles.h +++ b/docs/doxygen/overviews/windowstyles.h @@ -10,6 +10,8 @@ @page overview_windowstyles Window Styles +@tableofcontents + Window styles are used to specify alternative behaviour and appearances for windows, when they are created. The symbols are defined in such a way that they can be combined in a 'bit-list' using the C++ @e bitwise-or operator. @@ -27,4 +29,3 @@ Most windows can use the generic styles listed for wxWindow in addition to their own styles. */ - diff --git a/docs/doxygen/overviews/xrc.h b/docs/doxygen/overviews/xrc.h index d9d126fe6a..31ea4378da 100644 --- a/docs/doxygen/overviews/xrc.h +++ b/docs/doxygen/overviews/xrc.h @@ -10,7 +10,7 @@ @page overview_xrc XML Based Resource System (XRC) -Classes: wxXmlResource, wxXmlResourceHandler +@tableofcontents The XML-based resource system, known as XRC, allows user interface elements such as dialogs, menu bars and toolbars, to be stored in text files and loaded @@ -36,15 +36,8 @@ There are several advantages to using XRC resources: XRC was written by Vaclav Slavik. -@li @ref overview_xrc_gettingstarted -@li @ref overview_xrc_xrcsample -@li @ref overview_xrc_binaryresourcefiles -@li @ref overview_xrc_embeddedresource -@li @ref overview_xrc_cppheader -@li @ref overview_xrc_newresourcehandlers +@see wxXmlResource, wxXmlResourceHandler, @ref overview_xrcformat -See also the separate @ref overview_xrcformat page for more information, and -details about the XRC file format. @section overview_xrc_gettingstarted Getting Started with XRC @@ -545,4 +538,3 @@ built-in getters it contains. It's very easy to retrieve also complex structures out of XRC files using them. */ - diff --git a/docs/doxygen/overviews/xrc_format.h b/docs/doxygen/overviews/xrc_format.h index 5ff844aa2a..4246a0ab73 100644 --- a/docs/doxygen/overviews/xrc_format.h +++ b/docs/doxygen/overviews/xrc_format.h @@ -18,34 +18,10 @@ @page overview_xrcformat XRC File Format -Table of contents: -- @ref overview_xrcformat_overview -- @ref overview_xrcformat_root -- @ref overview_xrcformat_objects - - @ref overview_xrcformat_object - - @ref overview_xrcformat_object_ref -- @ref overview_xrcformat_datatypes -- @ref overview_xrcformat_windows - - @ref overview_xrcformat_std_props - - @ref overview_xrcformat_controls -- @ref overview_xrcformat_sizers -- @ref overview_xrcformat_other_objects -- @ref overview_xrcformat_platform -- @ref overview_xrcformat_idranges -- @ref overview_xrcformat_extending - - @ref overview_xrcformat_extending_subclass - - @ref overview_xrcformat_extending_unknown - - @ref overview_xrcformat_extending_custom -- @ref overview_xrcformat_packed -- @ref overview_xrcformat_oldversions - -This document describes the format of XRC resource files, as used by wxXmlResource. - - -
    - - -@section overview_xrcformat_overview Overview +@tableofcontents + +This document describes the format of XRC resource files, as used by +wxXmlResource. XRC file is a XML file with all of its elements in the @c http://www.wxwidgets.org/wxxrc namespace. For backward compatibility, @@ -66,6 +42,7 @@ Child objects are not directly accessible via wxXmlResource, they can only be accessed using XRCCTRL(). + @section overview_xrcformat_root Resource Root Element The root element is always @c \. It has one optional attribute, @c diff --git a/interface/wx/event.h b/interface/wx/event.h index 237e8480e8..0f80baa580 100644 --- a/interface/wx/event.h +++ b/interface/wx/event.h @@ -4315,7 +4315,7 @@ public: See the macro DEFINE_EVENT_TYPE() for more info. - @see @ref overview_events_introduction + @see @ref overview_events */ typedef int wxEventType;