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
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.

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

@@ -1,5 +1,5 @@
/////////////////////////////////////////////////////////////////////////////
// Name: validator
// Name: validator.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
@@ -8,106 +8,111 @@
/*!
@page overview_validator wxValidator overview
@page overview_validator wxValidator Overview
Classes: #wxValidator, #wxTextValidator,
#wxGenericValidator
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.
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.
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.
@section overview_validator_example Example
@code
wxTextCtrl *txt1 = new wxTextCtrl(this, -1, wxT(""),
wxPoint(10, 10), wxSize(100, 80), 0,
wxTextValidator(wxFILTER_ALPHA, _data.m_string));
@endcode
Here is an example of wxTextValidator usage.
In this example, the text validator object provides the following functionality:
@code
wxTextCtrl *txt1 = new wxTextCtrl(
this, -1, wxT(""), wxPoint(10, 10), wxSize(100, 80), 0,
wxTextValidator(wxFILTER_ALPHA, &g_data.m_string));
@endcode
@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.
In this example, the text validator object provides the following
functionality:
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.
@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.
@section anatomy Anatomy of a validator
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.
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.
@section overview_validator_anatomy Anatomy of a Validator
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.
A programmer creating a new validator class should provide the following
functionality.
The wxValidator::TransferToWindow member function should
transfer the data from the validator or associated C++ variable to the control.
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::TransferFromWindow member function should
transfer the data from the control to the validator or associated C++ variable.
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.
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.
The wxValidator::TransferToWindow member function should transfer the data from
the validator or associated C++ variable to the control.
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.
The wxValidator::TransferFromWindow member function should transfer the data
from the control to the validator or associated C++ variable.
@section dialogs How validators interact with dialogs
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.
For validators to work correctly, validator functions must be called at the right times during
dialog initialisation and dismissal.
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.
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.
@section overview_validator_dialogs How Validators Interact with Dialogs
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).
For validators to work correctly, validator functions must be called at the
right times during dialog initialisation and dismissal.
In fact, wxDialog contains a default command event handler for the wxID_OK button. It goes like
this:
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.
@code
void wxDialog::OnOK(wxCommandEvent& event)
{
@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() )
@@ -115,18 +120,18 @@
else
{
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
code for handling dialog dismissal.
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.
*/
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.
*/

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

@@ -1,5 +1,5 @@
/////////////////////////////////////////////////////////////////////////////
// Name: windowdeletion
// Name: windowdeletion.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
@@ -8,135 +8,103 @@
/*!
@page overview_windowdeletion Window deletion overview
@page overview_windowdeletion Window Deletion Overview
Classes: #wxCloseEvent, #wxWindow
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.
*/
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.
*/

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

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

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

@@ -1,5 +1,5 @@
/////////////////////////////////////////////////////////////////////////////
// Name: windowsizing
// Name: windowsizing.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
@@ -8,102 +8,93 @@
/*!
@page overview_windowsizing Window Sizing Overview
@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.
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:
@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.
-# 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 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 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 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 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 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 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 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 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 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 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 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 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 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.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 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.
*/
@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.
*/

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

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

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

@@ -8,182 +8,189 @@
/*!
@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
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).
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.
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
@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.
@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.
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
@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>
<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 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>.
@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.
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;
@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.
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.
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 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).
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.
It takes one or more file parameters (the input XRC files) and the following
switches and options:
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
@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:
For example:
@code
% wxrc resource.xrc
% wxrc resource.xrc -o resource.xrs
% wxrc resource.xrc -v -c -o resource.cpp
@endcode
@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:
@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
@code
#include <wx/filesys.h>
#include <wx/fs_arc.h>
...
wxFileSystem::AddHandler(new wxArchiveFSHandler);
@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
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.
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:
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
@code
extern void InitXmlResource(); // defined in generated file
...
wxXmlResource::Get()->InitAllHandlers();
InitXmlResource();
...
@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.
@code
#include "wx/wx.h"
#include "wx/image.h"
#include "wx/xrc/xmlres.h"
@code
#include "wx/wx.h"
#include "wx/image.h"
#include "wx/xrc/xmlres.h"
// the application icon
#if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__)
// the application icon
#if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__)
#include "rc/appicon.xpm"
#endif
#endif
// ----------------------------------------------------------------------------
// private classes
// ----------------------------------------------------------------------------
// ----------------------------------------------------------------------------
// private classes
// ----------------------------------------------------------------------------
// Define a new application type, each program should derive a class from wxApp
class MyApp : public wxApp
{
public:
// 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)
// 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:
// 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);
@@ -193,31 +200,31 @@
void OnDlg1(wxCommandEvent& event);
void OnDlg2(wxCommandEvent& event);
private:
private:
// any class wishing to process wxWidgets events must use this macro
DECLARE_EVENT_TABLE()
};
};
// ----------------------------------------------------------------------------
// event tables and other macros for wxWidgets
// ----------------------------------------------------------------------------
// ----------------------------------------------------------------------------
// event tables and other macros for wxWidgets
// ----------------------------------------------------------------------------
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
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()
END_EVENT_TABLE()
IMPLEMENT_APP(MyApp)
IMPLEMENT_APP(MyApp)
// ----------------------------------------------------------------------------
// the application class
// ----------------------------------------------------------------------------
// ----------------------------------------------------------------------------
// the application class
// ----------------------------------------------------------------------------
// 'Main program' equivalent: the program execution "starts" here
bool MyApp::OnInit()
{
// 'Main program' equivalent: the program execution "starts" here
bool MyApp::OnInit()
{
wxImage::AddHandler(new wxGIFHandler);
wxXmlResource::Get()->InitAllHandlers();
wxXmlResource::Get()->Load("rc/resource.xrc");
@@ -226,61 +233,62 @@
wxPoint(50, 50), wxSize(450, 340));
frame->Show(true);
return true;
}
}
// ----------------------------------------------------------------------------
// main frame
// ----------------------------------------------------------------------------
// ----------------------------------------------------------------------------
// main frame
// ----------------------------------------------------------------------------
// frame constructor
MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
: wxFrame((wxFrame *)NULL, -1, title, pos, size)
{
// 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))
{
// event handlers
void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
{
// true is to force the frame to close
Close(true);
}
}
void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
{
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);
}
wxMessageBox(msg, "About XML resources demo",
wxOK | wxICON_INFORMATION, this);
}
void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event))
{
void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event))
{
wxDialog dlg;
wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1");
dlg.ShowModal();
}
}
void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event))
{
void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event))
{
wxDialog dlg;
wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg2");
dlg.ShowModal();
}
@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.
@code
<?xml version="1.0"?>
<resource version="2.3.0.1">
@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">
@@ -357,7 +365,7 @@
</object>
<object class="sizeritem">
<object class="wxHtmlWindow">
<htmlcode>&lt;h1&gt;Hi,&lt;/h1&gt;man</htmlcode>
<htmlcode><h1>Hi,</h1>man</htmlcode>
<size>100,45d</size>
</object>
</object>
@@ -368,7 +376,7 @@
<object class="wxBoxSizer">
<object class="sizeritem">
<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>
</object>
<option>1</option>
@@ -382,7 +390,7 @@
<object class="wxBoxSizer">
<object class="sizeritem">
<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>
</object>
</object>
@@ -432,41 +440,41 @@
</object>
<title>Second testing dialog</title>
</object>
</resource>
@endcode
</resource>
@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
distribution.
Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWidgets
distribution.
@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
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).
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.
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.
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:
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">
@code
<?xml version="1.0"?>
<resource version="2.3.0.1">
<object class="wxFrame" name="TestWnd_Base">
<size>-1,-1</size>
<title>Test</title>
@@ -484,111 +492,116 @@
</object>
</object>
</object>
</resource>
</resource>
class TestWnd_Base : public wxFrame {
protected:
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);
private:
void InitWidgetsFromXRC()
{
wxXmlResource::Get()->LoadObject(this, NULL, "TestWnd", "wxFrame");
A = XRCCTRL(*this, "A", wxTextCtrl);
B = XRCCTRL(*this, "B", wxButton);
}
public:
TestWnd::TestWnd(){
public:
TestWnd::TestWnd()
{
InitWidgetsFromXRC();
}
};
@endcode
};
@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.
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:
Example:
@code
#include "resource.h"
@code
#include "resource.h"
class TestWnd : public TestWnd_Base {
public:
TestWnd(){
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){
void OnBPressed(wxEvent& event)
{
Close();
}
DECLARE_EVENT_TABLE();
};
};
BEGIN_EVENT_TABLE(TestWnd,TestWnd_Base)
EVT_BUTTON(XRCID("B"),TestWnd::OnBPressed)
END_EVENT_TABLE()
@endcode
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.
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.
The resource file can have something like this for a sizer item.
@code
<object class="spacer" name="area">
@code
<object class="spacer" name="area">
<size>400, 300</size>
</object>
@endcode
</object>
@endcode
The code can then access the sizer item by using @c XRCSIZERITEM and
@c XRCID together.
The code can then access the sizer item by using @c XRCSIZERITEM and @c XRCID
together.
@code
wxSizerItem* item = XRCSIZERITEM(*this, "area");
@endcode
@code
wxSizerItem* item = XRCSIZERITEM(*this, "area");
@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.
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.
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:
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.
// 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
};
@endcode
The implementation of your custom XML handler will typically look as:
The implementation of your custom XML handler will typically look as:
@code
// Register with wxWidgets' dynamic class subsystem.
IMPLEMENT_DYNAMIC_CLASS(MyControlXmlHandler, wxXmlResourceHandler)
@code
// Register with wxWidgets' dynamic class subsystem.
IMPLEMENT_DYNAMIC_CLASS(MyControlXmlHandler, wxXmlResourceHandler)
MyControlXmlHandler::MyControlXmlHandler()
{
MyControlXmlHandler::MyControlXmlHandler()
{
// this call adds support for all wxWindows class styles
// (e.g. wxBORDER_SIMPLE, wxBORDER_SUNKEN, wxWS_EX_* etc etc)
AddWindowStyles();
@@ -596,10 +609,10 @@
// if MyControl class supports e.g. MYCONTROL_DEFAULT_STYLE
// you should use:
// XRC_ADD_STYLE(MYCONTROL_DEFAULT_STYLE);
}
}
wxObject *MyControlXmlHandler::DoCreateResource()
{
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!
@@ -612,14 +625,14 @@
// 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 ,
// 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 = 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">
// <first-bitmap>first.xpm</first-bitmap>
@@ -628,13 +641,13 @@
// <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 -->
// <!-- 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:
// 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")),
@@ -647,19 +660,19 @@
SetupWindow(control);
return control;
}
}
bool MyControlXmlHandler::CanHandle(wxXmlNode *node)
{
bool MyControlXmlHandler::CanHandle(wxXmlNode *node)
{
// 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"));
}
@endcode
}
@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.
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.
*/