From 3863c5ebd92650ba88f29db4f5f8d794ec11bf80 Mon Sep 17 00:00:00 2001 From: Bryan Petty Date: Sun, 2 Mar 2008 10:48:31 +0000 Subject: [PATCH] More doxygen topic overview cleanup. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52244 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/overviews/unicode.h | 2 +- docs/doxygen/overviews/validator.h | 245 ++--- docs/doxygen/overviews/windowdeletion.h | 230 ++-- docs/doxygen/overviews/windowids.h | 146 +-- docs/doxygen/overviews/windowsizing.h | 189 ++-- docs/doxygen/overviews/windowstyles.h | 26 +- docs/doxygen/overviews/xrc.h | 1317 ++++++++++++----------- 7 files changed, 1070 insertions(+), 1085 deletions(-) diff --git a/docs/doxygen/overviews/unicode.h b/docs/doxygen/overviews/unicode.h index 0645ba06e3..d9ec16a070 100644 --- a/docs/doxygen/overviews/unicode.h +++ b/docs/doxygen/overviews/unicode.h @@ -110,7 +110,7 @@ in both ANSI and Unicode modes could look like: @endcode Of course, it would be nearly impossibly to write such programs if it had to -be done this way (try to imagine the number of @ifdef UNICODE an average +be done this way (try to imagine the number of UNICODE checkes an average program would have had!). Luckily, there is another way - see the next section. diff --git a/docs/doxygen/overviews/validator.h b/docs/doxygen/overviews/validator.h index 88f09e2814..4d36ff2fe4 100644 --- a/docs/doxygen/overviews/validator.h +++ b/docs/doxygen/overviews/validator.h @@ -1,5 +1,5 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: validator +// Name: validator.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ @@ -8,125 +8,130 @@ /*! - @page overview_validator wxValidator overview +@page overview_validator wxValidator Overview - Classes: #wxValidator, #wxTextValidator, - #wxGenericValidator - - 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 wxTextCtrl), and - mediates between C++ data and the control, transferring the data in either direction - and validating it. It also is able to intercept events generated - by the control, providing filtering behaviour without the need to derive a new control class. - - You can use a stock validator, such as #wxTextValidator (which does text - control data transfer, validation and filtering) and - #wxGenericValidator (which does data transfer for a range of controls); - or you can write your own. - - @section example Example - - Here is an example of wxTextValidator usage. - - @code - wxTextCtrl *txt1 = new wxTextCtrl(this, -1, wxT(""), - wxPoint(10, 10), wxSize(100, 80), 0, - wxTextValidator(wxFILTER_ALPHA, _data.m_string)); - @endcode - - In this example, the text validator object provides the following functionality: - - @li It transfers the value of g_data.m_string (a wxString variable) to the wxTextCtrl when - the dialog is initialised. - @li It transfers the wxTextCtrl data back to this variable when the dialog is dismissed. - @li It filters input characters so that only alphabetic characters are allowed. - - The validation and filtering of input is accomplished in two ways. When a character is input, - wxTextValidator checks the character against the allowed filter flag (wxFILTER_ALPHA in this case). If - the character is inappropriate, it is vetoed (does not appear) and a warning beep sounds. - The second type of validation is performed when the dialog is about to be dismissed, so if - the default string contained invalid characters already, a dialog box is shown giving the - error, and the dialog is not dismissed. - - @section anatomy Anatomy of a validator - - A programmer creating a new validator class should provide the following functionality. - - A validator constructor is responsible for allowing the programmer to specify the kind - of validation required, and perhaps a pointer to a C++ variable that is used for storing the - data for the control. If such a variable address is not supplied by the user, then - the validator should store the data internally. - - The wxValidator::Validate member function should return - @true if the data in the control (not the C++ variable) is valid. It should also show - an appropriate message if data was not valid. - - The wxValidator::TransferToWindow member function should - transfer the data from the validator or associated C++ variable to the control. - - The wxValidator::TransferFromWindow member function should - transfer the data from the control to the validator or associated C++ variable. - - There should be a copy constructor, and a wxValidator::Clone function - which returns a copy of the validator object. This is important because validators - are passed by reference to window constructors, and must therefore be cloned internally. - - You can optionally define event handlers for the validator, to implement filtering. These handlers - will capture events before the control itself does. - For an example implementation, see the valtext.h and valtext.cpp files in the wxWidgets library. - - @section dialogs How validators interact with dialogs - - For validators to work correctly, validator functions must be called at the right times during - dialog initialisation and dismissal. - - When a wxDialog::Show is called (for a modeless dialog) - or wxDialog::ShowModal is called (for a modal dialog), - the function wxWindow::InitDialog is automatically called. - This in turn sends an initialisation event to the dialog. The default handler for - the wxEVT_INIT_DIALOG event is defined in the wxWindow class to simply call - the function wxWindow::TransferDataToWindow. This - function finds all the validators in the window's children and calls the TransferToWindow - function for each. Thus, data is transferred from C++ variables to the dialog - just as the dialog is being shown. - - @note If you are using a window or panel instead of a dialog, you will need to - call wxWindow::InitDialog explicitly before showing the - window. - - When the user clicks on a button, for example the OK button, the application should - first call wxWindow::Validate, which returns @false if - any of the child window validators failed to validate the window data. The button handler - should return immediately if validation failed. Secondly, the application should - call wxWindow::TransferDataFromWindow and - return if this failed. It is then safe to end the dialog by calling EndModal (if modal) - or Show (if modeless). - - In fact, wxDialog contains a default command event handler for the wxID_OK button. It goes like - this: - - @code - void wxDialog::OnOK(wxCommandEvent& event) - { - if ( Validate() && TransferDataFromWindow() ) - { - if ( IsModal() ) - EndModal(wxID_OK); - else - { - SetReturnCode(wxID_OK); - this-Show(@false); - } - } - } - @endcode - - So if using validators and a normal OK button, you may not even need to write any - code for handling dialog dismissal. - - If you load your dialog from a resource file, you will need to iterate through the controls - setting validators, since validators can't be specified in a dialog resource. - - */ +Classes: wxValidator, wxTextValidator, wxGenericValidator +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 +wxTextCtrl), and mediates between C++ data and the control, transferring the +data in either direction and validating it. It also is able to intercept events +generated by the control, providing filtering behaviour without the need to +derive a new control class. + +You can use a stock validator, such as wxTextValidator (which does text control +data transfer, validation and filtering) and wxGenericValidator (which does +data transfer for a range of controls); or you can write your own. + + +@section overview_validator_example Example + +Here is an example of wxTextValidator usage. + +@code +wxTextCtrl *txt1 = new wxTextCtrl( + this, -1, wxT(""), wxPoint(10, 10), wxSize(100, 80), 0, + wxTextValidator(wxFILTER_ALPHA, &g_data.m_string)); +@endcode + +In this example, the text validator object provides the following +functionality: + +@li It transfers the value of g_data.m_string (a wxString variable) to the + wxTextCtrl when the dialog is initialised. +@li It transfers the wxTextCtrl data back to this variable when the dialog is + dismissed. +@li It filters input characters so that only alphabetic characters are allowed. + +The validation and filtering of input is accomplished in two ways. When a +character is input, wxTextValidator checks the character against the allowed +filter flag (wxFILTER_ALPHA in this case). If the character is inappropriate, +it is vetoed (does not appear) and a warning beep sounds. The second type of +validation is performed when the dialog is about to be dismissed, so if the +default string contained invalid characters already, a dialog box is shown +giving the error, and the dialog is not dismissed. + + +@section overview_validator_anatomy Anatomy of a Validator + +A programmer creating a new validator class should provide the following +functionality. + +A validator constructor is responsible for allowing the programmer to specify +the kind of validation required, and perhaps a pointer to a C++ variable that +is used for storing the data for the control. If such a variable address is not +supplied by the user, then the validator should store the data internally. + +The wxValidator::Validate member function should return @true if the data in +the control (not the C++ variable) is valid. It should also show an appropriate +message if data was not valid. + +The wxValidator::TransferToWindow member function should transfer the data from +the validator or associated C++ variable to the control. + +The wxValidator::TransferFromWindow member function should transfer the data +from the control to the validator or associated C++ variable. + +There should be a copy constructor, and a wxValidator::Clone function which +returns a copy of the validator object. This is important because validators +are passed by reference to window constructors, and must therefore be cloned +internally. + +You can optionally define event handlers for the validator, to implement +filtering. These handlers will capture events before the control itself does. +For an example implementation, see the valtext.h and valtext.cpp files in the +wxWidgets library. + + +@section overview_validator_dialogs How Validators Interact with Dialogs + +For validators to work correctly, validator functions must be called at the +right times during dialog initialisation and dismissal. + +When a wxDialog::Show is called (for a modeless dialog) or wxDialog::ShowModal +is called (for a modal dialog), the function wxWindow::InitDialog is +automatically called. This in turn sends an initialisation event to the dialog. +The default handler for the wxEVT_INIT_DIALOG event is defined in the wxWindow +class to simply call the function wxWindow::TransferDataToWindow. This function +finds all the validators in the window's children and calls the +TransferToWindow function for each. Thus, data is transferred from C++ +variables to the dialog just as the dialog is being shown. + +@note If you are using a window or panel instead of a dialog, you will need to +call wxWindow::InitDialog explicitly before showing the window. + +When the user clicks on a button, for example the OK button, the application +should first call wxWindow::Validate, which returns @false if any of the child +window validators failed to validate the window data. The button handler should +return immediately if validation failed. Secondly, the application should call +wxWindow::TransferDataFromWindow and return if this failed. It is then safe to +end the dialog by calling EndModal (if modal) or Show (if modeless). + +In fact, wxDialog contains a default command event handler for the wxID_OK +button. It goes like this: + +@code +void wxDialog::OnOK(wxCommandEvent& event) +{ + if ( Validate() && TransferDataFromWindow() ) + { + if ( IsModal() ) + EndModal(wxID_OK); + else + { + SetReturnCode(wxID_OK); + this->Show(false); + } + } +} +@endcode + +So if using validators and a normal OK button, you may not even need to write +any code for handling dialog dismissal. + +If you load your dialog from a resource file, you will need to iterate through +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 e7aa7a9c79..420b4c1664 100644 --- a/docs/doxygen/overviews/windowdeletion.h +++ b/docs/doxygen/overviews/windowdeletion.h @@ -1,5 +1,5 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: windowdeletion +// Name: windowdeletion.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ @@ -8,135 +8,103 @@ /*! - @page overview_windowdeletion Window deletion overview - - Classes: #wxCloseEvent, #wxWindow - - 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. - - @section sequence What is the sequence of events in a window deletion? - - When the user clicks on the system close button or system close command, - in a frame or a dialog, wxWidgets calls wxWindow::Close. This - in turn generates an EVT_CLOSE event: see #wxCloseEvent. - - It is the duty of the application to define a suitable event handler, and - decide whether or not to destroy the window. - If the application is for some reason forcing the application to close - (wxCloseEvent::CanVeto returns @false), the window should always be destroyed, otherwise there is the option to - ignore the request, or maybe wait until the user has answered a question - before deciding whether it is safe to close. The handler for EVT_CLOSE should - signal to the calling code if it does not destroy the window, by calling - wxCloseEvent::Veto. Calling this provides useful information - to the calling code. - - The wxCloseEvent handler should only call wxWindow::Destroy to - delete the window, and not use the @b delete operator. This is because - for some window classes, wxWidgets delays actual deletion of the window until all events have been processed, - since otherwise there is the danger that events will be sent to a non-existent window. - - As reinforced in the next section, calling Close does not guarantee that the window - will be destroyed. Call wxWindow::Destroy if you want to be - certain that the window is destroyed. - - @section close How can the application close a window itself? - - Your application can either use wxWindow::Close event just as - the framework does, or it can call wxWindow::Destroy directly. - If using Close(), you can pass a @true argument to this function to tell the event handler - that we definitely want to delete the frame and it cannot be vetoed. - - The advantage of using Close instead of Destroy is that it will call any clean-up code - defined by the EVT_CLOSE handler; for example it may close a document contained in - a window after first asking the user whether the work should be saved. Close can be vetoed - by this process (return @false), whereas Destroy definitely destroys the window. - - @section default What is the default behaviour? - - The default close event handler for wxDialog simulates a Cancel command, - generating a wxID_CANCEL event. Since the handler for this cancel event might - itself call @b Close, there is a check for infinite looping. The default handler - for wxID_CANCEL hides the dialog (if modeless) or calls EndModal(wxID_CANCEL) (if modal). - In other words, by default, the dialog @e is not destroyed (it might have been created - on the stack, so the assumption of dynamic creation cannot be made). - - The default close event handler for wxFrame destroys the frame using Destroy(). - - @section exit What should I do when the user calls up Exit from a menu? - - You can simply call wxWindow::Close on the frame. This - will invoke your own close event handler which may destroy the frame. - - You can do checking to see if your application can be safely exited at this point, - either from within your close event handler, or from within your exit menu command - handler. For example, you may wish to check that all files have been saved. - Give the user a chance to save and quit, to not save but quit anyway, or to cancel - the exit command altogether. - - @section upgrade What should I do to upgrade my 1.xx OnClose to 2.0? - - In wxWidgets 1.xx, the @b OnClose function did not actually delete 'this', but signaled - to the calling function (either @b Close, or the wxWidgets framework) to delete - or not delete the window. - - To update your code, you should provide an event table entry in your frame or - dialog, using the EVT_CLOSE macro. The event handler function might look like this: - - @code - void MyFrame::OnCloseWindow(wxCloseEvent& event) - { - if (MyDataHasBeenModified()) - { - wxMessageDialog* dialog = new wxMessageDialog(this, - "Save changed data?", "My app", wxYES_NO|wxCANCEL); - - int ans = dialog-ShowModal(); - dialog-Destroy(); - - switch (ans) - { - case wxID_YES: // Save, then destroy, quitting app - SaveMyData(); - this-Destroy(); - break; - case wxID_NO: // Don't save; just destroy, quitting app - this-Destroy(); - break; - case wxID_CANCEL: // Do nothing - so don't quit app. - default: - if (!event.CanVeto()) // Test if we can veto this deletion - this-Destroy(); // If not, destroy the window anyway. - else - event.Veto(); // Notify the calling code that we didn't delete the frame. - break; - } - } - } - @endcode - - @section exit_app How do I exit the application gracefully? - - A wxWidgets application automatically exits when the last top level window - (#wxFrame or #wxDialog), is destroyed. Put - any application-wide cleanup code in wxApp::OnExit (this - is a virtual function, not an event handler). - - @section deletion Do child windows get deleted automatically? - - Yes, child windows are deleted from within the parent destructor. This includes any children - that are themselves frames or dialogs, so you may wish to close these child frame or dialog windows - explicitly from within the parent close handler. - - @section window_kinds What about other kinds of window? - - So far we've been talking about 'managed' windows, i.e. frames and dialogs. Windows - with parents, such as controls, don't have delayed destruction and don't usually have - close event handlers, though you can implement them if you wish. For consistency, - continue to use the wxWindow::Destroy function instead - of the @b delete operator when deleting these kinds of windows explicitly. - - */ +@page overview_windowdeletion Window Deletion Overview +Classes: wxCloseEvent, wxWindow + +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. + + +@section overview_windowdeletion_sequence Sequence of Events During Window Deletion + +When the user clicks on the system close button or system close command, in a +frame or a dialog, wxWidgets calls wxWindow::Close. This in turn generates an +EVT_CLOSE event: see wxCloseEvent. + +It is the duty of the application to define a suitable event handler, and +decide whether or not to destroy the window. If the application is for some +reason forcing the application to close (wxCloseEvent::CanVeto returns @false), +the window should always be destroyed, otherwise there is the option to ignore +the request, or maybe wait until the user has answered a question before +deciding whether it is safe to close. The handler for EVT_CLOSE should signal +to the calling code if it does not destroy the window, by calling +wxCloseEvent::Veto. Calling this provides useful information to the calling +code. + +The wxCloseEvent handler should only call wxWindow::Destroy to delete the +window, and not use the @c delete operator. This is because for some window +classes, wxWidgets delays actual deletion of the window until all events have +been processed, since otherwise there is the danger that events will be sent to +a non-existent window. + +As reinforced in the next section, calling Close does not guarantee that the window +will be destroyed. Call wxWindow::Destroy if you want to be +certain that the window is destroyed. + + +@section overview_windowdeletion_close Closing Windows + +Your application can either use wxWindow::Close event just as the framework +does, or it can call wxWindow::Destroy directly. If using Close(), you can pass +a @true argument to this function to tell the event handler that we definitely +want to delete the frame and it cannot be vetoed. + +The advantage of using Close instead of Destroy is that it will call any +clean-up code defined by the EVT_CLOSE handler; for example it may close a +document contained in a window after first asking the user whether the work +should be saved. Close can be vetoed by this process (return @false), whereas +Destroy definitely destroys the window. + + +@section overview_windowdeletion_default Default Window Close Behaviour + +The default close event handler for wxDialog simulates a Cancel command, +generating a wxID_CANCEL event. Since the handler for this cancel event might +itself call Close, there is a check for infinite looping. The default handler +for wxID_CANCEL hides the dialog (if modeless) or calls EndModal(wxID_CANCEL) +(if modal). In other words, by default, the dialog @e is not destroyed (it +might have been created on the stack, so the assumption of dynamic creation +cannot be made). + +The default close event handler for wxFrame destroys the frame using Destroy(). + + +@section overview_windowdeletion_menuexit User Calls to Exit From a Menu + +What should I do when the user calls up Exit from a menu? You can simply call +wxWindow::Close on the frame. This will invoke your own close event handler +which may destroy the frame. + +You can do checking to see if your application can be safely exited at this +point, either from within your close event handler, or from within your exit +menu command handler. For example, you may wish to check that all files have +been saved. Give the user a chance to save and quit, to not save but quit +anyway, or to cancel the exit command altogether. + + +@section overview_windowdeletion_exitapp Exiting the Application Gracefully + +A wxWidgets application automatically exits when the last top level window +(wxFrame or wxDialog), is destroyed. Put any application-wide cleanup code in +wxApp::OnExit (this is a virtual function, not an event handler). + + +@section overview_windowdeletion_deletion Automatic Deletion of Child Windows + +Child windows are deleted from within the parent destructor. This includes any +children that are themselves frames or dialogs, so you may wish to close these +child frame or dialog windows explicitly from within the parent close handler. + + +@section overview_windowdeletion_windowkinds Other Kinds of Windows + +So far we've been talking about 'managed' windows, i.e. frames and dialogs. +Windows with parents, such as controls, don't have delayed destruction and +don't usually have close event handlers, though you can implement them if you +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 bc33455321..a513b8bf3e 100644 --- a/docs/doxygen/overviews/windowids.h +++ b/docs/doxygen/overviews/windowids.h @@ -1,5 +1,5 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: windowids +// Name: windowids.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ @@ -8,73 +8,81 @@ /*! - @page overview_windowids Window IDs overview - - @seealso - #wxIdManager - wxWindow::NewControlId - wxWindow::UnreserveControlId - - @li @ref introduction - @li @ref overview_windowidstypes - @li @ref overview_windowidsusing - - - @section introduction Introduction - - Various contols and other parts of wxWidgets need an ID. Sometimes the - ID may be directly provided by the use or have a predefined value, such as - @c wxID_OPEN. Often, however, the value of the ID is unimportant and is - created automatically by calling wxWindow::NewControlId - or by passing @c wxID_ANY as the ID of an object. - - There are two ways to generate an ID. One way, is to start at a negative number, - and for each new ID, return the next smallest number. This is fine for systems - that can used the full range of negative numbers for an ID, as this provides - more than enough IDs and it would take a very very long time to run out and - wrap around. However, some systems can not use the full range of the ID value. - Windows, for example, can only use 16 bit IDs, and only has about 32000 possible - automatic IDs that can be generated by wxWindow::NewControlId. - If the program runs long enough, depending on the program itself, using this first - method would cause the IDs to wrap around into the positive ID range and cause possible - clashes with any directly specified ID values. - - The other way is to keep track of the IDs returned by wxWindow::NewControlId - and don't return them again until the ID is completely free and not being used by - any other objects. This will make sure that the ID values do not clash with 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. - - @section overview_windowidstypes Data types - - A wxWindowID is just the integer type for a window ID. It should be used almost - everywhere. To help keep track of the count for the automatically generated IDs, - a new type, wxWindowIDRef exists, that can take the place of wxWindowID where needed. - When an ID is first created, it is marked as reserved. When assigning it to a - wxWindowIDRef, the usage count of the ID is increased, or set to 1 if it is currently - reserved. Assigning the same ID to several wxWindowIDRefs will keep track of the count. - As the wxWindowIDRef gets destroyed or its value changes, it will decrease the count - of the used ID. When there are no more wxWindowIDRef types with the created ID, the - ID is considered free and can then be used again by wxWindow::NewControlId. - - If a created ID is not assigned to a wxWindowIDRef, then it remains reserved until it - is unreserved manually with wxWindow::UnreserveControlId. - However, if it is assigned to a wxWindowIDRef, then it will be unreserved automatically - and will be considered free when the count is 0, and should NOT be manually unreserved. - - wxWindowIDRef can store both automatic IDs from wxWindow::NewControlId - as well as normal IDs. Reference counting is only done for the automatic IDs. Also, - wxWindowIDRef has conversion operators that allow it to be treated just like a wxWindowID. - - @section overview_windowidsusing Using wxWindowIDRef - - A wxWindowIDRef should be used in place of a wxWindowID where you want to make sure the - ID is not created again by wxWindow::NewControlId - at least until the wxWindowIDRef is destroyed, usually when the associated object is destroyed. - 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. - - */ +@page overview_windowids Window IDs Overview +@li @ref overview_windowids_intro +@li @ref overview_windowids_type +@li @ref overview_windowids_using + +@seealso + +@li wxIdManager +@li wxWindow::NewControlId +@li wxWindow::UnreserveControlId + + +
+ + +@section overview_windowids_intro Introduction + +Various contols and other parts of wxWidgets need an ID. Sometimes the ID may +be directly provided by the use or have a predefined value, such as +@c wxID_OPEN. Often, however, the value of the ID is unimportant and is created +automatically by calling wxWindow::NewControlId or by passing @c wxID_ANY as +the ID of an object. + +There are two ways to generate an ID. One way, is to start at a negative +number, and for each new ID, return the next smallest number. This is fine for +systems that can used the full range of negative numbers for an ID, as this +provides more than enough IDs and it would take a very very long time to run +out and wrap around. However, some systems can not use the full range of the +ID value. Windows, for example, can only use 16 bit IDs, and only has about +32000 possible automatic IDs that can be generated by wxWindow::NewControlId. +If the program runs long enough, depending on the program itself, using this +first method would cause the IDs to wrap around into the positive ID range and +cause possible clashes with any directly specified ID values. + +The other way is to keep track of the IDs returned by wxWindow::NewControlId +and don't return them again until the ID is completely free and not being used +by any other objects. This will make sure that the ID values do not clash with +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. + + +@section overview_windowids_type Data Types + +A wxWindowID is just the integer type for a window ID. It should be used +almost everywhere. To help keep track of the count for the automatically +generated IDs, a new type, wxWindowIDRef exists, that can take the place of +wxWindowID where needed. When an ID is first created, it is marked as reserved. +When assigning it to a wxWindowIDRef, the usage count of the ID is increased, +or set to 1 if it is currently reserved. Assigning the same ID to several +wxWindowIDRefs will keep track of the count. As the wxWindowIDRef gets +destroyed or its value changes, it will decrease the count of the used ID. When +there are no more wxWindowIDRef types with the created ID, the ID is considered +free and can then be used again by wxWindow::NewControlId. + +If a created ID is not assigned to a wxWindowIDRef, then it remains reserved +until it is unreserved manually with wxWindow::UnreserveControlId. However, if +it is assigned to a wxWindowIDRef, then it will be unreserved automatically and +will be considered free when the count is 0, and should NOT be manually +unreserved. + +wxWindowIDRef can store both automatic IDs from wxWindow::NewControlId as well +as normal IDs. Reference counting is only done for the automatic IDs. Also, +wxWindowIDRef has conversion operators that allow it to be treated just like a +wxWindowID. + + +@section overview_windowids_using Using wxWindowIDRef + +A wxWindowIDRef should be used in place of a wxWindowID where you want to make +sure the ID is not created again by wxWindow::NewControlId at least until the +wxWindowIDRef is destroyed, usually when the associated object is destroyed. +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 9f593c5316..3665c8223d 100644 --- a/docs/doxygen/overviews/windowsizing.h +++ b/docs/doxygen/overviews/windowsizing.h @@ -1,5 +1,5 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: windowsizing +// Name: windowsizing.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ @@ -8,102 +8,93 @@ /*! - @page overview_windowsizing Window Sizing Overview - - 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. - - @b BestSize: The best size of a widget depends on what kind of widget it - is, and usually also on the contents of the widget. For example a - #wxListBox's best size will be calculated based on - how many items it has, up to a certain limit, or a - #wxButton's best size will be calculated based on - its label size, but normally won't be smaller than the platform - default button size (unless a style flag overrides that). Get the - picture? There is a special virtual method in the C++ window classes - called @c DoGetBestSize() that a class needs to override if it - wants to calculate its own best size based on its content. The default - @c DoGetBestSize() is designed for use in container windows, - such as #wxPanel, and works something like this: - - - -# If the window has a sizer then it is used to calculate the best size. - -# Otherwise if the window has layout constraints then that is used to calculate the best size. - -# Otherwise if the window has children then the best size is set to be large enough to show all the children. - -# Otherwise if there are no children then the window's min size will be used for the best size. - -# Otherwise if there is no min size set, then the current size is used for the best size. - - - @b MinSize: The min size of a widget is a size that is normally - explicitly set by the programmer either with the @c SetMinSize() - method or the @c SetSizeHints() method. Most controls will also - set the min size to the size given in the control's constructor if a - non-default value is passed. Top-level windows such as - #wxFrame will not allow the user to resize the frame - below the min size. - - @b Size: The size of a widget can be explicitly set or fetched with - the @c SetSize() or @c GetSize() methods. This size value - is the size that the widget is currently using on screen and is the - way to change the size of something that is not being managed by a - sizer. - - @b ClientSize: The client size represents the widget's area inside - of any borders belonging to the widget and is the area that can be - drawn upon in a @c EVT_PAINT event. If a widget doesn't have a - border then its client size is the same as its size. - - @b InitialSize: The initial size of a widget is the size given to - the constructor of the widget, if any. As mentioned above most - controls will also set this size value as the control's min size. If - the size passed to the constructor is the default - @c wxDefaultSize, or if the size is not fully specified (such as - @c wxSize(150,-1)) then most controls will fill in the missing - size components using the best size and will set the initial size of - the control to the resulting size. - - @b GetEffectiveMinSize(): (formerly @c GetBestFittingSize) A - blending of the widget's min size and best size, giving precedence to - the min size. For example, if a widget's min size is set to (150, -1) - and the best size is (80, 22) then the best fitting size is (150, - 22). If the min size is (50, 20) then the best fitting size is (50, - 20). This method is what is called by the sizers when determining what - the requirements of each item in the sizer is, and is used for - calculating the overall minimum needs of the sizer. - - @b SetInitialSize(size): (formerly @c SetBestFittingSize) - This is a little different than the typical size setters. Rather than - just setting an "initial size" attribute it actually sets the minsize - to the value passed in, blends that value with the best size, and then - sets the size of the widget to be the result. So you can consider this - method to be a "Smart SetSize". This method is what is called by the - constructor of most controls to set the minsize and initial size of - the control. - - @b window.Fit(): The @c Fit() method sets the size of a - window to fit around its children. If it has no children then nothing - is done, if it does have children then the size of the window is set - to the window's best size. - - @b sizer.Fit(window): This sets the size of the window to be large - enough to accommodate the minimum size needed by the sizer, (along with - a few other constraints...) If the sizer is the one that is assigned - to the window then this should be equivalent to @c window.Fit(). - - @b sizer.Layout(): Recalculates the minimum space needed by each - item in the sizer, and then lays out the items within the space - currently allotted to the sizer. - - @b window.Layout(): If the window has a sizer then it sets the - space given to the sizer to the current size of the window, which - results in a call to @c sizer.Layout(). If the window has layout - constraints instead of a sizer then the constraints algorithm is - run. The @c Layout() method is what is called by the default - @c EVT_SIZE handler for container windows. - - */ - +@page overview_windowsizing Window Sizing Overview + +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. + +@b BestSize: The best size of a widget depends on what kind of widget it is, +and usually also on the contents of the widget. For example a wxListBox's best +size will be calculated based on how many items it has, up to a certain limit, +or a wxButton's best size will be calculated based on its label size, but +normally won't be smaller than the platform default button size (unless a style +flag overrides that). Get the picture? There is a special virtual method in the +C++ window classes called @c DoGetBestSize() that a class needs to override if +it wants to calculate its own best size based on its content. The default +@c DoGetBestSize() is designed for use in container windows, such as wxPanel, +and works something like this: + +-# If the window has a sizer then it is used to calculate the best size. +-# Otherwise if the window has layout constraints then that is used to + calculate the best size. +-# Otherwise if the window has children then the best size is set to be large + enough to show all the children. +-# Otherwise if there are no children then the window's min size will be used + for the best size. +-# Otherwise if there is no min size set, then the current size is used for the + best size. + +@b MinSize: The min size of a widget is a size that is normally explicitly set +by the programmer either with the @c SetMinSize() method or the +@c SetSizeHints() method. Most controls will also set the min size to the size +given in the control's constructor if a non-default value is passed. Top-level +windows such as wxFrame will not allow the user to resize the frame below the +min size. + +@b Size: The size of a widget can be explicitly set or fetched with the +@c SetSize() or @c GetSize() methods. This size value is the size that the +widget is currently using on screen and is the way to change the size of +something that is not being managed by a sizer. + +@b ClientSize: The client size represents the widget's area inside of any +borders belonging to the widget and is the area that can be drawn upon in a +@c EVT_PAINT event. If a widget doesn't have a border then its client size is +the same as its size. + +@b InitialSize: The initial size of a widget is the size given to the +constructor of the widget, if any. As mentioned above most controls will also +set this size value as the control's min size. If the size passed to the +constructor is the default @c wxDefaultSize, or if the size is not fully +specified (such as wxSize(150,-1)) then most controls will fill in the missing +size components using the best size and will set the initial size of the +control to the resulting size. + +@b GetEffectiveMinSize(): (formerly @c GetBestFittingSize) A blending of the +widget's min size and best size, giving precedence to the min size. For +example, if a widget's min size is set to (150, -1) and the best size is +(80, 22) then the best fitting size is (150, 22). If the min size is (50, 20) +then the best fitting size is (50, 20). This method is what is called by the +sizers when determining what the requirements of each item in the sizer is, and +is used for calculating the overall minimum needs of the sizer. + +@b SetInitialSize(size): (formerly @c SetBestFittingSize) This is a little +different than the typical size setters. Rather than just setting an +"initial size" attribute it actually sets the minsize to the value passed in, +blends that value with the best size, and then sets the size of the widget to +be the result. So you can consider this method to be a "Smart SetSize". This +method is what is called by the constructor of most controls to set the minsize +and initial size of the control. + +@b window.Fit(): The @c Fit() method sets the size of a window to fit around +its children. If it has no children then nothing is done, if it does have +children then the size of the window is set to the window's best size. + +@b sizer.Fit(window): This sets the size of the window to be large enough to +accommodate the minimum size needed by the sizer, (along with a few other +constraints...) If the sizer is the one that is assigned to the window then +this should be equivalent to @c window.Fit(). + +@b sizer.Layout(): Recalculates the minimum space needed by each item in the +sizer, and then lays out the items within the space currently allotted to the +sizer. + +@b window.Layout(): If the window has a sizer then it sets the space given to +the sizer to the current size of the window, which results in a call to +@c sizer.Layout(). If the window has layout constraints instead of a sizer then +the constraints algorithm is run. The @c Layout() method is what is called by +the default @c EVT_SIZE handler for container windows. + +*/ diff --git a/docs/doxygen/overviews/windowstyles.h b/docs/doxygen/overviews/windowstyles.h index 4eb99a7e8b..23f8e244b4 100644 --- a/docs/doxygen/overviews/windowstyles.h +++ b/docs/doxygen/overviews/windowstyles.h @@ -1,5 +1,5 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: windowstyles +// Name: windowstyles.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ @@ -8,20 +8,20 @@ /*! - @page overview_windowstyles Window styles +@page overview_windowstyles Window Styles - 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. For example: +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. For +example: - @code - wxCAPTION | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER - @endcode +@code +wxCAPTION | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER +@endcode - For the window styles specific to each window class, please see the documentation - for the window. Most windows can use the generic styles listed for #wxWindow in - addition to their own styles. - - */ +For the window styles specific to each window class, please see the +documentation for the window. 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 2574bdc55b..56c8ad08c8 100644 --- a/docs/doxygen/overviews/xrc.h +++ b/docs/doxygen/overviews/xrc.h @@ -8,658 +8,671 @@ /*! - @page overview_xrc XML-based resource system overview - - Classes: #wxXmlResource, #wxXmlResourceHandler - - 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 into - the application at run-time. XRC files can also be compiled into binary XRS files - or C++ code (the former makes it possible to store all resources in a single file - and the latter is useful when you want to embed the resources into the executable). - - There are several advantages to using XRC resources. - - @li Recompiling and linking an application is not necessary if the - resources change. - @li If you use a dialog designer that generates C++ code, it can be hard - to reintegrate this into existing C++ code. Separation of resources and code - is a more elegant solution. - @li You can choose between different alternative resource files at run time, - if necessary. - @li The XRC format uses sizers for flexibility, allowing dialogs to be resizable - and highly portable. - @li The XRC format is a wxWidgets standard, - and can be generated or postprocessed by any program that understands it. - As it is basedon the XML standard, existing XML editors can be used for - simple editing purposes. - - XRC was written by Vaclav Slavik. - - @li @ref overview_xrc_concepts - @li @ref overview_xrc_binaryresourcefiles - @li @ref overview_xrc_embeddedresource - @li @ref overview_xrc_cppsample - @li @ref overview_xrc_sample - @li @ref overview_xrc_fileformat - @li @ref overview_xrc_cppheader - @li @ref overview_xrc_newresourcehandlers - - -
- - - @section overview_xrc_concepts XRC concepts - - These are the typical steps for using XRC files in your application. - - @li Include the appropriate headers: normally "wx/xrc/xmlres.h" will suffice; - @li If you are going to use XRS files (see @ref overview_xrc_binaryresourcefiles), install - wxFileSystem archive handler first with @c wxFileSystem::AddHandler(new wxArchiveFSHandler); - @li call @c wxXmlResource::Get()->InitAllHandlers() from your wxApp::OnInit function, - and then call @c wxXmlResource::Get()->Load("myfile.xrc") to load the resource file; - @li to create a dialog from a resource, create it using the default constructor, and then - load it using for example @c wxXmlResource::Get()->LoadDialog(dlg, this, "dlg1"); - @li set up event tables as usual but use the @c XRCID(str) macro to translate from XRC string names - to a suitable integer identifier, for example EVT_MENU(XRCID("quit"), MyFrame::OnQuit). - - To create an XRC file, you can use one of the following methods. - - @li Create the file by hand; - @li use wxDesigner (http://www.roebling.de), a commercial dialog designer/RAD tool; - @li use DialogBlocks (http://www.anthemion.co.uk/dialogblocks), a commercial dialog editor; - @li use XRCed (http://xrced.sf.net), a wxPython-based dialog editor that you can find in the - @c wxPython/tools subdirectory of the wxWidgets SVN archive; - @li use wxGlade (http://wxglade.sf.net), a GUI designer written in wxPython. - At the moment it can generate Python, C++ and XRC; - - A complete list of third-party tools that write to XRC can be found at - http://www.wxwidgets.org/wiki/index.php/Tools. - - It is highly recommended that you use a resource editing tool, since it's fiddly - writing XRC files by hand. - - You can use wxXmlResource::Load in a number of ways. - You can pass an XRC file (XML-based text resource file) or a zip-compressed file - (see @ref overview_xrc_binaryresourcefiles), with extension ZIP or XRS, containing - other XRC. - - You can also use embedded C++ resources (see @ref overview_xrc_embeddedresource). - - - @section overview_xrc_binaryresourcefiles Using binary resource files - - To compile binary resource files, use the command-line @c wxrc utility. - It takes one or more file parameters (the input XRC files) and the following - switches and options: - - @li -h (--help): show a help message - @li -v (--verbose): show verbose logging information - @li -c (--cpp-code): write C++ source rather than a XRS file - @li -e (--extra-cpp-code): if used together with -c, generates C++ header file - containing class definitions for the windows defined by the XRC file - (see special subsection) - @li -u (--uncompressed): do not compress XML files (C++ only) - @li -g (--gettext): output underscore-wrapped strings that poEdit or gettext can scan. - Outputs to stdout, or a file if -o is used - @li -n (--function) name: specify C++ function name (use with -c) - @li -o (--output) filename: specify the output file, such as resource.xrs or resource.cpp - @li -l (--list-of-handlers) filename: output a list of necessary handlers to this file - - For example: - - @code - % wxrc resource.xrc - % wxrc resource.xrc -o resource.xrs - % wxrc resource.xrc -v -c -o resource.cpp - @endcode - - @note - XRS file is essentially a renamed ZIP archive which means that you can manipulate - it with standard ZIP tools. Note that if you are using XRS files, you have - to initialize the #wxFileSystem archive handler first! It is a simple - thing to do: - - @code - #include wx/filesys.h - #include wx/fs_arc.h - ... - wxFileSystem::AddHandler(new wxArchiveFSHandler); - @endcode - - - @section overview_xrc_embeddedresource Using embedded resources - - It is sometimes useful to embed resources in the executable itself instead - of loading an external file (e.g. when your app is small and consists only of one - exe file). XRC provides means to convert resources into regular C++ file that - can be compiled and included in the executable. - - Use the @c -c switch to - @c wxrc utility to produce C++ file with embedded resources. This file will - contain a function called @e InitXmlResource (unless you override this with - a command line switch). Use it to load the resource: - - @code - extern void InitXmlResource(); // defined in generated file - ... - wxXmlResource::Get()-InitAllHandlers(); - InitXmlResource(); - ... - @endcode - - - @section overview_xrc_cppsample XRC C++ sample - - This is the C++ source file (xrcdemo.cpp) for the XRC sample. - - @code - #include "wx/wx.h" - #include "wx/image.h" - #include "wx/xrc/xmlres.h" - - // the application icon - #if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__) - #include "rc/appicon.xpm" - #endif - - // ---------------------------------------------------------------------------- - // private classes - // ---------------------------------------------------------------------------- - - // Define a new application type, each program should derive a class from wxApp - class MyApp : public wxApp - { - public: - // override base class virtuals - // ---------------------------- - - // this one is called on application startup and is a good place for the app - // initialization (doing it here and not in the ctor allows to have an error - // return: if OnInit() returns @false, the application terminates) - virtual bool OnInit(); - }; - - // Define a new frame type: this is going to be our main frame - class MyFrame : public wxFrame - { - public: - // ctor(s) - MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size); - - // event handlers (these functions should _not_ be virtual) - void OnQuit(wxCommandEvent& event); - void OnAbout(wxCommandEvent& event); - void OnDlg1(wxCommandEvent& event); - void OnDlg2(wxCommandEvent& event); - - private: - // any class wishing to process wxWidgets events must use this macro - DECLARE_EVENT_TABLE() - }; - - // ---------------------------------------------------------------------------- - // event tables and other macros for wxWidgets - // ---------------------------------------------------------------------------- - - BEGIN_EVENT_TABLE(MyFrame, wxFrame) - EVT_MENU(XRCID("menu_quit"), MyFrame::OnQuit) - EVT_MENU(XRCID("menu_about"), MyFrame::OnAbout) - EVT_MENU(XRCID("menu_dlg1"), MyFrame::OnDlg1) - EVT_MENU(XRCID("menu_dlg2"), MyFrame::OnDlg2) - END_EVENT_TABLE() - - IMPLEMENT_APP(MyApp) - - // ---------------------------------------------------------------------------- - // the application class - // ---------------------------------------------------------------------------- - - // 'Main program' equivalent: the program execution "starts" here - bool MyApp::OnInit() - { - wxImage::AddHandler(new wxGIFHandler); - wxXmlResource::Get()->InitAllHandlers(); - wxXmlResource::Get()->Load("rc/resource.xrc"); - - MyFrame *frame = new MyFrame("XML resources demo", - wxPoint(50, 50), wxSize(450, 340)); - frame->Show(true); - return true; - } - - // ---------------------------------------------------------------------------- - // main frame - // ---------------------------------------------------------------------------- - - // frame constructor - MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size) - : wxFrame((wxFrame *)NULL, -1, title, pos, size) - { - SetIcon(wxICON(appicon)); - - SetMenuBar(wxXmlResource::Get()->LoadMenuBar("mainmenu")); - SetToolBar(wxXmlResource::Get()->LoadToolBar(this, "toolbar")); - } - - // event handlers - void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event)) - { - // true is to force the frame to close - Close(true); - } - - void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event)) - { - wxString msg; - msg.Printf( _T("This is the about dialog of XML resources demo.\n") - _T("Welcome to %s"), wxVERSION_STRING); - - wxMessageBox(msg, "About XML resources demo", wxOK | wxICON_INFORMATION, this); - } - - void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event)) - { - wxDialog dlg; - wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1"); - dlg.ShowModal(); - } - - void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event)) - { - wxDialog dlg; - wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg2"); - dlg.ShowModal(); - } - @endcode - - - @section overview_xrc_sample XRC resource file sample - - This is the XML file (resource.xrc) for the XRC sample. - - @code - - - - - - - - - - filesave.gif - - - - - - - - - - - - - - - - - 2,2 - - fileopen.gif - Open catalog - - - filesave.gif - Save catalog - - - update.gif - Update catalog - synchronize it with sources - - - - quotes.gif - 1 - Display quotes around the string? - - - - fuzzy.gif - Toggled if selected string is fuzzy translation - 1 - - - - - - - fuzzy.gif - fileopen.gif - - - - - - - - - - wxALIGN_CENTER - - - - - - 10d - wxALL - - - - <h1>Hi,</h1>man - 100,45d - - - - - - - - - - Hello, we are inside a <u>NOTEBOOK</u>... - 50,50d - - - - - - - - - - - - - Hello, we are inside a <u>NOTEBOOK</u>... - 50,50d - - - - - - - 1 - - wxEXPAND - - wxVERTICAL - - - - - wxVERTICAL - - - 200,200d - - Hello, this is an ordinary multiline\n textctrl.... - - - wxEXPAND|wxALL - 10 - - - - - - - 1 - - - - - - - 10 - wxLEFT - - - wxLEFT|wxRIGHT|wxBOTTOM|wxALIGN_RIGHT - 10 - - - Second testing dialog - - - @endcode - - - @section overview_xrc_fileformat XRC file format - - Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWidgets - distribution. - - - @section overview_xrc_cppheader C++ header file generation - - Using the @c -e switch together with @c -c, a C++ header file is written - containing class definitions for the GUI windows defined in the XRC file. - This code generation can make it easier to use XRC and automate program - development. - The classes can be used as basis for development, freeing the - programmer from dealing with most of the XRC specifics (e.g. @c XRCCTRL). - - For each top level window defined in the XRC file a C++ class definition is - generated, containing as class members the named widgets of the window. - A default constructor for each class is also generated. Inside the constructor - all XRC loading is done and all class members representing widgets are initialized. - - A simple example will help understand how the scheme works. Suppose you have - a XRC file defining a top level window @c TestWnd_Base, which subclasses @c wxFrame - (any other class like @c wxDialog will do also), and has subwidgets @c wxTextCtrl A - and @c wxButton B. - - The XRC file and corresponding class definition in the header file will - be something like: - - @code - - - - -1,-1 - Test - - wxHORIZONTAL - - - - - - - - - - - - - - - - class TestWnd_Base : public wxFrame { - protected: - wxTextCtrl* A; - wxButton* B; - - private: - void InitWidgetsFromXRC(){ - wxXmlResource::Get()->LoadObject(this,NULL,"TestWnd","wxFrame"); - A = XRCCTRL(*this,"A",wxTextCtrl); - B = XRCCTRL(*this,"B",wxButton); - } - public: - TestWnd::TestWnd(){ - InitWidgetsFromXRC(); - } - }; - @endcode - - The generated window class can be used as basis for the full window class. The - class members which represent widgets may be accessed by name instead of using - @c XRCCTRL every time you wish to reference them (note that they are @c protected - class members), though you must still use @c XRCID to refer to widget IDs in the - event table. - - Example: - - @code - #include "resource.h" - - class TestWnd : public TestWnd_Base { - public: - TestWnd(){ - // A, B already initialised at this point - A->SetValue("Updated in TestWnd::TestWnd"); - B->SetValue("Nice :)"); - } - void OnBPressed(wxEvent& event){ - Close(); - } - DECLARE_EVENT_TABLE(); - }; - - BEGIN_EVENT_TABLE(TestWnd,TestWnd_Base) - EVT_BUTTON(XRCID("B"),TestWnd::OnBPressed) - END_EVENT_TABLE() - @endcode - - It is also possible to access the wxSizerItem of a sizer that is part of - a resource. This can be done using @c XRCSIZERITEM as shown. - - The resource file can have something like this for a sizer item. - - @code - - 400, 300 - - @endcode - - The code can then access the sizer item by using @c XRCSIZERITEM and - @c XRCID together. - - @code - wxSizerItem* item = XRCSIZERITEM(*this, "area"); - @endcode - - - @section overview_xrc_newresourcehandlers Adding new resource handlers - - Adding a new resource handler is pretty easy. - - Typically, to add an handler for the @c MyControl class, you'll want to create - the @c xh_mycontrol.h and @c xh_mycontrol.cpp files. - - The header needs to contains the @c MyControlXmlHandler class definition: - - @code - class MyControlXmlHandler : public wxXmlResourceHandler - { - public: - - // Constructor. - MyControlXmlHandler(); - - // Creates the control and returns a pointer to it. - virtual wxObject *DoCreateResource(); - - // Returns @true if we know how to create a control for the given node. - virtual bool CanHandle(wxXmlNode *node); - - // Register with wxWidgets' dynamic class subsystem. - DECLARE_DYNAMIC_CLASS(MyControlXmlHandler) - }; - @endcode - - The implementation of your custom XML handler will typically look as: - - @code - // Register with wxWidgets' dynamic class subsystem. - IMPLEMENT_DYNAMIC_CLASS(MyControlXmlHandler, wxXmlResourceHandler) - - MyControlXmlHandler::MyControlXmlHandler() - { - // this call adds support for all wxWindows class styles - // (e.g. wxBORDER_SIMPLE, wxBORDER_SUNKEN, wxWS_EX_* etc etc) - AddWindowStyles(); - - // if MyControl class supports e.g. MYCONTROL_DEFAULT_STYLE - // you should use: - // XRC_ADD_STYLE(MYCONTROL_DEFAULT_STYLE); - } - - wxObject *MyControlXmlHandler::DoCreateResource() - { - // the following macro will init a pointer named "control" - // with a new instance of the MyControl class, but will NOT - // Create() it! - XRC_MAKE_INSTANCE(control, MyControl) - - // this is the point where you'll typically need to do the most - // important changes: here the control is created and initialized. - // You'll want to use the wxXmlResourceHandler's getters to - // do most of your work. - // If e.g. the MyControl::Create function looks like: - // - // bool MyControl::Create(wxWindow *parent, int id, - // const wxBitmap , const wxPoint , - // const wxBitmap , const wxPoint , - // const wxString , const wxFont , - // const wxPoint , const wxSize , - // long style = MYCONTROL_DEFAULT_STYLE, - // const wxString = wxT("MyControl")); - // - // then the XRC for your component should look like: - // - // - // first.xpm - // text.xpm - // 3,3 - // 4,4 - // a title - // - // - // - // - // - // - // and the code to read your custom tags from the XRC file is just: - control->Create(m_parentAsWindow, GetID(), - GetBitmap(wxT("first-bitmap")), - GetPosition(wxT("first-pos")), - GetBitmap(wxT("second-bitmap")), - GetPosition(wxT("second-pos")), - GetText(wxT("the-title")), - GetFont(wxT("title-font")), - GetPosition(), GetSize(), GetStyle(), GetName()); - - SetupWindow(control); - - return control; - } - - bool MyControlXmlHandler::CanHandle(wxXmlNode *node) - { - // this function tells XRC system that this handler can parse - // the object class="MyControl" tags - return IsOfClass(node, wxT("MyControl")); - } - @endcode - - You may want to check the #wxXmlResourceHandler documentation - to see how many built-in getters it contains. It's very easy to retrieve also - complex structures out of XRC files using them. +@page overview_xrc XML Based Resource System + +Classes: wxXmlResource, wxXmlResourceHandler + +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 +into the application at run-time. XRC files can also be compiled into binary +XRS files or C++ code (the former makes it possible to store all resources in a +single file and the latter is useful when you want to embed the resources into +the executable). + +There are several advantages to using XRC resources: + +@li Recompiling and linking an application is not necessary if the resources + change. +@li If you use a dialog designer that generates C++ code, it can be hard to + reintegrate this into existing C++ code. Separation of resources and code + is a more elegant solution. +@li You can choose between different alternative resource files at run time, if + necessary. +@li The XRC format uses sizers for flexibility, allowing dialogs to be + resizable and highly portable. +@li The XRC format is a wxWidgets standard, and can be generated or + postprocessed by any program that understands it. As it is basedon the XML + standard, existing XML editors can be used for simple editing purposes. + +XRC was written by Vaclav Slavik. + +@li @ref overview_xrc_concepts +@li @ref overview_xrc_binaryresourcefiles +@li @ref overview_xrc_embeddedresource +@li @ref overview_xrc_cppsample +@li @ref overview_xrc_sample +@li @ref overview_xrc_fileformat +@li @ref overview_xrc_cppheader +@li @ref overview_xrc_newresourcehandlers + + +
+ + +@section overview_xrc_concepts XRC Concepts + +These are the typical steps for using XRC files in your application. + +@li Include the appropriate headers: normally "wx/xrc/xmlres.h" will suffice. +@li If you are going to use XRS files (see + @ref overview_xrc_binaryresourcefiles), install wxFileSystem archive + handler first with wxFileSystem::AddHandler(new wxArchiveFSHandler); +@li Call wxXmlResource::Get()->InitAllHandlers() from your wxApp::OnInit + function, and then call wxXmlResource::Get()->Load("myfile.xrc") to load + the resource file. +@li To create a dialog from a resource, create it using the default + constructor, and then load it. For example: + wxXmlResource::Get()->LoadDialog(dlg, this, "dlg1"); +@li Set up event tables as usual but use the XRCID(str) macro to translate from + XRC string names to a suitable integer identifier, for example + EVT_MENU(XRCID("quit"), MyFrame::OnQuit). + +To create an XRC file, you can use one of the following methods. + +@li Create the file by hand. +@li Use wxDesigner , a commercial dialog designer/RAD + tool. +@li Use DialogBlocks , a commercial + dialog editor. +@li Use XRCed , a wxPython-based dialog editor that you + can find in the wxPython/tools subdirectory of the wxWidgets SVN archive. +@li Use wxGlade , a GUI designer written in wxPython. + At the moment it can generate Python, C++ and XRC. + +A complete list of third-party tools that write to XRC can be found at +. + +It is highly recommended that you use a resource editing tool, since it's +fiddly writing XRC files by hand. + +You can use wxXmlResource::Load in a number of ways. You can pass an XRC file +(XML-based text resource file) or a zip-compressed file (see +@ref overview_xrc_binaryresourcefiles), with extension ZIP or XRS, containing +other XRC. + +You can also use embedded C++ resources (see +@ref overview_xrc_embeddedresource). + + +@section overview_xrc_binaryresourcefiles Using Binary Resource Files + +To compile binary resource files, use the command-line @c wxrc utility. It +takes one or more file parameters (the input XRC files) and the following +switches and options: + +@li -h (--help): Show a help message. +@li -v (--verbose): Show verbose logging information. +@li -c (--cpp-code): Write C++ source rather than a XRS file. +@li -e (--extra-cpp-code): If used together with -c, generates C++ header file + containing class definitions for the windows defined by the XRC file (see + special subsection). +@li -u (--uncompressed): Do not compress XML files (C++ only). +@li -g (--gettext): Output underscore-wrapped strings that poEdit or gettext + can scan. Outputs to stdout, or a file if -o is used. +@li -n (--function) @: Specify C++ function name (use with -c). +@li -o (--output) @: Specify the output file, such as resource.xrs + or resource.cpp. +@li -l (--list-of-handlers) @: Output a list of necessary handlers + to this file. + +For example: + +@code +$ wxrc resource.xrc +$ wxrc resource.xrc -o resource.xrs +$ wxrc resource.xrc -v -c -o resource.cpp +@endcode + +@note XRS file is essentially a renamed ZIP archive which means that you can +manipulate it with standard ZIP tools. Note that if you are using XRS files, +you have to initialize the wxFileSystem archive handler first! It is a simple +thing to do: + +@code +#include +#include +... +wxFileSystem::AddHandler(new wxArchiveFSHandler); +@endcode + + +@section overview_xrc_embeddedresource Using Embedded Resources + +It is sometimes useful to embed resources in the executable itself instead of +loading an external file (e.g. when your app is small and consists only of one +exe file). XRC provides means to convert resources into regular C++ file that +can be compiled and included in the executable. + +Use the @c -c switch to @c wxrc utility to produce C++ file with embedded +resources. This file will contain a function called @c InitXmlResource (unless +you override this with a command line switch). Use it to load the resource: + +@code +extern void InitXmlResource(); // defined in generated file +... +wxXmlResource::Get()->InitAllHandlers(); +InitXmlResource(); +... +@endcode + + +@section overview_xrc_cppsample XRC C++ Sample + +This is the C++ source file (xrcdemo.cpp) for the XRC sample. + +@code +#include "wx/wx.h" +#include "wx/image.h" +#include "wx/xrc/xmlres.h" + +// the application icon +#if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__) + #include "rc/appicon.xpm" +#endif + +// ---------------------------------------------------------------------------- +// private classes +// ---------------------------------------------------------------------------- + +// Define a new application type, each program should derive a class from wxApp +class MyApp : public wxApp +{ +public: + // override base class virtuals + // ---------------------------- + + // this one is called on application startup and is a good place for the + // app initialization (doing it here and not in the ctor allows to have an + // error return: if OnInit() returns false, the application terminates) + virtual bool OnInit(); +}; + +// Define a new frame type: this is going to be our main frame +class MyFrame : public wxFrame +{ +public: + // ctor(s) + MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size); + + // event handlers (these functions should _not_ be virtual) + void OnQuit(wxCommandEvent& event); + void OnAbout(wxCommandEvent& event); + void OnDlg1(wxCommandEvent& event); + void OnDlg2(wxCommandEvent& event); + +private: + // any class wishing to process wxWidgets events must use this macro + DECLARE_EVENT_TABLE() +}; + +// ---------------------------------------------------------------------------- +// event tables and other macros for wxWidgets +// ---------------------------------------------------------------------------- + +BEGIN_EVENT_TABLE(MyFrame, wxFrame) + EVT_MENU(XRCID("menu_quit"), MyFrame::OnQuit) + EVT_MENU(XRCID("menu_about"), MyFrame::OnAbout) + EVT_MENU(XRCID("menu_dlg1"), MyFrame::OnDlg1) + EVT_MENU(XRCID("menu_dlg2"), MyFrame::OnDlg2) +END_EVENT_TABLE() + +IMPLEMENT_APP(MyApp) + +// ---------------------------------------------------------------------------- +// the application class +// ---------------------------------------------------------------------------- + +// 'Main program' equivalent: the program execution "starts" here +bool MyApp::OnInit() +{ + wxImage::AddHandler(new wxGIFHandler); + wxXmlResource::Get()->InitAllHandlers(); + wxXmlResource::Get()->Load("rc/resource.xrc"); + + MyFrame *frame = new MyFrame("XML resources demo", + wxPoint(50, 50), wxSize(450, 340)); + frame->Show(true); + return true; +} + +// ---------------------------------------------------------------------------- +// main frame +// ---------------------------------------------------------------------------- + +// frame constructor +MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size) +: wxFrame((wxFrame *)NULL, -1, title, pos, size) +{ + SetIcon(wxICON(appicon)); + + SetMenuBar(wxXmlResource::Get()->LoadMenuBar("mainmenu")); + SetToolBar(wxXmlResource::Get()->LoadToolBar(this, "toolbar")); +} + +// event handlers +void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event)) +{ + // true is to force the frame to close + Close(true); +} + +void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event)) +{ + wxString msg; + msg.Printf( _T("This is the about dialog of XML resources demo.\n") + _T("Welcome to %s"), wxVERSION_STRING); + + wxMessageBox(msg, "About XML resources demo", + wxOK | wxICON_INFORMATION, this); +} + +void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event)) +{ + wxDialog dlg; + wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1"); + dlg.ShowModal(); +} + +void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event)) +{ + wxDialog dlg; + wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg2"); + dlg.ShowModal(); +} +@endcode + + +@section overview_xrc_sample XRC Resource File Sample + +This is the XML file (resource.xrc) for the XRC sample. + +@code + + + + + + + + + + filesave.gif + + + + + + + + + + + + + + + + + 2,2 + + fileopen.gif + Open catalog + + + filesave.gif + Save catalog + + + update.gif + Update catalog - synchronize it with sources + + + + quotes.gif + 1 + Display quotes around the string? + + + + fuzzy.gif + Toggled if selected string is fuzzy translation + 1 + + + + + + + fuzzy.gif + fileopen.gif + + + + + + + + + + wxALIGN_CENTER + + + + + + 10d + wxALL + + + +

Hi,

man + 100,45d + + + + + + + + + + Hello, we are inside a NOTEBOOK... + 50,50d + + + + + + + + + + + + + Hello, we are inside a NOTEBOOK... + 50,50d + + + + + + + 1 + + wxEXPAND + + wxVERTICAL + + + + + wxVERTICAL + + + 200,200d + + Hello, this is an ordinary multiline\n textctrl.... + + + wxEXPAND|wxALL + 10 + + + + + + + 1 + + + + + + + 10 + wxLEFT + + + wxLEFT|wxRIGHT|wxBOTTOM|wxALIGN_RIGHT + 10 + + + Second testing dialog + + +@endcode + + +@section overview_xrc_fileformat XRC File Format + +Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWidgets +distribution. + + +@section overview_xrc_cppheader C++ header file generation + +Using the @c -e switch together with @c -c, a C++ header file is written +containing class definitions for the GUI windows defined in the XRC file. This +code generation can make it easier to use XRC and automate program development. +The classes can be used as basis for development, freeing the programmer from +dealing with most of the XRC specifics (e.g. @c XRCCTRL). + +For each top level window defined in the XRC file a C++ class definition is +generated, containing as class members the named widgets of the window. A +default constructor for each class is also generated. Inside the constructor +all XRC loading is done and all class members representing widgets are +initialized. + +A simple example will help understand how the scheme works. Suppose you have a +XRC file defining a top level window @c TestWnd_Base, which subclasses wxFrame +(any other class like @c wxDialog will do also), and has subwidgets wxTextCtrl A +and wxButton B. + +The XRC file and corresponding class definition in the header file will be +something like: + +@code + + + + -1,-1 + Test + + wxHORIZONTAL + + + + + + + + + + + + + + + +class TestWnd_Base : public wxFrame +{ +protected: + wxTextCtrl* A; + wxButton* B; + +private: + void InitWidgetsFromXRC() + { + wxXmlResource::Get()->LoadObject(this, NULL, "TestWnd", "wxFrame"); + A = XRCCTRL(*this, "A", wxTextCtrl); + B = XRCCTRL(*this, "B", wxButton); + } +public: + TestWnd::TestWnd() + { + InitWidgetsFromXRC(); + } +}; +@endcode + +The generated window class can be used as basis for the full window class. The +class members which represent widgets may be accessed by name instead of using +@c XRCCTRL every time you wish to reference them (note that they are +@c protected class members), though you must still use @c XRCID to refer to +widget IDs in the event table. + +Example: + +@code +#include "resource.h" + +class TestWnd : public TestWnd_Base +{ +public: + TestWnd() + { + // A, B already initialised at this point + A->SetValue("Updated in TestWnd::TestWnd"); + B->SetValue("Nice :)"); + } + void OnBPressed(wxEvent& event) + { + Close(); + } + DECLARE_EVENT_TABLE(); +}; + +BEGIN_EVENT_TABLE(TestWnd,TestWnd_Base) + EVT_BUTTON(XRCID("B"), TestWnd::OnBPressed) +END_EVENT_TABLE() +@endcode + +It is also possible to access the wxSizerItem of a sizer that is part of a +resource. This can be done using @c XRCSIZERITEM as shown. + +The resource file can have something like this for a sizer item. + +@code + + 400, 300 + +@endcode + +The code can then access the sizer item by using @c XRCSIZERITEM and @c XRCID +together. + +@code +wxSizerItem* item = XRCSIZERITEM(*this, "area"); +@endcode + + +@section overview_xrc_newresourcehandlers Adding New Resource Handlers + +Adding a new resource handler is pretty easy. + +Typically, to add an handler for the @c MyControl class, you'll want to create +the @c xh_mycontrol.h and @c xh_mycontrol.cpp files. + +The header needs to contains the @c MyControlXmlHandler class definition: + +@code +class MyControlXmlHandler : public wxXmlResourceHandler +{ +public: + // Constructor. + MyControlXmlHandler(); + + // Creates the control and returns a pointer to it. + virtual wxObject *DoCreateResource(); + + // Returns true if we know how to create a control for the given node. + virtual bool CanHandle(wxXmlNode *node); + + // Register with wxWidgets' dynamic class subsystem. + DECLARE_DYNAMIC_CLASS(MyControlXmlHandler) +}; +@endcode + +The implementation of your custom XML handler will typically look as: + +@code +// Register with wxWidgets' dynamic class subsystem. +IMPLEMENT_DYNAMIC_CLASS(MyControlXmlHandler, wxXmlResourceHandler) + +MyControlXmlHandler::MyControlXmlHandler() +{ + // this call adds support for all wxWindows class styles + // (e.g. wxBORDER_SIMPLE, wxBORDER_SUNKEN, wxWS_EX_* etc etc) + AddWindowStyles(); + + // if MyControl class supports e.g. MYCONTROL_DEFAULT_STYLE + // you should use: + // XRC_ADD_STYLE(MYCONTROL_DEFAULT_STYLE); +} + +wxObject *MyControlXmlHandler::DoCreateResource() +{ + // the following macro will init a pointer named "control" + // with a new instance of the MyControl class, but will NOT + // Create() it! + XRC_MAKE_INSTANCE(control, MyControl) + + // this is the point where you'll typically need to do the most + // important changes: here the control is created and initialized. + // You'll want to use the wxXmlResourceHandler's getters to + // do most of your work. + // If e.g. the MyControl::Create function looks like: + // + // bool MyControl::Create(wxWindow *parent, int id, + // const wxBitmap &first, const wxPoint &posFirst, + // const wxBitmap &second, const wxPoint &posSecond, + // const wxString &theTitle, const wxFont &titleFont, + // const wxPoint &pos, const wxSize &size, + // long style = MYCONTROL_DEFAULT_STYLE, + // const wxString &name = wxT("MyControl")); + // + // Then the XRC for your component should look like: + // + // + // first.xpm + // text.xpm + // 3,3 + // 4,4 + // a title + // + // + // + // + // + // + // And the code to read your custom tags from the XRC file is just: + control->Create(m_parentAsWindow, GetID(), + GetBitmap(wxT("first-bitmap")), + GetPosition(wxT("first-pos")), + GetBitmap(wxT("second-bitmap")), + GetPosition(wxT("second-pos")), + GetText(wxT("the-title")), + GetFont(wxT("title-font")), + GetPosition(), GetSize(), GetStyle(), GetName()); + + SetupWindow(control); + + return control; +} + +bool MyControlXmlHandler::CanHandle(wxXmlNode *node) +{ + // this function tells XRC system that this handler can parse + // the tags + return IsOfClass(node, wxT("MyControl")); +} +@endcode + +You may want to check the wxXmlResourceHandler documentation to see how many +built-in getters it contains. It's very easy to retrieve also complex +structures out of XRC files using them. */ -- 2.45.2