Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More doxygen topic overview cleanup.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52244 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-03-02 10:48:31 +00:00
parent 2cd3cc948e
commit 3863c5ebd9
7 changed files with 1048 additions and 1063 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/doxygen/overviews/unicode.h
View File

@@ -110,7 +110,7 @@ in both ANSI and Unicode modes could look like:
@endcode @endcode
Of course, it would be nearly impossibly to write such programs if it had to 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. program would have had!). Luckily, there is another way - see the next section.

153
docs/doxygen/overviews/validator.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: validator // Name: validator.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,102 +8,107 @@
/*! /*!
@page overview_validator wxValidator overview @page overview_validator wxValidator Overview
Classes: #wxValidator, #wxTextValidator, Classes: wxValidator, wxTextValidator, wxGenericValidator
#wxGenericValidator
The aim of the validator concept is to make dialogs very much easier to write. 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 A validator is an object that can be plugged into a control (such as a
mediates between C++ data and the control, transferring the data in either direction wxTextCtrl), and mediates between C++ data and the control, transferring the
and validating it. It also is able to intercept events generated data in either direction and validating it. It also is able to intercept events
by the control, providing filtering behaviour without the need to derive a new control class. 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 You can use a stock validator, such as wxTextValidator (which does text control
control data transfer, validation and filtering) and data transfer, validation and filtering) and wxGenericValidator (which does
#wxGenericValidator (which does data transfer for a range of controls); data transfer for a range of controls); or you can write your own.
or you can write your own.
@section example Example
@section overview_validator_example Example
Here is an example of wxTextValidator usage. Here is an example of wxTextValidator usage.
@code @code
wxTextCtrl *txt1 = new wxTextCtrl(this, -1, wxT(""), wxTextCtrl *txt1 = new wxTextCtrl(
wxPoint(10, 10), wxSize(100, 80), 0, this, -1, wxT(""), wxPoint(10, 10), wxSize(100, 80), 0,
wxTextValidator(wxFILTER_ALPHA, _data.m_string)); wxTextValidator(wxFILTER_ALPHA, &g_data.m_string));
@endcode @endcode
In this example, the text validator object provides the following functionality: 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 @li It transfers the value of g_data.m_string (a wxString variable) to the
the dialog is initialised. wxTextCtrl when the dialog is initialised.
@li It transfers the wxTextCtrl data back to this variable when the dialog is dismissed. @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. @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, The validation and filtering of input is accomplished in two ways. When a
wxTextValidator checks the character against the allowed filter flag (wxFILTER_ALPHA in this case). If character is input, wxTextValidator checks the character against the allowed
the character is inappropriate, it is vetoed (does not appear) and a warning beep sounds. filter flag (wxFILTER_ALPHA in this case). If the character is inappropriate,
The second type of validation is performed when the dialog is about to be dismissed, so if it is vetoed (does not appear) and a warning beep sounds. The second type of
the default string contained invalid characters already, a dialog box is shown giving the validation is performed when the dialog is about to be dismissed, so if the
error, and the dialog is not dismissed. 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. @section overview_validator_anatomy Anatomy of a Validator
A validator constructor is responsible for allowing the programmer to specify the kind A programmer creating a new validator class should provide the following
of validation required, and perhaps a pointer to a C++ variable that is used for storing the functionality.
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 A validator constructor is responsible for allowing the programmer to specify
@true if the data in the control (not the C++ variable) is valid. It should also show the kind of validation required, and perhaps a pointer to a C++ variable that
an appropriate message if data was not valid. 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::TransferToWindow member function should The wxValidator::Validate member function should return @true if the data in
transfer the data from the validator or associated C++ variable to the control. the control (not the C++ variable) is valid. It should also show an appropriate
message if data was not valid.
The wxValidator::TransferFromWindow member function should The wxValidator::TransferToWindow member function should transfer the data from
transfer the data from the control to the validator or associated C++ variable. the validator or associated C++ variable to the control.
There should be a copy constructor, and a wxValidator::Clone function The wxValidator::TransferFromWindow member function should transfer the data
which returns a copy of the validator object. This is important because validators from the control to the validator or associated C++ variable.
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 There should be a copy constructor, and a wxValidator::Clone function which
will capture events before the control itself does. returns a copy of the validator object. This is important because validators
For an example implementation, see the valtext.h and valtext.cpp files in the wxWidgets library. are passed by reference to window constructors, and must therefore be cloned
internally.
@section dialogs How validators interact with dialogs 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.
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) @section overview_validator_dialogs How Validators Interact with Dialogs
or wxDialog::ShowModal is called (for a modal dialog),
the function wxWindow::InitDialog is automatically called. For validators to work correctly, validator functions must be called at the
This in turn sends an initialisation event to the dialog. The default handler for right times during dialog initialisation and dismissal.
the wxEVT_INIT_DIALOG event is defined in the wxWindow class to simply call
the function wxWindow::TransferDataToWindow. This When a wxDialog::Show is called (for a modeless dialog) or wxDialog::ShowModal
function finds all the validators in the window's children and calls the TransferToWindow is called (for a modal dialog), the function wxWindow::InitDialog is
function for each. Thus, data is transferred from C++ variables to the dialog automatically called. This in turn sends an initialisation event to the dialog.
just as the dialog is being shown. 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 @note If you are using a window or panel instead of a dialog, you will need to
call wxWindow::InitDialog explicitly before showing the call wxWindow::InitDialog explicitly before showing the window.
window.
When the user clicks on a button, for example the OK button, the application should When the user clicks on a button, for example the OK button, the application
first call wxWindow::Validate, which returns @false if should first call wxWindow::Validate, which returns @false if any of the child
any of the child window validators failed to validate the window data. The button handler window validators failed to validate the window data. The button handler should
should return immediately if validation failed. Secondly, the application should return immediately if validation failed. Secondly, the application should call
call wxWindow::TransferDataFromWindow and wxWindow::TransferDataFromWindow and return if this failed. It is then safe to
return if this failed. It is then safe to end the dialog by calling EndModal (if modal) end the dialog by calling EndModal (if modal) or Show (if modeless).
or Show (if modeless).
In fact, wxDialog contains a default command event handler for the wxID_OK button. It goes like In fact, wxDialog contains a default command event handler for the wxID_OK
this: button. It goes like this:
@code @code
void wxDialog::OnOK(wxCommandEvent& event) void wxDialog::OnOK(wxCommandEvent& event)
@@ -115,18 +120,18 @@
else else
{ {
SetReturnCode(wxID_OK); SetReturnCode(wxID_OK);
this-Show(@false); this->Show(false);
} }
} }
} }
@endcode @endcode
So if using validators and a normal OK button, you may not even need to write any So if using validators and a normal OK button, you may not even need to write
code for handling dialog dismissal. any code for handling dialog dismissal.
If you load your dialog from a resource file, you will need to iterate through the controls If you load your dialog from a resource file, you will need to iterate through
setting validators, since validators can't be specified in a dialog resource. the controls setting validators, since validators can't be specified in a
dialog resource.
*/ */

162
docs/doxygen/overviews/windowdeletion.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: windowdeletion // Name: windowdeletion.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,135 +8,103 @@
/*! /*!
@page overview_windowdeletion Window deletion overview @page overview_windowdeletion Window Deletion Overview
Classes: #wxCloseEvent, #wxWindow Classes: wxCloseEvent, wxWindow
Window deletion can be a confusing subject, so this overview is provided Window deletion can be a confusing subject, so this overview is provided to
to help make it clear when and how you delete windows, or respond to user requests help make it clear when and how you delete windows, or respond to user requests
to close windows. 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, @section overview_windowdeletion_sequence Sequence of Events During Window Deletion
in a frame or a dialog, wxWidgets calls wxWindow::Close. This
in turn generates an EVT_CLOSE event: see #wxCloseEvent. 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 It is the duty of the application to define a suitable event handler, and
decide whether or not to destroy the window. decide whether or not to destroy the window. If the application is for some
If the application is for some reason forcing the application to close reason forcing the application to close (wxCloseEvent::CanVeto returns @false),
(wxCloseEvent::CanVeto returns @false), the window should always be destroyed, otherwise there is the option to the window should always be destroyed, otherwise there is the option to ignore
ignore the request, or maybe wait until the user has answered a question the request, or maybe wait until the user has answered a question before
before deciding whether it is safe to close. The handler for EVT_CLOSE should deciding whether it is safe to close. The handler for EVT_CLOSE should signal
signal to the calling code if it does not destroy the window, by calling to the calling code if it does not destroy the window, by calling
wxCloseEvent::Veto. Calling this provides useful information wxCloseEvent::Veto. Calling this provides useful information to the calling
to the calling code. code.
The wxCloseEvent handler should only call wxWindow::Destroy to The wxCloseEvent handler should only call wxWindow::Destroy to delete the
delete the window, and not use the @b delete operator. This is because window, and not use the @c delete operator. This is because for some window
for some window classes, wxWidgets delays actual deletion of the window until all events have been processed, classes, wxWidgets delays actual deletion of the window until all events have
since otherwise there is the danger that events will be sent to a non-existent window. 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 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 will be destroyed. Call wxWindow::Destroy if you want to be
certain that the window is destroyed. 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 @section overview_windowdeletion_close Closing Windows
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 Your application can either use wxWindow::Close event just as the framework
defined by the EVT_CLOSE handler; for example it may close a document contained in does, or it can call wxWindow::Destroy directly. If using Close(), you can pass
a window after first asking the user whether the work should be saved. Close can be vetoed a @true argument to this function to tell the event handler that we definitely
by this process (return @false), whereas Destroy definitely destroys the window. want to delete the frame and it cannot be vetoed.
@section default What is the default behaviour? 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, The default close event handler for wxDialog simulates a Cancel command,
generating a wxID_CANCEL event. Since the handler for this cancel event might 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 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). for wxID_CANCEL hides the dialog (if modeless) or calls EndModal(wxID_CANCEL)
In other words, by default, the dialog @e is not destroyed (it might have been created (if modal). In other words, by default, the dialog @e is not destroyed (it
on the stack, so the assumption of dynamic creation cannot be made). 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(). 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 @section overview_windowdeletion_menuexit User Calls to Exit From a Menu
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, What should I do when the user calls up Exit from a menu? You can simply call
either from within your close event handler, or from within your exit menu command wxWindow::Close on the frame. This will invoke your own close event handler
handler. For example, you may wish to check that all files have been saved. which may destroy the frame.
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? 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.
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 @section overview_windowdeletion_exitapp Exiting the Application Gracefully
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 A wxWidgets application automatically exits when the last top level window
(#wxFrame or #wxDialog), is destroyed. Put (wxFrame or wxDialog), is destroyed. Put any application-wide cleanup code in
any application-wide cleanup code in wxApp::OnExit (this wxApp::OnExit (this is a virtual function, not an event handler).
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 @section overview_windowdeletion_deletion Automatic Deletion of Child Windows
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? 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.
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 @section overview_windowdeletion_windowkinds Other Kinds of Windows
close event handlers, though you can implement them if you wish. For consistency,
continue to use the wxWindow::Destroy function instead So far we've been talking about 'managed' windows, i.e. frames and dialogs.
of the @b delete operator when deleting these kinds of windows explicitly. 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.
*/ */

114
docs/doxygen/overviews/windowids.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: windowids // Name: windowids.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,73 +8,81 @@
/*! /*!
@page overview_windowids Window IDs overview @page overview_windowids Window IDs Overview
@li @ref overview_windowids_intro
@li @ref overview_windowids_type
@li @ref overview_windowids_using
@seealso @seealso
#wxIdManager
wxWindow::NewControlId
wxWindow::UnreserveControlId
@li @ref introduction @li wxIdManager
@li @ref overview_windowidstypes @li wxWindow::NewControlId
@li @ref overview_windowidsusing @li wxWindow::UnreserveControlId
@section introduction Introduction <hr>
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, @section overview_windowids_intro Introduction
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 Various contols and other parts of wxWidgets need an ID. Sometimes the ID may
more than enough IDs and it would take a very very long time to run out and be directly provided by the use or have a predefined value, such as
wrap around. However, some systems can not use the full range of the ID value. @c wxID_OPEN. Often, however, the value of the ID is unimportant and is created
Windows, for example, can only use 16 bit IDs, and only has about 32000 possible automatically by calling wxWindow::NewControlId or by passing @c wxID_ANY as
automatic IDs that can be generated by wxWindow::NewControlId. the ID of an object.
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 There are two ways to generate an ID. One way, is to start at a negative
clashes with any directly specified ID values. 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 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 and don't return them again until the ID is completely free and not being used
any other objects. This will make sure that the ID values do not clash with one by any other objects. This will make sure that the ID values do not clash with
another. This is accomplished by keeping a reference count for each of the IDs one another. This is accomplished by keeping a reference count for each of the
that can possibly be returned by wxWindow::NewControlId. IDs that can possibly be returned by wxWindow::NewControlId. Other IDs are not
Other IDs are not reference counted. reference counted.
@section overview_windowidstypes Data types
A wxWindowID is just the integer type for a window ID. It should be used almost @section overview_windowids_type Data Types
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 A wxWindowID is just the integer type for a window ID. It should be used
is unreserved manually with wxWindow::UnreserveControlId. almost everywhere. To help keep track of the count for the automatically
However, if it is assigned to a wxWindowIDRef, then it will be unreserved automatically generated IDs, a new type, wxWindowIDRef exists, that can take the place of
and will be considered free when the count is 0, and should NOT be manually unreserved. 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.
wxWindowIDRef can store both automatic IDs from wxWindow::NewControlId If a created ID is not assigned to a wxWindowIDRef, then it remains reserved
as well as normal IDs. Reference counting is only done for the automatic IDs. Also, until it is unreserved manually with wxWindow::UnreserveControlId. However, if
wxWindowIDRef has conversion operators that allow it to be treated just like a wxWindowID. 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.
@section overview_windowidsusing Using wxWindowIDRef 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.
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 @section overview_windowids_using Using wxWindowIDRef
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. A wxWindowIDRef should be used in place of a wxWindowID where you want to make
It should only be used in the main thread, as it is not thread safe. 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.
*/ */

165
docs/doxygen/overviews/windowsizing.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: windowsizing // Name: windowsizing.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -10,100 +10,91 @@
@page overview_windowsizing Window Sizing Overview @page overview_windowsizing Window Sizing Overview
It can sometimes be confusing to keep track of the various It can sometimes be confusing to keep track of the various size-related
size-related attributes of a #wxWindow, how they attributes of a wxWindow, how they relate to each other, and how they interact
relate to each other, and how they interact with sizers. This document with sizers. This document will attempt to clear the fog a little, and give
will attempt to clear the fog a little, and give some simple some simple explanations of things.
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:
@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. -# 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 layout constraints then that is used to
-# Otherwise if the window has children then the best size is set to be large enough to show all the children. calculate the best size.
-# Otherwise if there are no children then the window's min size will be used for the best size. -# Otherwise if the window has children then the best size is set to be large
-# Otherwise if there is no min size set, then the current size is used for the best size. 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 MinSize: The min size of a widget is a size that is normally @b Size: The size of a widget can be explicitly set or fetched with the
explicitly set by the programmer either with the @c SetMinSize() @c SetSize() or @c GetSize() methods. This size value is the size that the
method or the @c SetSizeHints() method. Most controls will also widget is currently using on screen and is the way to change the size of
set the min size to the size given in the control's constructor if a something that is not being managed by a sizer.
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 @b ClientSize: The client size represents the widget's area inside of any
the @c SetSize() or @c GetSize() methods. This size value borders belonging to the widget and is the area that can be drawn upon in a
is the size that the widget is currently using on screen and is the @c EVT_PAINT event. If a widget doesn't have a border then its client size is
way to change the size of something that is not being managed by a 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. sizer.
@b ClientSize: The client size represents the widget's area inside @b window.Layout(): If the window has a sizer then it sets the space given to
of any borders belonging to the widget and is the area that can be the sizer to the current size of the window, which results in a call to
drawn upon in a @c EVT_PAINT event. If a widget doesn't have a @c sizer.Layout(). If the window has layout constraints instead of a sizer then
border then its client size is the same as its size. the constraints algorithm is run. The @c Layout() method is what is called by
the default @c EVT_SIZE handler for container windows.
@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.
*/ */

18
docs/doxygen/overviews/windowstyles.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: windowstyles // Name: windowstyles.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // 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 Window styles are used to specify alternative behaviour and appearances for
created. The symbols are defined in such a way that they can be combined in a 'bit-list' using the windows, when they are created. The symbols are defined in such a way that they
C++ @e bitwise-or operator. For example: can be combined in a 'bit-list' using the C++ @e bitwise-or operator. For
example:
@code @code
wxCAPTION | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER wxCAPTION | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER
@endcode @endcode
For the window styles specific to each window class, please see the documentation For the window styles specific to each window class, please see the
for the window. Most windows can use the generic styles listed for #wxWindow in documentation for the window. Most windows can use the generic styles listed
addition to their own styles. for wxWindow in addition to their own styles.
*/ */

269
docs/doxygen/overviews/xrc.h
View File

@@ -8,31 +8,31 @@
/*! /*!
@page overview_xrc XML-based resource system overview @page overview_xrc XML Based Resource System
Classes: #wxXmlResource, #wxXmlResourceHandler Classes: wxXmlResource, wxXmlResourceHandler
The XML-based resource system, known as XRC, allows user interface elements such The XML-based resource system, known as XRC, allows user interface elements
as dialogs, menu bars and toolbars, to be stored in text files and loaded into such as dialogs, menu bars and toolbars, to be stored in text files and loaded
the application at run-time. XRC files can also be compiled into binary XRS files into the application at run-time. XRC files can also be compiled into binary
or C++ code (the former makes it possible to store all resources in a single file XRS files or C++ code (the former makes it possible to store all resources in a
and the latter is useful when you want to embed the resources into the executable). 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. There are several advantages to using XRC resources:
@li Recompiling and linking an application is not necessary if the @li Recompiling and linking an application is not necessary if the resources
resources change. change.
@li If you use a dialog designer that generates C++ code, it can be hard @li If you use a dialog designer that generates C++ code, it can be hard to
to reintegrate this into existing C++ code. Separation of resources and code reintegrate this into existing C++ code. Separation of resources and code
is a more elegant solution. is a more elegant solution.
@li You can choose between different alternative resource files at run time, @li You can choose between different alternative resource files at run time, if
if necessary. necessary.
@li The XRC format uses sizers for flexibility, allowing dialogs to be resizable @li The XRC format uses sizers for flexibility, allowing dialogs to be
and highly portable. resizable and highly portable.
@li The XRC format is a wxWidgets standard, @li The XRC format is a wxWidgets standard, and can be generated or
and can be generated or postprocessed by any program that understands it. postprocessed by any program that understands it. As it is basedon the XML
As it is basedon the XML standard, existing XML editors can be used for standard, existing XML editors can be used for simple editing purposes.
simple editing purposes.
XRC was written by Vaclav Slavik. XRC was written by Vaclav Slavik.
@@ -49,107 +49,114 @@
<hr> <hr>
@section overview_xrc_concepts XRC concepts @section overview_xrc_concepts XRC Concepts
These are the typical steps for using XRC files in your application. 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 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 @li If you are going to use XRS files (see
wxFileSystem archive handler first with @c wxFileSystem::AddHandler(new wxArchiveFSHandler); @ref overview_xrc_binaryresourcefiles), install wxFileSystem archive
@li call @c wxXmlResource::Get()->InitAllHandlers() from your wxApp::OnInit function, handler first with wxFileSystem::AddHandler(new wxArchiveFSHandler);
and then call @c wxXmlResource::Get()->Load("myfile.xrc") to load the resource file; @li Call wxXmlResource::Get()->InitAllHandlers() from your wxApp::OnInit
@li to create a dialog from a resource, create it using the default constructor, and then function, and then call wxXmlResource::Get()->Load("myfile.xrc") to load
load it using for example @c wxXmlResource::Get()->LoadDialog(dlg, this, "dlg1"); the resource file.
@li set up event tables as usual but use the @c XRCID(str) macro to translate from XRC string names @li To create a dialog from a resource, create it using the default
to a suitable integer identifier, for example <tt>EVT_MENU(XRCID("quit"), MyFrame::OnQuit)</tt>. 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. To create an XRC file, you can use one of the following methods.
@li Create the file by hand; @li Create the file by hand.
@li use wxDesigner (http://www.roebling.de), a commercial dialog designer/RAD tool; @li Use wxDesigner <http://www.roebling.de/>, a commercial dialog designer/RAD
@li use DialogBlocks (http://www.anthemion.co.uk/dialogblocks), a commercial dialog editor; tool.
@li use XRCed (http://xrced.sf.net), a wxPython-based dialog editor that you can find in the @li Use DialogBlocks <http://www.anthemion.co.uk/dialogblocks/>, a commercial
@c wxPython/tools subdirectory of the wxWidgets SVN archive; dialog editor.
@li use wxGlade (http://wxglade.sf.net), a GUI designer written in wxPython. @li Use XRCed <http://xrced.sf.net/>, a wxPython-based dialog editor that you
At the moment it can generate Python, C++ and XRC; 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 A complete list of third-party tools that write to XRC can be found at
http://www.wxwidgets.org/wiki/index.php/Tools. <http://www.wxwidgets.org/wiki/index.php/Tools>.
It is highly recommended that you use a resource editing tool, since it's fiddly It is highly recommended that you use a resource editing tool, since it's
writing XRC files by hand. fiddly writing XRC files by hand.
You can use wxXmlResource::Load in a number of ways. You can use wxXmlResource::Load in a number of ways. You can pass an XRC file
You can pass an XRC file (XML-based text resource file) or a zip-compressed file (XML-based text resource file) or a zip-compressed file (see
(see @ref overview_xrc_binaryresourcefiles), with extension ZIP or XRS, containing @ref overview_xrc_binaryresourcefiles), with extension ZIP or XRS, containing
other XRC. other XRC.
You can also use embedded C++ resources (see @ref overview_xrc_embeddedresource). You can also use embedded C++ resources (see
@ref overview_xrc_embeddedresource).
@section overview_xrc_binaryresourcefiles Using binary resource files @section overview_xrc_binaryresourcefiles Using Binary Resource Files
To compile binary resource files, use the command-line @c wxrc utility. To compile binary resource files, use the command-line @c wxrc utility. It
It takes one or more file parameters (the input XRC files) and the following takes one or more file parameters (the input XRC files) and the following
switches and options: switches and options:
@li -h (--help): show a help message @li -h (--help): Show a help message.
@li -v (--verbose): show verbose logging information @li -v (--verbose): Show verbose logging information.
@li -c (--cpp-code): write C++ source rather than a XRS file @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 @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 containing class definitions for the windows defined by the XRC file (see
(see special subsection) special subsection).
@li -u (--uncompressed): do not compress XML files (C++ only) @li -u (--uncompressed): Do not compress XML files (C++ only).
@li -g (--gettext): output underscore-wrapped strings that poEdit or gettext can scan. @li -g (--gettext): Output underscore-wrapped strings that poEdit or gettext
Outputs to stdout, or a file if -o is used can scan. Outputs to stdout, or a file if -o is used.
@li -n (--function) name: specify C++ function name (use with -c) @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 -o (--output) @<filename@>: Specify the output file, such as resource.xrs
@li -l (--list-of-handlers) filename: output a list of necessary handlers to this file or resource.cpp.
@li -l (--list-of-handlers) @<filename@>: Output a list of necessary handlers
to this file.
For example: For example:
@code @code
% wxrc resource.xrc $ wxrc resource.xrc
% wxrc resource.xrc -o resource.xrs $ wxrc resource.xrc -o resource.xrs
% wxrc resource.xrc -v -c -o resource.cpp $ wxrc resource.xrc -v -c -o resource.cpp
@endcode @endcode
@note @note XRS file is essentially a renamed ZIP archive which means that you can
XRS file is essentially a renamed ZIP archive which means that you can manipulate manipulate it with standard ZIP tools. Note that if you are using XRS files,
it with standard ZIP tools. Note that if you are using XRS files, you have you have to initialize the wxFileSystem archive handler first! It is a simple
to initialize the #wxFileSystem archive handler first! It is a simple
thing to do: thing to do:
@code @code
#include wx/filesys.h #include <wx/filesys.h>
#include wx/fs_arc.h #include <wx/fs_arc.h>
... ...
wxFileSystem::AddHandler(new wxArchiveFSHandler); wxFileSystem::AddHandler(new wxArchiveFSHandler);
@endcode @endcode
@section overview_xrc_embeddedresource Using embedded resources @section overview_xrc_embeddedresource Using Embedded Resources
It is sometimes useful to embed resources in the executable itself instead It is sometimes useful to embed resources in the executable itself instead of
of loading an external file (e.g. when your app is small and consists only of one 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 exe file). XRC provides means to convert resources into regular C++ file that
can be compiled and included in the executable. can be compiled and included in the executable.
Use the @c -c switch to Use the @c -c switch to @c wxrc utility to produce C++ file with embedded
@c wxrc utility to produce C++ file with embedded resources. This file will resources. This file will contain a function called @c InitXmlResource (unless
contain a function called @e InitXmlResource (unless you override this with you override this with a command line switch). Use it to load the resource:
a command line switch). Use it to load the resource:
@code @code
extern void InitXmlResource(); // defined in generated file extern void InitXmlResource(); // defined in generated file
... ...
wxXmlResource::Get()-InitAllHandlers(); wxXmlResource::Get()->InitAllHandlers();
InitXmlResource(); InitXmlResource();
... ...
@endcode @endcode
@section overview_xrc_cppsample XRC C++ sample @section overview_xrc_cppsample XRC C++ Sample
This is the C++ source file (xrcdemo.cpp) for the XRC sample. This is the C++ source file (xrcdemo.cpp) for the XRC sample.
@@ -174,9 +181,9 @@
// override base class virtuals // override base class virtuals
// ---------------------------- // ----------------------------
// this one is called on application startup and is a good place for the app // this one is called on application startup and is a good place for the
// initialization (doing it here and not in the ctor allows to have an error // app initialization (doing it here and not in the ctor allows to have an
// return: if OnInit() returns @false, the application terminates) // error return: if OnInit() returns false, the application terminates)
virtual bool OnInit(); virtual bool OnInit();
}; };
@@ -255,7 +262,8 @@
msg.Printf( _T("This is the about dialog of XML resources demo.\n") msg.Printf( _T("This is the about dialog of XML resources demo.\n")
_T("Welcome to %s"), wxVERSION_STRING); _T("Welcome to %s"), wxVERSION_STRING);
wxMessageBox(msg, "About XML resources demo", wxOK | wxICON_INFORMATION, this); wxMessageBox(msg, "About XML resources demo",
wxOK | wxICON_INFORMATION, this);
} }
void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event)) void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event))
@@ -274,7 +282,7 @@
@endcode @endcode
@section overview_xrc_sample XRC resource file sample @section overview_xrc_sample XRC Resource File Sample
This is the XML file (resource.xrc) for the XRC sample. This is the XML file (resource.xrc) for the XRC sample.
@@ -357,7 +365,7 @@
</object> </object>
<object class="sizeritem"> <object class="sizeritem">
<object class="wxHtmlWindow"> <object class="wxHtmlWindow">
<htmlcode>&lt;h1&gt;Hi,&lt;/h1&gt;man</htmlcode> <htmlcode><h1>Hi,</h1>man</htmlcode>
<size>100,45d</size> <size>100,45d</size>
</object> </object>
</object> </object>
@@ -368,7 +376,7 @@
<object class="wxBoxSizer"> <object class="wxBoxSizer">
<object class="sizeritem"> <object class="sizeritem">
<object class="wxHtmlWindow"> <object class="wxHtmlWindow">
<htmlcode>Hello, we are inside a &lt;u&gt;NOTEBOOK&lt;/u&gt;...</htmlcode> <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
<size>50,50d</size> <size>50,50d</size>
</object> </object>
<option>1</option> <option>1</option>
@@ -382,7 +390,7 @@
<object class="wxBoxSizer"> <object class="wxBoxSizer">
<object class="sizeritem"> <object class="sizeritem">
<object class="wxHtmlWindow"> <object class="wxHtmlWindow">
<htmlcode>Hello, we are inside a &lt;u&gt;NOTEBOOK&lt;/u&gt;...</htmlcode> <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
<size>50,50d</size> <size>50,50d</size>
</object> </object>
</object> </object>
@@ -436,7 +444,7 @@
@endcode @endcode
@section overview_xrc_fileformat XRC file format @section overview_xrc_fileformat XRC File Format
Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWidgets Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWidgets
distribution. distribution.
@@ -445,24 +453,24 @@
@section overview_xrc_cppheader C++ header file generation @section overview_xrc_cppheader C++ header file generation
Using the @c -e switch together with @c -c, a C++ header file is written 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. containing class definitions for the GUI windows defined in the XRC file. This
This code generation can make it easier to use XRC and automate program code generation can make it easier to use XRC and automate program development.
development. The classes can be used as basis for development, freeing the programmer from
The classes can be used as basis for development, freeing the dealing with most of the XRC specifics (e.g. @c XRCCTRL).
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 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. generated, containing as class members the named widgets of the window. A
A default constructor for each class is also generated. Inside the constructor default constructor for each class is also generated. Inside the constructor
all XRC loading is done and all class members representing widgets are initialized. 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 simple example will help understand how the scheme works. Suppose you have a
a XRC file defining a top level window @c TestWnd_Base, which subclasses @c wxFrame 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 @c wxTextCtrl A (any other class like @c wxDialog will do also), and has subwidgets wxTextCtrl A
and @c wxButton B. and wxButton B.
The XRC file and corresponding class definition in the header file will The XRC file and corresponding class definition in the header file will be
be something like: something like:
@code @code
<?xml version="1.0"?> <?xml version="1.0"?>
@@ -487,19 +495,22 @@
</resource> </resource>
class TestWnd_Base : public wxFrame { class TestWnd_Base : public wxFrame
{
protected: protected:
wxTextCtrl* A; wxTextCtrl* A;
wxButton* B; wxButton* B;
private: private:
void InitWidgetsFromXRC(){ void InitWidgetsFromXRC()
{
wxXmlResource::Get()->LoadObject(this, NULL, "TestWnd", "wxFrame"); wxXmlResource::Get()->LoadObject(this, NULL, "TestWnd", "wxFrame");
A = XRCCTRL(*this, "A", wxTextCtrl); A = XRCCTRL(*this, "A", wxTextCtrl);
B = XRCCTRL(*this, "B", wxButton); B = XRCCTRL(*this, "B", wxButton);
} }
public: public:
TestWnd::TestWnd(){ TestWnd::TestWnd()
{
InitWidgetsFromXRC(); InitWidgetsFromXRC();
} }
}; };
@@ -507,23 +518,26 @@
The generated window class can be used as basis for the full window class. The 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 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 @c XRCCTRL every time you wish to reference them (note that they are
class members), though you must still use @c XRCID to refer to widget IDs in the @c protected class members), though you must still use @c XRCID to refer to
event table. widget IDs in the event table.
Example: Example:
@code @code
#include "resource.h" #include "resource.h"
class TestWnd : public TestWnd_Base { class TestWnd : public TestWnd_Base
{
public: public:
TestWnd(){ TestWnd()
{
// A, B already initialised at this point // A, B already initialised at this point
A->SetValue("Updated in TestWnd::TestWnd"); A->SetValue("Updated in TestWnd::TestWnd");
B->SetValue("Nice :)"); B->SetValue("Nice :)");
} }
void OnBPressed(wxEvent& event){ void OnBPressed(wxEvent& event)
{
Close(); Close();
} }
DECLARE_EVENT_TABLE(); DECLARE_EVENT_TABLE();
@@ -534,8 +548,8 @@
END_EVENT_TABLE() END_EVENT_TABLE()
@endcode @endcode
It is also possible to access the wxSizerItem of a sizer that is part of It is also possible to access the wxSizerItem of a sizer that is part of a
a resource. This can be done using @c XRCSIZERITEM as shown. resource. This can be done using @c XRCSIZERITEM as shown.
The resource file can have something like this for a sizer item. The resource file can have something like this for a sizer item.
@@ -545,15 +559,15 @@
</object> </object>
@endcode @endcode
The code can then access the sizer item by using @c XRCSIZERITEM and The code can then access the sizer item by using @c XRCSIZERITEM and @c XRCID
@c XRCID together. together.
@code @code
wxSizerItem* item = XRCSIZERITEM(*this, "area"); wxSizerItem* item = XRCSIZERITEM(*this, "area");
@endcode @endcode
@section overview_xrc_newresourcehandlers Adding new resource handlers @section overview_xrc_newresourcehandlers Adding New Resource Handlers
Adding a new resource handler is pretty easy. Adding a new resource handler is pretty easy.
@@ -566,14 +580,13 @@
class MyControlXmlHandler : public wxXmlResourceHandler class MyControlXmlHandler : public wxXmlResourceHandler
{ {
public: public:
// Constructor. // Constructor.
MyControlXmlHandler(); MyControlXmlHandler();
// Creates the control and returns a pointer to it. // Creates the control and returns a pointer to it.
virtual wxObject *DoCreateResource(); virtual wxObject *DoCreateResource();
// Returns @true if we know how to create a control for the given node. // Returns true if we know how to create a control for the given node.
virtual bool CanHandle(wxXmlNode *node); virtual bool CanHandle(wxXmlNode *node);
// Register with wxWidgets' dynamic class subsystem. // Register with wxWidgets' dynamic class subsystem.
@@ -612,14 +625,14 @@
// If e.g. the MyControl::Create function looks like: // If e.g. the MyControl::Create function looks like:
// //
// bool MyControl::Create(wxWindow *parent, int id, // bool MyControl::Create(wxWindow *parent, int id,
// const wxBitmap , const wxPoint , // const wxBitmap &first, const wxPoint &posFirst,
// const wxBitmap , const wxPoint , // const wxBitmap &second, const wxPoint &posSecond,
// const wxString , const wxFont , // const wxString &theTitle, const wxFont &titleFont,
// const wxPoint , const wxSize , // const wxPoint &pos, const wxSize &size,
// long style = MYCONTROL_DEFAULT_STYLE, // long style = MYCONTROL_DEFAULT_STYLE,
// const wxString = wxT("MyControl")); // const wxString &name = wxT("MyControl"));
// //
// then the XRC for your component should look like: // Then the XRC for your component should look like:
// //
// <object class="MyControl" name="some_name"> // <object class="MyControl" name="some_name">
// <first-bitmap>first.xpm</first-bitmap> // <first-bitmap>first.xpm</first-bitmap>
@@ -628,13 +641,13 @@
// <second-pos>4,4</second-pos> // <second-pos>4,4</second-pos>
// <the-title>a title</the-title> // <the-title>a title</the-title>
// <title-font> // <title-font>
// <!-- the standard XRC tags for describing a font: <size>, <style>, <weight>, etc --> // <!-- Standard XRC tags for a font: <size>, <style>, <weight>, etc -->
// </title-font> // </title-font>
// <!-- XRC also accepts other usual tags for wxWindow-derived classes: // <!-- XRC also accepts other usual tags for wxWindow-derived classes:
// like e.g. <name>, <style>, <size>, <position>, etc --> // like e.g. <name>, <style>, <size>, <position>, etc -->
// </object> // </object>
// //
// and the code to read your custom tags from the XRC file is just: // And the code to read your custom tags from the XRC file is just:
control->Create(m_parentAsWindow, GetID(), control->Create(m_parentAsWindow, GetID(),
GetBitmap(wxT("first-bitmap")), GetBitmap(wxT("first-bitmap")),
GetPosition(wxT("first-pos")), GetPosition(wxT("first-pos")),
@@ -652,14 +665,14 @@
bool MyControlXmlHandler::CanHandle(wxXmlNode *node) bool MyControlXmlHandler::CanHandle(wxXmlNode *node)
{ {
// this function tells XRC system that this handler can parse // this function tells XRC system that this handler can parse
// the object class="MyControl" tags // the <object class="MyControl"> tags
return IsOfClass(node, wxT("MyControl")); return IsOfClass(node, wxT("MyControl"));
} }
@endcode @endcode
You may want to check the #wxXmlResourceHandler documentation You may want to check the wxXmlResourceHandler documentation to see how many
to see how many built-in getters it contains. It's very easy to retrieve also built-in getters it contains. It's very easy to retrieve also complex
complex structures out of XRC files using them. structures out of XRC files using them.
*/ */