d54cf7ff13
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52014 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
258 lines
8.8 KiB
C
258 lines
8.8 KiB
C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: commondialogs.h
|
|
// Purpose: topic overview
|
|
// Author: wxWidgets team
|
|
// RCS-ID: $Id$
|
|
// Licence: wxWindows license
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*!
|
|
|
|
@page overview_cmndlg Common dialogs overview
|
|
|
|
Classes: #wxColourDialog, #wxFontDialog, #wxPrintDialog, #wxFileDialog,
|
|
#wxDirDialog, #wxTextEntryDialog, #wxPasswordEntryDialog,
|
|
#wxMessageDialog, #wxSingleChoiceDialog, #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
|
|
|
|
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
|
|
|
|
|
|
|
|
@section overview_cmndlg_font wxFontDialog overview
|
|
|
|
Classes: #wxFontDialog, #wxFontData
|
|
|
|
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
|
|
|
|
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).
|
|
|
|
@subsection overview_cmndlg_font_generic The generic font selector
|
|
|
|
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:
|
|
|
|
@code
|
|
wxFontData data;
|
|
data.SetInitialFont(canvasFont);
|
|
data.SetColour(canvasTextColour);
|
|
|
|
wxFontDialog dialog(this, &data);
|
|
if (dialog.ShowModal() == wxID_OK)
|
|
{
|
|
wxFontData retData = dialog.GetFontData();
|
|
canvasFont = retData.GetChosenFont();
|
|
canvasTextColour = retData.GetColour();
|
|
myWindow-Refresh();
|
|
}
|
|
@endcode
|
|
|
|
|
|
|
|
@section overview_cmndlg_print wxPrintDialog overview
|
|
|
|
Classes: #wxPrintDialog, #wxPrintData
|
|
|
|
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_file wxFileDialog overview
|
|
|
|
Classes: #wxFileDialog
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
The wildcard may be a specification for multiple
|
|
types of file with a description for each, such as:
|
|
|
|
@code
|
|
"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
|
|
@endcode
|
|
|
|
|
|
|
|
@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_textentry wxTextEntryDialog overview
|
|
|
|
Classes: #wxTextEntryDialog
|
|
|
|
This is a dialog with a text entry field. The value that the user
|
|
entered is obtained using wxTextEntryDialog::GetValue.
|
|
|
|
|
|
|
|
@section overview_cmndlg_password wxPasswordEntryDialog overview
|
|
|
|
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.
|
|
|
|
*/
|
|
|