More doxygen topic overview cleanup.
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52244 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
@@ -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.
|
||||
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: validator
|
||||
// Name: validator.h
|
||||
// Purpose: topic overview
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
@@ -8,125 +8,130 @@
|
||||
|
||||
/*!
|
||||
|
||||
@page overview_validator wxValidator overview
|
||||
@page overview_validator wxValidator Overview
|
||||
|
||||
Classes: #wxValidator, #wxTextValidator,
|
||||
#wxGenericValidator
|
||||
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.
|
||||
|
||||
@section example Example
|
||||
|
||||
Here is an example of wxTextValidator usage.
|
||||
|
||||
@code
|
||||
wxTextCtrl *txt1 = new wxTextCtrl(this, -1, wxT(""),
|
||||
wxPoint(10, 10), wxSize(100, 80), 0,
|
||||
wxTextValidator(wxFILTER_ALPHA, _data.m_string));
|
||||
@endcode
|
||||
|
||||
In this example, the text validator object provides the following functionality:
|
||||
|
||||
@li It transfers the value of g_data.m_string (a wxString variable) to the wxTextCtrl when
|
||||
the dialog is initialised.
|
||||
@li It transfers the wxTextCtrl data back to this variable when the dialog is dismissed.
|
||||
@li It filters input characters so that only alphabetic characters are allowed.
|
||||
|
||||
The validation and filtering of input is accomplished in two ways. When a character is input,
|
||||
wxTextValidator checks the character against the allowed filter flag (wxFILTER_ALPHA in this case). If
|
||||
the character is inappropriate, it is vetoed (does not appear) and a warning beep sounds.
|
||||
The second type of validation is performed when the dialog is about to be dismissed, so if
|
||||
the default string contained invalid characters already, a dialog box is shown giving the
|
||||
error, and the dialog is not dismissed.
|
||||
|
||||
@section anatomy Anatomy of a validator
|
||||
|
||||
A programmer creating a new validator class should provide the following functionality.
|
||||
|
||||
A validator constructor is responsible for allowing the programmer to specify the kind
|
||||
of validation required, and perhaps a pointer to a C++ variable that is used for storing the
|
||||
data for the control. If such a variable address is not supplied by the user, then
|
||||
the validator should store the data internally.
|
||||
|
||||
The wxValidator::Validate member function should return
|
||||
@true if the data in the control (not the C++ variable) is valid. It should also show
|
||||
an appropriate message if data was not valid.
|
||||
|
||||
The wxValidator::TransferToWindow member function should
|
||||
transfer the data from the validator or associated C++ variable to the control.
|
||||
|
||||
The wxValidator::TransferFromWindow member function should
|
||||
transfer the data from the control to the validator or associated C++ variable.
|
||||
|
||||
There should be a copy constructor, and a wxValidator::Clone function
|
||||
which returns a copy of the validator object. This is important because validators
|
||||
are passed by reference to window constructors, and must therefore be cloned internally.
|
||||
|
||||
You can optionally define event handlers for the validator, to implement filtering. These handlers
|
||||
will capture events before the control itself does.
|
||||
For an example implementation, see the valtext.h and valtext.cpp files in the wxWidgets library.
|
||||
|
||||
@section dialogs How validators interact with dialogs
|
||||
|
||||
For validators to work correctly, validator functions must be called at the right times during
|
||||
dialog initialisation and dismissal.
|
||||
|
||||
When a wxDialog::Show is called (for a modeless dialog)
|
||||
or wxDialog::ShowModal is called (for a modal dialog),
|
||||
the function wxWindow::InitDialog is automatically called.
|
||||
This in turn sends an initialisation event to the dialog. The default handler for
|
||||
the wxEVT_INIT_DIALOG event is defined in the wxWindow class to simply call
|
||||
the function wxWindow::TransferDataToWindow. This
|
||||
function finds all the validators in the window's children and calls the TransferToWindow
|
||||
function for each. Thus, data is transferred from C++ variables to the dialog
|
||||
just as the dialog is being shown.
|
||||
|
||||
@note If you are using a window or panel instead of a dialog, you will need to
|
||||
call wxWindow::InitDialog explicitly before showing the
|
||||
window.
|
||||
|
||||
When the user clicks on a button, for example the OK button, the application should
|
||||
first call wxWindow::Validate, which returns @false if
|
||||
any of the child window validators failed to validate the window data. The button handler
|
||||
should return immediately if validation failed. Secondly, the application should
|
||||
call wxWindow::TransferDataFromWindow and
|
||||
return if this failed. It is then safe to end the dialog by calling EndModal (if modal)
|
||||
or Show (if modeless).
|
||||
|
||||
In fact, wxDialog contains a default command event handler for the wxID_OK button. It goes like
|
||||
this:
|
||||
|
||||
@code
|
||||
void wxDialog::OnOK(wxCommandEvent& event)
|
||||
{
|
||||
if ( Validate() && TransferDataFromWindow() )
|
||||
{
|
||||
if ( IsModal() )
|
||||
EndModal(wxID_OK);
|
||||
else
|
||||
{
|
||||
SetReturnCode(wxID_OK);
|
||||
this-Show(@false);
|
||||
}
|
||||
}
|
||||
}
|
||||
@endcode
|
||||
|
||||
So if using validators and a normal OK button, you may not even need to write any
|
||||
code for handling dialog dismissal.
|
||||
|
||||
If you load your dialog from a resource file, you will need to iterate through the controls
|
||||
setting validators, since validators can't be specified in a dialog resource.
|
||||
|
||||
*/
|
||||
You can use a stock validator, such as wxTextValidator (which does text control
|
||||
data transfer, validation and filtering) and wxGenericValidator (which does
|
||||
data transfer for a range of controls); or you can write your own.
|
||||
|
||||
|
||||
@section overview_validator_example Example
|
||||
|
||||
Here is an example of wxTextValidator usage.
|
||||
|
||||
@code
|
||||
wxTextCtrl *txt1 = new wxTextCtrl(
|
||||
this, -1, wxT(""), wxPoint(10, 10), wxSize(100, 80), 0,
|
||||
wxTextValidator(wxFILTER_ALPHA, &g_data.m_string));
|
||||
@endcode
|
||||
|
||||
In this example, the text validator object provides the following
|
||||
functionality:
|
||||
|
||||
@li It transfers the value of g_data.m_string (a wxString variable) to the
|
||||
wxTextCtrl when the dialog is initialised.
|
||||
@li It transfers the wxTextCtrl data back to this variable when the dialog is
|
||||
dismissed.
|
||||
@li It filters input characters so that only alphabetic characters are allowed.
|
||||
|
||||
The validation and filtering of input is accomplished in two ways. When a
|
||||
character is input, wxTextValidator checks the character against the allowed
|
||||
filter flag (wxFILTER_ALPHA in this case). If the character is inappropriate,
|
||||
it is vetoed (does not appear) and a warning beep sounds. The second type of
|
||||
validation is performed when the dialog is about to be dismissed, so if the
|
||||
default string contained invalid characters already, a dialog box is shown
|
||||
giving the error, and the dialog is not dismissed.
|
||||
|
||||
|
||||
@section overview_validator_anatomy Anatomy of a Validator
|
||||
|
||||
A programmer creating a new validator class should provide the following
|
||||
functionality.
|
||||
|
||||
A validator constructor is responsible for allowing the programmer to specify
|
||||
the kind of validation required, and perhaps a pointer to a C++ variable that
|
||||
is used for storing the data for the control. If such a variable address is not
|
||||
supplied by the user, then the validator should store the data internally.
|
||||
|
||||
The wxValidator::Validate member function should return @true if the data in
|
||||
the control (not the C++ variable) is valid. It should also show an appropriate
|
||||
message if data was not valid.
|
||||
|
||||
The wxValidator::TransferToWindow member function should transfer the data from
|
||||
the validator or associated C++ variable to the control.
|
||||
|
||||
The wxValidator::TransferFromWindow member function should transfer the data
|
||||
from the control to the validator or associated C++ variable.
|
||||
|
||||
There should be a copy constructor, and a wxValidator::Clone function which
|
||||
returns a copy of the validator object. This is important because validators
|
||||
are passed by reference to window constructors, and must therefore be cloned
|
||||
internally.
|
||||
|
||||
You can optionally define event handlers for the validator, to implement
|
||||
filtering. These handlers will capture events before the control itself does.
|
||||
For an example implementation, see the valtext.h and valtext.cpp files in the
|
||||
wxWidgets library.
|
||||
|
||||
|
||||
@section overview_validator_dialogs How Validators Interact with Dialogs
|
||||
|
||||
For validators to work correctly, validator functions must be called at the
|
||||
right times during dialog initialisation and dismissal.
|
||||
|
||||
When a wxDialog::Show is called (for a modeless dialog) or wxDialog::ShowModal
|
||||
is called (for a modal dialog), the function wxWindow::InitDialog is
|
||||
automatically called. This in turn sends an initialisation event to the dialog.
|
||||
The default handler for the wxEVT_INIT_DIALOG event is defined in the wxWindow
|
||||
class to simply call the function wxWindow::TransferDataToWindow. This function
|
||||
finds all the validators in the window's children and calls the
|
||||
TransferToWindow function for each. Thus, data is transferred from C++
|
||||
variables to the dialog just as the dialog is being shown.
|
||||
|
||||
@note If you are using a window or panel instead of a dialog, you will need to
|
||||
call wxWindow::InitDialog explicitly before showing the window.
|
||||
|
||||
When the user clicks on a button, for example the OK button, the application
|
||||
should first call wxWindow::Validate, which returns @false if any of the child
|
||||
window validators failed to validate the window data. The button handler should
|
||||
return immediately if validation failed. Secondly, the application should call
|
||||
wxWindow::TransferDataFromWindow and return if this failed. It is then safe to
|
||||
end the dialog by calling EndModal (if modal) or Show (if modeless).
|
||||
|
||||
In fact, wxDialog contains a default command event handler for the wxID_OK
|
||||
button. It goes like this:
|
||||
|
||||
@code
|
||||
void wxDialog::OnOK(wxCommandEvent& event)
|
||||
{
|
||||
if ( Validate() && TransferDataFromWindow() )
|
||||
{
|
||||
if ( IsModal() )
|
||||
EndModal(wxID_OK);
|
||||
else
|
||||
{
|
||||
SetReturnCode(wxID_OK);
|
||||
this->Show(false);
|
||||
}
|
||||
}
|
||||
}
|
||||
@endcode
|
||||
|
||||
So if using validators and a normal OK button, you may not even need to write
|
||||
any code for handling dialog dismissal.
|
||||
|
||||
If you load your dialog from a resource file, you will need to iterate through
|
||||
the controls setting validators, since validators can't be specified in a
|
||||
dialog resource.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
@@ -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 Size: The size of a widget can be explicitly set or fetched with
|
||||
the @c SetSize() or @c GetSize() methods. This size value
|
||||
is the size that the widget is currently using on screen and is the
|
||||
way to change the size of something that is not being managed by a
|
||||
sizer.
|
||||
@b ClientSize: The client size represents the widget's area inside of any
|
||||
borders belonging to the widget and is the area that can be drawn upon in a
|
||||
@c EVT_PAINT event. If a widget doesn't have a border then its client size is
|
||||
the same as its size.
|
||||
|
||||
@b ClientSize: The client size represents the widget's area inside
|
||||
of any borders belonging to the widget and is the area that can be
|
||||
drawn upon in a @c EVT_PAINT event. If a widget doesn't have a
|
||||
border then its client size is the same as its size.
|
||||
@b InitialSize: The initial size of a widget is the size given to the
|
||||
constructor of the widget, if any. As mentioned above most controls will also
|
||||
set this size value as the control's min size. If the size passed to the
|
||||
constructor is the default @c wxDefaultSize, or if the size is not fully
|
||||
specified (such as wxSize(150,-1)) then most controls will fill in the missing
|
||||
size components using the best size and will set the initial size of the
|
||||
control to the resulting size.
|
||||
|
||||
@b 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 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 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 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.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 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.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user