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

More doxygen topic overview cleanup.

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

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

@@ -110,7 +110,7 @@ in both ANSI and Unicode modes could look like:
@endcode @endcode
Of course, it would be nearly impossibly to write such programs if it had to Of course, it would be nearly impossibly to write such programs if it had to
be done this way (try to imagine the number of @ifdef UNICODE an average be done this way (try to imagine the number of UNICODE checkes an average
program would have had!). Luckily, there is another way - see the next section. program would have had!). Luckily, there is another way - see the next section.

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

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: validator // Name: validator.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,125 +8,130 @@
/*! /*!
@page overview_validator wxValidator overview @page overview_validator wxValidator Overview
Classes: #wxValidator, #wxTextValidator, Classes: wxValidator, wxTextValidator, wxGenericValidator
#wxGenericValidator
The aim of the validator concept is to make dialogs very much easier to write. The aim of the validator concept is to make dialogs very much easier to write.
A validator is an object that can be plugged into a control (such as a wxTextCtrl), and A validator is an object that can be plugged into a control (such as a
mediates between C++ data and the control, transferring the data in either direction wxTextCtrl), and mediates between C++ data and the control, transferring the
and validating it. It also is able to intercept events generated data in either direction and validating it. It also is able to intercept events
by the control, providing filtering behaviour without the need to derive a new control class. generated by the control, providing filtering behaviour without the need to
derive a new control class.
You can use a stock validator, such as #wxTextValidator (which does text You can use a stock validator, such as wxTextValidator (which does text control
control data transfer, validation and filtering) and data transfer, validation and filtering) and wxGenericValidator (which does
#wxGenericValidator (which does data transfer for a range of controls); data transfer for a range of controls); or you can write your own.
or you can write your own.
@section example Example
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.
*/
@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.
*/

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

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: windowdeletion // Name: windowdeletion.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,135 +8,103 @@
/*! /*!
@page overview_windowdeletion Window deletion overview @page overview_windowdeletion Window Deletion Overview
Classes: #wxCloseEvent, #wxWindow Classes: wxCloseEvent, wxWindow
Window deletion can be a confusing subject, so this overview is provided Window deletion can be a confusing subject, so this overview is provided to
to help make it clear when and how you delete windows, or respond to user requests help make it clear when and how you delete windows, or respond to user requests
to close windows. to close windows.
@section sequence What is the sequence of events in a window deletion?
When the user clicks on the system close button or system close command,
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.
*/
@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 // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,73 +8,81 @@
/*! /*!
@page overview_windowids Window IDs overview @page overview_windowids Window IDs Overview
@seealso @li @ref overview_windowids_intro
#wxIdManager @li @ref overview_windowids_type
wxWindow::NewControlId @li @ref overview_windowids_using
wxWindow::UnreserveControlId
@li @ref introduction @seealso
@li @ref overview_windowidstypes
@li @ref overview_windowidsusing @li wxIdManager
@li wxWindow::NewControlId
@li wxWindow::UnreserveControlId
@section introduction Introduction <hr>
Various contols and other parts of wxWidgets need an ID. Sometimes the
ID may be directly provided by the use or have a predefined value, such as
@c wxID_OPEN. Often, however, the value of the ID is unimportant and is
created automatically by calling wxWindow::NewControlId
or by passing @c wxID_ANY as the ID of an object.
There are two ways to generate an ID. One way, is to start at a negative number,
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.
*/
@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 // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // 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 It can sometimes be confusing to keep track of the various size-related
size-related attributes of a #wxWindow, how they attributes of a wxWindow, how they relate to each other, and how they interact
relate to each other, and how they interact with sizers. This document with sizers. This document will attempt to clear the fog a little, and give
will attempt to clear the fog a little, and give some simple some simple explanations of things.
explanations of things.
@b BestSize: The best size of a widget depends on what kind of widget it @b BestSize: The best size of a widget depends on what kind of widget it is,
is, and usually also on the contents of the widget. For example a and usually also on the contents of the widget. For example a wxListBox's best
#wxListBox's best size will be calculated based on size will be calculated based on how many items it has, up to a certain limit,
how many items it has, up to a certain limit, or a or a wxButton's best size will be calculated based on its label size, but
#wxButton's best size will be calculated based on normally won't be smaller than the platform default button size (unless a style
its label size, but normally won't be smaller than the platform flag overrides that). Get the picture? There is a special virtual method in the
default button size (unless a style flag overrides that). Get the C++ window classes called @c DoGetBestSize() that a class needs to override if
picture? There is a special virtual method in the C++ window classes it wants to calculate its own best size based on its content. The default
called @c DoGetBestSize() that a class needs to override if it @c DoGetBestSize() is designed for use in container windows, such as wxPanel,
wants to calculate its own best size based on its content. The default and works something like this:
@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. @b MinSize: The min size of a widget is a size that is normally explicitly set
-# Otherwise if the window has layout constraints then that is used to calculate the best size. by the programmer either with the @c SetMinSize() method or the
-# Otherwise if the window has children then the best size is set to be large enough to show all the children. @c SetSizeHints() method. Most controls will also set the min size to the size
-# Otherwise if there are no children then the window's min size will be used for the best size. given in the control's constructor if a non-default value is passed. Top-level
-# Otherwise if there is no min size set, then the current size is used for the best size. 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 @b ClientSize: The client size represents the widget's area inside of any
explicitly set by the programmer either with the @c SetMinSize() borders belonging to the widget and is the area that can be drawn upon in a
method or the @c SetSizeHints() method. Most controls will also @c EVT_PAINT event. If a widget doesn't have a border then its client size is
set the min size to the size given in the control's constructor if a the same as its size.
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 @b InitialSize: The initial size of a widget is the size given to the
of any borders belonging to the widget and is the area that can be constructor of the widget, if any. As mentioned above most controls will also
drawn upon in a @c EVT_PAINT event. If a widget doesn't have a set this size value as the control's min size. If the size passed to the
border then its client size is the same as its size. 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 @b GetEffectiveMinSize(): (formerly @c GetBestFittingSize) A blending of the
the constructor of the widget, if any. As mentioned above most widget's min size and best size, giving precedence to the min size. For
controls will also set this size value as the control's min size. If example, if a widget's min size is set to (150, -1) and the best size is
the size passed to the constructor is the default (80, 22) then the best fitting size is (150, 22). If the min size is (50, 20)
@c wxDefaultSize, or if the size is not fully specified (such as then the best fitting size is (50, 20). This method is what is called by the
@c wxSize(150,-1)) then most controls will fill in the missing sizers when determining what the requirements of each item in the sizer is, and
size components using the best size and will set the initial size of is used for calculating the overall minimum needs of the sizer.
the control to the resulting size.
@b GetEffectiveMinSize(): (formerly @c GetBestFittingSize) A @b SetInitialSize(size): (formerly @c SetBestFittingSize) This is a little
blending of the widget's min size and best size, giving precedence to different than the typical size setters. Rather than just setting an
the min size. For example, if a widget's min size is set to (150, -1) "initial size" attribute it actually sets the minsize to the value passed in,
and the best size is (80, 22) then the best fitting size is (150, blends that value with the best size, and then sets the size of the widget to
22). If the min size is (50, 20) then the best fitting size is (50, be the result. So you can consider this method to be a "Smart SetSize". This
20). This method is what is called by the sizers when determining what method is what is called by the constructor of most controls to set the minsize
the requirements of each item in the sizer is, and is used for and initial size of the control.
calculating the overall minimum needs of the sizer.
@b SetInitialSize(size): (formerly @c SetBestFittingSize) @b window.Fit(): The @c Fit() method sets the size of a window to fit around
This is a little different than the typical size setters. Rather than its children. If it has no children then nothing is done, if it does have
just setting an "initial size" attribute it actually sets the minsize children then the size of the window is set to the window's best size.
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 @b sizer.Fit(window): This sets the size of the window to be large enough to
window to fit around its children. If it has no children then nothing accommodate the minimum size needed by the sizer, (along with a few other
is done, if it does have children then the size of the window is set constraints...) If the sizer is the one that is assigned to the window then
to the window's best size. this should be equivalent to @c window.Fit().
@b sizer.Fit(window): This sets the size of the window to be large @b sizer.Layout(): Recalculates the minimum space needed by each item in the
enough to accommodate the minimum size needed by the sizer, (along with sizer, and then lays out the items within the space currently allotted to the
a few other constraints...) If the sizer is the one that is assigned sizer.
to the window then this should be equivalent to @c window.Fit().
@b sizer.Layout(): Recalculates the minimum space needed by each @b window.Layout(): If the window has a sizer then it sets the space given to
item in the sizer, and then lays out the items within the space the sizer to the current size of the window, which results in a call to
currently allotted to the sizer. @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
@b window.Layout(): If the window has a sizer then it sets the the default @c EVT_SIZE handler for container windows.
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 // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,20 +8,20 @@
/*! /*!
@page overview_windowstyles Window styles @page overview_windowstyles Window Styles
Window styles are used to specify alternative behaviour and appearances for windows, when they are Window styles are used to specify alternative behaviour and appearances for
created. The symbols are defined in such a way that they can be combined in a 'bit-list' using the windows, when they are created. The symbols are defined in such a way that they
C++ @e bitwise-or operator. For example: can be combined in a 'bit-list' using the C++ @e bitwise-or operator. For
example:
@code @code
wxCAPTION | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER wxCAPTION | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER
@endcode @endcode
For the window styles specific to each window class, please see the documentation For the window styles specific to each window class, please see the
for the window. Most windows can use the generic styles listed for #wxWindow in documentation for the window. Most windows can use the generic styles listed
addition to their own styles. for wxWindow in addition to their own styles.
*/
*/

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

File diff suppressed because it is too large Load Diff