3f66f6a5b3
This keyword is not expanded by Git which means it's not replaced with the correct revision value in the releases made using git-based scripts and it's confusing to have lines with unexpanded "$Id$" in the released files. As expanding them with Git is not that simple (it could be done with git archive and export-subst attribute) and there are not many benefits in having them in the first place, just remove all these lines. If nothing else, this will make an eventual transition to Git simpler. Closes #14487. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@74602 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
239 lines
8.1 KiB
C
239 lines
8.1 KiB
C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: commondialogs.h
|
|
// Purpose: topic overview
|
|
// Author: wxWidgets team
|
|
// Licence: wxWindows licence
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
|
|
@page overview_cmndlg Common Dialogs
|
|
|
|
@tableofcontents
|
|
|
|
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.
|
|
|
|
@see @ref group_class_cmndlg
|
|
|
|
|
|
|
|
@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. 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.
|
|
|
|
The wildcard may be a specification for multiple types of file with a
|
|
description for each, such as:
|
|
|
|
@verbatim
|
|
"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
|
|
@endverbatim
|
|
|
|
|
|
|
|
@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.
|
|
|
|
*/
|