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

Replaced /*! with /** in remaining Doxygen headers, and removed intentation of overviews [a-c].

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52448 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-03-12 08:50:42 +00:00
parent b890136bc6
commit 880efa2a13
76 changed files with 761 additions and 755 deletions
Download Patch File Download Diff File Expand all files Collapse all files

386
docs/doxygen/overviews/commondialogs.h
View File

@@ -6,252 +6,248 @@
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
/*!
/**
@page overview_cmndlg Common Dialogs
Classes:
@li wxColourDialog
@li wxFontDialog
@li wxPrintDialog
@li wxFileDialog
@li wxDirDialog
@li wxTextEntryDialog
@li wxPasswordEntryDialog
@li wxMessageDialog
@li wxSingleChoiceDialog
@li wxMultiChoiceDialog
Common dialog classes and functions encapsulate commonly-needed dialog box
requirements. They are all 'modal', grabbing the flow of control until the user
dismisses the dialog, to make them easy to use within an application.
Some dialogs have both platform-dependent and platform-independent
implementations, so that if underlying windowing systems do not provide the
required functionality, the generic classes and functions can stand in. For
example, under MS Windows, wxColourDialog uses the standard colour selector.
There is also an equivalent called wxGenericColourDialog for other platforms,
and a macro defines wxColourDialog to be the same as wxGenericColourDialog on
non-MS Windows platforms. However, under MS Windows, the generic dialog can
also be used, for testing or other purposes.
@li @ref overview_cmndlg_colour
@li @ref overview_cmndlg_font
@li @ref overview_cmndlg_print
@li @ref overview_cmndlg_file
@li @ref overview_cmndlg_dir
@li @ref overview_cmndlg_textentry
@li @ref overview_cmndlg_password
@li @ref overview_cmndlg_msg
@li @ref overview_cmndlg_singlechoice
@li @ref overview_cmndlg_multichoice
<hr>
@section overview_cmndlg_colour wxColourDialog Overview
Classes: wxColourDialog, wxColourData
The wxColourDialog presents a colour selector to the user, and returns with
colour information.
@subsection overview_cmndlg_colour_msw The MS Windows Colour Selector
Under Windows, the native colour selector common dialog is used. This presents
a dialog box with three main regions: at the top left, a palette of 48
commonly-used colours is shown. Under this, there is a palette of 16
'custom colours' which can be set by the application if desired. Additionally,
the user may open up the dialog box to show a right-hand panel containing
controls to select a precise colour, and add it to the custom colour palette.
@subsection overview_cmndlg_colour_generic The Generic Colour Selector
@page overview_cmndlg Common dialogs overview
Classes: wxColourDialog, wxFontDialog, wxPrintDialog, wxFileDialog,
wxDirDialog, wxTextEntryDialog, wxPasswordEntryDialog,
wxMessageDialog, wxSingleChoiceDialog, wxMultiChoiceDialog
Under non-MS Windows platforms, the colour selector is a simulation of most of
the features of the MS Windows selector. Two palettes of 48 standard and 16
custom colours are presented, with the right-hand area containing three sliders
for the user to select a colour from red, green and blue components. This
colour may be added to the custom colour palette, and will replace either the
currently selected custom colour, or the first one in the palette if none is
selected. The RGB colour sliders are not optional in the generic colour
selector. The generic colour selector is also available under MS Windows; use
the name wxGenericColourDialog.
@subsection overview_cmndlg_colour_example Example
In the samples/dialogs directory, there is an example of using the
wxColourDialog class. Here is an excerpt, which sets various parameters of a
wxColourData object, including a grey scale for the custom colours. If the user
did not cancel the dialog, the application retrieves the selected colour and
uses it to set the background of a window.
@code
wxColourData data;
data.SetChooseFull(true);
for (int i = 0; i < 16; i++)
{
wxColour colour(i*16, i*16, i*16);
data.SetCustomColour(i, colour);
}
wxColourDialog dialog(this, &data);
if (dialog.ShowModal() == wxID_OK)
{
wxColourData retData = dialog.GetColourData();
wxColour col = retData.GetColour();
wxBrush brush(col, wxSOLID);
myWindow->SetBackground(brush);
myWindow->Clear();
myWindow->Refresh();
}
@endcode
Common dialog classes and functions encapsulate commonly-needed dialog box requirements.
They are all 'modal', grabbing the flow of control until the user dismisses the dialog,
to make them easy to use within an application.
Some dialogs have both platform-dependent and platform-independent implementations,
so that if underlying windowing systems do not provide the required functionality,
the generic classes and functions can stand in. For example, under MS Windows, wxColourDialog
uses the standard colour selector. There is also an equivalent called wxGenericColourDialog
for other platforms, and a macro defines wxColourDialog to be the same as wxGenericColourDialog
on non-MS Windows platforms. However, under MS Windows, the generic dialog can also be
used, for testing or other purposes.
@li @ref overview_cmndlg_colour
@li @ref overview_cmndlg_font
@li @ref overview_cmndlg_print
@li @ref overview_cmndlg_file
@li @ref overview_cmndlg_dir
@li @ref overview_cmndlg_textentry
@li @ref overview_cmndlg_password
@li @ref overview_cmndlg_msg
@li @ref overview_cmndlg_singlechoice
@li @ref overview_cmndlg_multichoice
<hr>
@section overview_cmndlg_font wxFontDialog Overview
@section overview_cmndlg_colour wxColourDialog overview
Classes: wxColourDialog, wxColourData
The wxColourDialog presents a colour selector to the user, and returns
with colour information.
@subsection overview_cmndlg_colour_msw The MS Windows colour selector
Under Windows, the native colour selector common dialog is used. This
presents a dialog box with three main regions: at the top left, a
palette of 48 commonly-used colours is shown. Under this, there is a
palette of 16 'custom colours' which can be set by the application if
desired. Additionally, the user may open up the dialog box to show
a right-hand panel containing controls to select a precise colour, and add
it to the custom colour palette.
@subsection overview_cmndlg_colour_generic The generic colour selector
Classes: wxFontDialog, wxFontData
Under non-MS Windows platforms, the colour selector is a simulation of
most of the features of the MS Windows selector. Two palettes of 48
standard and 16 custom colours are presented, with the right-hand area
containing three sliders for the user to select a colour from red,
green and blue components. This colour may be added to the custom colour
palette, and will replace either the currently selected custom colour,
or the first one in the palette if none is selected. The RGB colour sliders
are not optional in the generic colour selector. The generic colour
selector is also available under MS Windows; use the name
wxGenericColourDialog.
The wxFontDialog presents a font selector to the user, and returns with font
and colour information.
@subsection overview_cmndlg_colour_example Example
@subsection overview_cmndlg_font_msw The MS Windows Font Selector
In the samples/dialogs directory, there is an example of using
the wxColourDialog class. Here is an excerpt, which
sets various parameters of a wxColourData object, including
a grey scale for the custom colours. If the user did not cancel
the dialog, the application retrieves the selected colour and
uses it to set the background of a window.
Under Windows, the native font selector common dialog is used. This presents a
dialog box with controls for font name, point size, style, weight, underlining,
strikeout and text foreground colour. A sample of the font is shown on a white
area of the dialog box. Note that in the translation from full MS Windows fonts
to wxWidgets font conventions, strikeout is ignored and a font family (such as
Swiss or Modern) is deduced from the actual font name (such as Arial or
Courier).
@code
wxColourData data;
data.SetChooseFull(true);
for (int i = 0; i 16; i++)
{
wxColour colour(i*16, i*16, i*16);
data.SetCustomColour(i, colour);
}
@subsection overview_cmndlg_font_generic The Generic Font Selector
wxColourDialog dialog(this, &data);
if (dialog.ShowModal() == wxID_OK)
{
wxColourData retData = dialog.GetColourData();
wxColour col = retData.GetColour();
wxBrush brush(col, wxSOLID);
myWindow->SetBackground(brush);
myWindow->Clear();
myWindow->Refresh();
}
@endcode
Under non-MS Windows platforms, the font selector is simpler. Controls for font
family, point size, style, weight, underlining and text foreground colour are
provided, and a sample is shown upon a white background. The generic font
selector is also available under MS Windows; use the name wxGenericFontDialog.
@subsection overview_cmndlg_font_example Example
In the samples/dialogs directory, there is an example of using the wxFontDialog
class. The application uses the returned font and colour for drawing text on a
canvas. Here is an excerpt:
@section overview_cmndlg_font wxFontDialog overview
@code
wxFontData data;
data.SetInitialFont(canvasFont);
data.SetColour(canvasTextColour);
Classes: wxFontDialog, wxFontData
wxFontDialog dialog(this, &data);
if (dialog.ShowModal() == wxID_OK)
{
wxFontData retData = dialog.GetFontData();
canvasFont = retData.GetChosenFont();
canvasTextColour = retData.GetColour();
myWindow->Refresh();
}
@endcode
The wxFontDialog presents a font selector to the user, and returns
with font and colour information.
@subsection overview_cmndlg_font_msw The MS Windows font selector
@section overview_cmndlg_print wxPrintDialog Overview
Under Windows, the native font selector common dialog is used. This
presents a dialog box with controls for font name, point size, style, weight,
underlining, strikeout and text foreground colour. A sample of the
font is shown on a white area of the dialog box. Note that
in the translation from full MS Windows fonts to wxWidgets font
conventions, strikeout is ignored and a font family (such as
Swiss or Modern) is deduced from the actual font name (such as Arial
or Courier).
Classes: wxPrintDialog, wxPrintData
@subsection overview_cmndlg_font_generic The generic font selector
This class represents the print and print setup common dialogs. You may obtain
a wxPrinterDC device context from a successfully dismissed print dialog.
Under non-MS Windows platforms, the font selector is simpler.
Controls for font family, point size, style, weight,
underlining and text foreground colour are provided, and
a sample is shown upon a white background. The generic font selector
is also available under MS Windows; use the name wxGenericFontDialog.
The samples/printing example shows how to use it: see @ref overview_printing
for an excerpt from this example.
@subsection overview_cmndlg_font_example Example
In the samples/dialogs directory, there is an example of using
the wxFontDialog class. The application uses the returned font
and colour for drawing text on a canvas. Here is an excerpt:
@section overview_cmndlg_file wxFileDialog Overview
@code
wxFontData data;
data.SetInitialFont(canvasFont);
data.SetColour(canvasTextColour);
Classes: wxFileDialog
wxFontDialog dialog(this, &data);
if (dialog.ShowModal() == wxID_OK)
{
wxFontData retData = dialog.GetFontData();
canvasFont = retData.GetChosenFont();
canvasTextColour = retData.GetColour();
myWindow->Refresh();
}
@endcode
Pops up a file selector box. On Windows and GTK 2.4+, this is the common file
selector dialog. In X, this is a file selector box with somewhat less
functionality. The path and filename are distinct elements of a full file
pathname.
If path is "", the current directory will be used. If filename is "", no
default filename will be supplied. The wildcard determines what files are
displayed in the file selector, and file extension supplies a type extension
for the required filename. Flags may be a combination of wxFD_OPEN, wxFD_SAVE,
wxFD_OVERWRITE_PROMPT, wxFD_HIDE_READONLY, wxFD_FILE_MUST_EXIST, wxFD_MULTIPLE,
wxFD_CHANGE_DIR or 0.
Both the X and Windows versions implement a wildcard filter. Typing a filename
containing wildcards (*, ?) in the filename text item, and clicking on Ok, will
result in only those files matching the pattern being displayed. In the X
version, supplying no default name will result in the wildcard filter being
inserted in the filename text item; the filter is ignored if a default name is
supplied.
@section overview_cmndlg_print wxPrintDialog overview
The wildcard may be a specification for multiple types of file with a
description for each, such as:
Classes: wxPrintDialog, wxPrintData
@verbatim
"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
@endverbatim
This class represents the print and print setup common dialogs.
You may obtain a wxPrinterDC device context from
a successfully dismissed print dialog.
The samples/printing example shows how to use it: see @ref overview_printing for
an excerpt from this example.
@section overview_cmndlg_dir wxDirDialog Overview
Classes: wxDirDialog
This dialog shows a directory selector dialog, allowing the user to select a
single directory.
@section overview_cmndlg_file wxFileDialog overview
Classes: wxFileDialog
@section overview_cmndlg_textentry wxTextEntryDialog Overview
Pops up a file selector box. In Windows and GTK2.4+, this is the common
file selector dialog. In X, this is a file selector box with somewhat less
functionality. The path and filename are distinct elements of a full file pathname.
Classes: wxTextEntryDialog
If path is "", the current directory will be used. If filename is "",
no default filename will be supplied. The wildcard determines what files
are displayed in the file selector, and file extension supplies a type
extension for the required filename. Flags may be a combination of wxFD_OPEN,
wxFD_SAVE, wxFD_OVERWRITE_PROMPT, wxFD_HIDE_READONLY, wxFD_FILE_MUST_EXIST,
wxFD_MULTIPLE, wxFD_CHANGE_DIR or 0.
This is a dialog with a text entry field. The value that the user entered is
obtained using wxTextEntryDialog::GetValue().
Both the X and Windows versions implement a wildcard filter. Typing a
filename containing wildcards (*, ?) in the filename text item, and
clicking on Ok, will result in only those files matching the pattern being
displayed. In the X version, supplying no default name will result in the
wildcard filter being inserted in the filename text item; the filter is
ignored if a default name is supplied.
The wildcard may be a specification for multiple
types of file with a description for each, such as:
@section overview_cmndlg_password wxPasswordEntryDialog Overview
@code
"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
@endcode
Classes: wxPasswordEntryDialog
This is a dialog with a password entry field. The value that the user entered
is obtained using wxTextEntryDialog::GetValue().
@section overview_cmndlg_dir wxDirDialog overview
@section overview_cmndlg_msg wxMessageDialog Overview
Classes: wxDirDialog
Classes: wxMessageDialog
This dialog shows a directory selector dialog, allowing the user to select
a single directory.
This dialog shows a message, plus buttons that can be chosen from OK, Cancel,
Yes, and No. Under Windows, an optional icon can be shown, such as an
exclamation mark or question mark.
The return value of wxMessageDialog::ShowModal() indicates which button the
user pressed.
@section overview_cmndlg_textentry wxTextEntryDialog overview
@section overview_cmndlg_singlechoice wxSingleChoiceDialog Overview
Classes: wxTextEntryDialog
Classes: wxSingleChoiceDialog
This is a dialog with a text entry field. The value that the user
entered is obtained using wxTextEntryDialog::GetValue.
This dialog shows a list of choices, plus OK and (optionally) Cancel. The user
can select one of them. The selection can be obtained from the dialog as an
index, a string or client data.
@section overview_cmndlg_multichoice wxMultiChoiceDialog Overview
@section overview_cmndlg_password wxPasswordEntryDialog overview
Classes: wxMultiChoiceDialog
Classes: wxPasswordEntryDialog
This is a dialog with a password entry field. The value that the user
entered is obtained using wxTextEntryDialog::GetValue.
@section overview_cmndlg_msg wxMessageDialog overview
Classes: wxMessageDialog
This dialog shows a message, plus buttons that can be chosen from OK, Cancel, Yes, and No.
Under Windows, an optional icon can be shown, such as an exclamation mark or question mark.
The return value of wxMessageDialog::ShowModal indicates
which button the user pressed.
@section overview_cmndlg_singlechoice wxSingleChoiceDialog overview
Classes: wxSingleChoiceDialog
This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
select one of them. The selection can be obtained from the dialog as an index,
a string or client data.
@section overview_cmndlg_multichoice wxMultiChoiceDialog overview
Classes: wxMultiChoiceDialog
This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
select one or more of them.
This dialog shows a list of choices, plus OK and (optionally) Cancel. The user
can select one or more of them.
*/