/////////////////////////////////////////////////////////////////////////////
-// Name: validator
+// Name: validator.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @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.
+
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: windowdeletion
+// Name: windowdeletion.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @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.
+
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: windowsizing
+// Name: windowsizing.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @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.
+
+*/
/*!
- @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
-
-
- <hr>
-
-
- @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 <tt>EVT_MENU(XRCID("quit"), MyFrame::OnQuit)</tt>.
-
- 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
- <?xml version="1.0"?>
- <resource version="2.3.0.1">
- <object class="wxMenuBar" name="mainmenu">
- <style>wxMB_DOCKABLE</style>
- <object class="wxMenu" name="menu_file">
- <label>_File</label>
- <style>wxMENU_TEAROFF</style>
- <object class="wxMenuItem" name="menu_about">
- <label>_About...</label>
- <bitmap>filesave.gif</bitmap>
- </object>
- <object class="separator"/>
- <object class="wxMenuItem" name="menu_dlg1">
- <label>Dialog 1</label>
- </object>
- <object class="wxMenuItem" name="menu_dlg2">
- <label>Dialog 2</label>
- </object>
- <object class="separator"/>
- <object class="wxMenuItem" name="menu_quit">
- <label>E_xit\tAlt-X</label>
- </object>
- </object>
- </object>
- <object class="wxToolBar" name="toolbar">
- <style>wxTB_FLAT|wxTB_DOCKABLE</style>
- <margins>2,2</margins>
- <object class="tool" name="menu_open">
- <bitmap>fileopen.gif</bitmap>
- <tooltip>Open catalog</tooltip>
- </object>
- <object class="tool" name="menu_save">
- <bitmap>filesave.gif</bitmap>
- <tooltip>Save catalog</tooltip>
- </object>
- <object class="tool" name="menu_update">
- <bitmap>update.gif</bitmap>
- <tooltip>Update catalog - synchronize it with sources</tooltip>
- </object>
- <separator/>
- <object class="tool" name="menu_quotes">
- <bitmap>quotes.gif</bitmap>
- <toggle>1</toggle>
- <tooltip>Display quotes around the string?</tooltip>
- </object>
- <object class="separator"/>
- <object class="tool" name="menu_fuzzy">
- <bitmap>fuzzy.gif</bitmap>
- <tooltip>Toggled if selected string is fuzzy translation</tooltip>
- <toggle>1</toggle>
- </object>
- </object>
- <object class="wxDialog" name="dlg1">
- <object class="wxBoxSizer">
- <object class="sizeritem">
- <object class="wxBitmapButton">
- <bitmap>fuzzy.gif</bitmap>
- <focus>fileopen.gif</focus>
- </object>
- </object>
- <object class="sizeritem">
- <object class="wxPanel">
- <object class="wxStaticText">
- <label>fdgdfgdfgdfg</label>
- </object>
- <style>wxBORDER\_SUNKEN</style>
- </object>
- <flag>wxALIGN_CENTER</flag>
- </object>
- <object class="sizeritem">
- <object class="wxButton">
- <label>Buttonek</label>
- </object>
- <border>10d</border>
- <flag>wxALL</flag>
- </object>
- <object class="sizeritem">
- <object class="wxHtmlWindow">
- <htmlcode><h1>Hi,</h1>man</htmlcode>
- <size>100,45d</size>
- </object>
- </object>
- <object class="sizeritem">
- <object class="wxNotebook">
- <object class="notebookpage">
- <object class="wxPanel">
- <object class="wxBoxSizer">
- <object class="sizeritem">
- <object class="wxHtmlWindow">
- <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
- <size>50,50d</size>
- </object>
- <option>1</option>
- </object>
- </object>
- </object>
- <label>Page</label>
- </object>
- <object class="notebookpage">
- <object class="wxPanel">
- <object class="wxBoxSizer">
- <object class="sizeritem">
- <object class="wxHtmlWindow">
- <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
- <size>50,50d</size>
- </object>
- </object>
- </object>
- </object>
- <label>Page 2</label>
- </object>
- <usenotebooksizer>1</usenotebooksizer>
- </object>
- <flag>wxEXPAND</flag>
- </object>
- <orient>wxVERTICAL</orient>
- </object>
- </object>
- <object class="wxDialog" name="dlg2">
- <object class="wxBoxSizer">
- <orient>wxVERTICAL</orient>
- <object class="sizeritem" name="dfgdfg">
- <object class="wxTextCtrl">
- <size>200,200d</size>
- <style>wxTE_MULTILINE|wxBORDER_SUNKEN</style>
- <value>Hello, this is an ordinary multiline\n textctrl....</value>
- </object>
- <option>1</option>
- <flag>wxEXPAND|wxALL</flag>
- <border>10</border>
- </object>
- <object class="sizeritem">
- <object class="wxBoxSizer">
- <object class="sizeritem">
- <object class="wxButton" name="wxID_OK">
- <label>Ok</label>
- <default>1</default>
- </object>
- </object>
- <object class="sizeritem">
- <object class="wxButton" name="wxID_CANCEL">
- <label>Cancel</label>
- </object>
- <border>10</border>
- <flag>wxLEFT</flag>
- </object>
- </object>
- <flag>wxLEFT|wxRIGHT|wxBOTTOM|wxALIGN_RIGHT</flag>
- <border>10</border>
- </object>
- </object>
- <title>Second testing dialog</title>
- </object>
- </resource>
- @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
- <?xml version="1.0"?>
- <resource version="2.3.0.1">
- <object class="wxFrame" name="TestWnd_Base">
- <size>-1,-1</size>
- <title>Test</title>
- <object class="wxBoxSizer">
- <orient>wxHORIZONTAL</orient>
- <object class="sizeritem">
- <object class="wxTextCtrl" name="A">
- <label>Test label</label>
- </object>
- </object>
- <object class="sizeritem">
- <object class="wxButton" name="B">
- <label>Test button</label>
- </object>
- </object>
- </object>
- </object>
- </resource>
-
-
- 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
- <object class="spacer" name="area">
- <size>400, 300</size>
- </object>
- @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:
- //
- // <object class="MyControl" name="some_name">
- // <first-bitmap>first.xpm</first-bitmap>
- // <second-bitmap>text.xpm</second-bitmap>
- // <first-pos>3,3</first-pos>
- // <second-pos>4,4</second-pos>
- // <the-title>a title</the-title>
- // <title-font>
- // <!-- the standard XRC tags for describing a font: <size>, <style>, <weight>, etc -->
- // </title-font>
- // <!-- XRC also accepts other usual tags for wxWindow-derived classes:
- // like e.g. <name>, <style>, <size>, <position>, etc -->
- // </object>
- //
- // 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
+
+
+<hr>
+
+
+@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
+ <tt>EVT_MENU(XRCID("quit"), MyFrame::OnQuit)</tt>.
+
+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 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 @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
+<?xml version="1.0"?>
+<resource version="2.3.0.1">
+ <object class="wxMenuBar" name="mainmenu">
+ <style>wxMB_DOCKABLE</style>
+ <object class="wxMenu" name="menu_file">
+ <label>_File</label>
+ <style>wxMENU_TEAROFF</style>
+ <object class="wxMenuItem" name="menu_about">
+ <label>_About...</label>
+ <bitmap>filesave.gif</bitmap>
+ </object>
+ <object class="separator"/>
+ <object class="wxMenuItem" name="menu_dlg1">
+ <label>Dialog 1</label>
+ </object>
+ <object class="wxMenuItem" name="menu_dlg2">
+ <label>Dialog 2</label>
+ </object>
+ <object class="separator"/>
+ <object class="wxMenuItem" name="menu_quit">
+ <label>E_xit\tAlt-X</label>
+ </object>
+ </object>
+ </object>
+ <object class="wxToolBar" name="toolbar">
+ <style>wxTB_FLAT|wxTB_DOCKABLE</style>
+ <margins>2,2</margins>
+ <object class="tool" name="menu_open">
+ <bitmap>fileopen.gif</bitmap>
+ <tooltip>Open catalog</tooltip>
+ </object>
+ <object class="tool" name="menu_save">
+ <bitmap>filesave.gif</bitmap>
+ <tooltip>Save catalog</tooltip>
+ </object>
+ <object class="tool" name="menu_update">
+ <bitmap>update.gif</bitmap>
+ <tooltip>Update catalog - synchronize it with sources</tooltip>
+ </object>
+ <separator/>
+ <object class="tool" name="menu_quotes">
+ <bitmap>quotes.gif</bitmap>
+ <toggle>1</toggle>
+ <tooltip>Display quotes around the string?</tooltip>
+ </object>
+ <object class="separator"/>
+ <object class="tool" name="menu_fuzzy">
+ <bitmap>fuzzy.gif</bitmap>
+ <tooltip>Toggled if selected string is fuzzy translation</tooltip>
+ <toggle>1</toggle>
+ </object>
+ </object>
+ <object class="wxDialog" name="dlg1">
+ <object class="wxBoxSizer">
+ <object class="sizeritem">
+ <object class="wxBitmapButton">
+ <bitmap>fuzzy.gif</bitmap>
+ <focus>fileopen.gif</focus>
+ </object>
+ </object>
+ <object class="sizeritem">
+ <object class="wxPanel">
+ <object class="wxStaticText">
+ <label>fdgdfgdfgdfg</label>
+ </object>
+ <style>wxBORDER\_SUNKEN</style>
+ </object>
+ <flag>wxALIGN_CENTER</flag>
+ </object>
+ <object class="sizeritem">
+ <object class="wxButton">
+ <label>Buttonek</label>
+ </object>
+ <border>10d</border>
+ <flag>wxALL</flag>
+ </object>
+ <object class="sizeritem">
+ <object class="wxHtmlWindow">
+ <htmlcode><h1>Hi,</h1>man</htmlcode>
+ <size>100,45d</size>
+ </object>
+ </object>
+ <object class="sizeritem">
+ <object class="wxNotebook">
+ <object class="notebookpage">
+ <object class="wxPanel">
+ <object class="wxBoxSizer">
+ <object class="sizeritem">
+ <object class="wxHtmlWindow">
+ <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
+ <size>50,50d</size>
+ </object>
+ <option>1</option>
+ </object>
+ </object>
+ </object>
+ <label>Page</label>
+ </object>
+ <object class="notebookpage">
+ <object class="wxPanel">
+ <object class="wxBoxSizer">
+ <object class="sizeritem">
+ <object class="wxHtmlWindow">
+ <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
+ <size>50,50d</size>
+ </object>
+ </object>
+ </object>
+ </object>
+ <label>Page 2</label>
+ </object>
+ <usenotebooksizer>1</usenotebooksizer>
+ </object>
+ <flag>wxEXPAND</flag>
+ </object>
+ <orient>wxVERTICAL</orient>
+ </object>
+ </object>
+ <object class="wxDialog" name="dlg2">
+ <object class="wxBoxSizer">
+ <orient>wxVERTICAL</orient>
+ <object class="sizeritem" name="dfgdfg">
+ <object class="wxTextCtrl">
+ <size>200,200d</size>
+ <style>wxTE_MULTILINE|wxBORDER_SUNKEN</style>
+ <value>Hello, this is an ordinary multiline\n textctrl....</value>
+ </object>
+ <option>1</option>
+ <flag>wxEXPAND|wxALL</flag>
+ <border>10</border>
+ </object>
+ <object class="sizeritem">
+ <object class="wxBoxSizer">
+ <object class="sizeritem">
+ <object class="wxButton" name="wxID_OK">
+ <label>Ok</label>
+ <default>1</default>
+ </object>
+ </object>
+ <object class="sizeritem">
+ <object class="wxButton" name="wxID_CANCEL">
+ <label>Cancel</label>
+ </object>
+ <border>10</border>
+ <flag>wxLEFT</flag>
+ </object>
+ </object>
+ <flag>wxLEFT|wxRIGHT|wxBOTTOM|wxALIGN_RIGHT</flag>
+ <border>10</border>
+ </object>
+ </object>
+ <title>Second testing dialog</title>
+ </object>
+</resource>
+@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
+<?xml version="1.0"?>
+<resource version="2.3.0.1">
+ <object class="wxFrame" name="TestWnd_Base">
+ <size>-1,-1</size>
+ <title>Test</title>
+ <object class="wxBoxSizer">
+ <orient>wxHORIZONTAL</orient>
+ <object class="sizeritem">
+ <object class="wxTextCtrl" name="A">
+ <label>Test label</label>
+ </object>
+ </object>
+ <object class="sizeritem">
+ <object class="wxButton" name="B">
+ <label>Test button</label>
+ </object>
+ </object>
+ </object>
+ </object>
+</resource>
+
+
+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
+<object class="spacer" name="area">
+ <size>400, 300</size>
+</object>
+@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:
+ //
+ // <object class="MyControl" name="some_name">
+ // <first-bitmap>first.xpm</first-bitmap>
+ // <second-bitmap>text.xpm</second-bitmap>
+ // <first-pos>3,3</first-pos>
+ // <second-pos>4,4</second-pos>
+ // <the-title>a title</the-title>
+ // <title-font>
+ // <!-- Standard XRC tags for a font: <size>, <style>, <weight>, etc -->
+ // </title-font>
+ // <!-- XRC also accepts other usual tags for wxWindow-derived classes:
+ // like e.g. <name>, <style>, <size>, <position>, etc -->
+ // </object>
+ //
+ // 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.
*/
projects / wxWidgets.git / commitdiff
