]>
git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/overviews/commondialogs.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: commondialogs.h
3 // Purpose: topic overview
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
11 @page overview_cmndlg Common dialogs overview
13 Classes: wxColourDialog, wxFontDialog, wxPrintDialog, wxFileDialog,
14 wxDirDialog, wxTextEntryDialog, wxPasswordEntryDialog,
15 wxMessageDialog, wxSingleChoiceDialog, wxMultiChoiceDialog
17 Common dialog classes and functions encapsulate commonly-needed dialog box requirements.
18 They are all 'modal', grabbing the flow of control until the user dismisses the dialog,
19 to make them easy to use within an application.
21 Some dialogs have both platform-dependent and platform-independent implementations,
22 so that if underlying windowing systems do not provide the required functionality,
23 the generic classes and functions can stand in. For example, under MS Windows, wxColourDialog
24 uses the standard colour selector. There is also an equivalent called wxGenericColourDialog
25 for other platforms, and a macro defines wxColourDialog to be the same as wxGenericColourDialog
26 on non-MS Windows platforms. However, under MS Windows, the generic dialog can also be
27 used, for testing or other purposes.
30 @li @ref overview_cmndlg_colour
31 @li @ref overview_cmndlg_font
32 @li @ref overview_cmndlg_print
33 @li @ref overview_cmndlg_file
34 @li @ref overview_cmndlg_dir
35 @li @ref overview_cmndlg_textentry
36 @li @ref overview_cmndlg_password
37 @li @ref overview_cmndlg_msg
38 @li @ref overview_cmndlg_singlechoice
39 @li @ref overview_cmndlg_multichoice
45 @section overview_cmndlg_colour wxColourDialog overview
47 Classes: wxColourDialog, wxColourData
49 The wxColourDialog presents a colour selector to the user, and returns
50 with colour information.
52 @subsection overview_cmndlg_colour_msw The MS Windows colour selector
54 Under Windows, the native colour selector common dialog is used. This
55 presents a dialog box with three main regions: at the top left, a
56 palette of 48 commonly-used colours is shown. Under this, there is a
57 palette of 16 'custom colours' which can be set by the application if
58 desired. Additionally, the user may open up the dialog box to show
59 a right-hand panel containing controls to select a precise colour, and add
60 it to the custom colour palette.
62 @subsection overview_cmndlg_colour_generic The generic colour selector
64 Under non-MS Windows platforms, the colour selector is a simulation of
65 most of the features of the MS Windows selector. Two palettes of 48
66 standard and 16 custom colours are presented, with the right-hand area
67 containing three sliders for the user to select a colour from red,
68 green and blue components. This colour may be added to the custom colour
69 palette, and will replace either the currently selected custom colour,
70 or the first one in the palette if none is selected. The RGB colour sliders
71 are not optional in the generic colour selector. The generic colour
72 selector is also available under MS Windows; use the name
73 wxGenericColourDialog.
75 @subsection overview_cmndlg_colour_example Example
77 In the samples/dialogs directory, there is an example of using
78 the wxColourDialog class. Here is an excerpt, which
79 sets various parameters of a wxColourData object, including
80 a grey scale for the custom colours. If the user did not cancel
81 the dialog, the application retrieves the selected colour and
82 uses it to set the background of a window.
86 data.SetChooseFull(true);
87 for (int i = 0; i 16; i++)
89 wxColour colour(i*16, i*16, i*16);
90 data.SetCustomColour(i, colour);
93 wxColourDialog dialog(this, &data);
94 if (dialog.ShowModal() == wxID_OK)
96 wxColourData retData = dialog.GetColourData();
97 wxColour col = retData.GetColour();
98 wxBrush brush(col, wxSOLID);
99 myWindow-SetBackground(brush);
107 @section overview_cmndlg_font wxFontDialog overview
109 Classes: wxFontDialog, wxFontData
111 The wxFontDialog presents a font selector to the user, and returns
112 with font and colour information.
114 @subsection overview_cmndlg_font_msw The MS Windows font selector
116 Under Windows, the native font selector common dialog is used. This
117 presents a dialog box with controls for font name, point size, style, weight,
118 underlining, strikeout and text foreground colour. A sample of the
119 font is shown on a white area of the dialog box. Note that
120 in the translation from full MS Windows fonts to wxWidgets font
121 conventions, strikeout is ignored and a font family (such as
122 Swiss or Modern) is deduced from the actual font name (such as Arial
125 @subsection overview_cmndlg_font_generic The generic font selector
127 Under non-MS Windows platforms, the font selector is simpler.
128 Controls for font family, point size, style, weight,
129 underlining and text foreground colour are provided, and
130 a sample is shown upon a white background. The generic font selector
131 is also available under MS Windows; use the name wxGenericFontDialog.
133 @subsection overview_cmndlg_font_example Example
135 In the samples/dialogs directory, there is an example of using
136 the wxFontDialog class. The application uses the returned font
137 and colour for drawing text on a canvas. Here is an excerpt:
141 data.SetInitialFont(canvasFont);
142 data.SetColour(canvasTextColour);
144 wxFontDialog dialog(this, &data);
145 if (dialog.ShowModal() == wxID_OK)
147 wxFontData retData = dialog.GetFontData();
148 canvasFont = retData.GetChosenFont();
149 canvasTextColour = retData.GetColour();
156 @section overview_cmndlg_print wxPrintDialog overview
158 Classes: wxPrintDialog, wxPrintData
160 This class represents the print and print setup common dialogs.
161 You may obtain a wxPrinterDC device context from
162 a successfully dismissed print dialog.
164 The samples/printing example shows how to use it: see @ref overview_printing for
165 an excerpt from this example.
169 @section overview_cmndlg_file wxFileDialog overview
171 Classes: wxFileDialog
173 Pops up a file selector box. In Windows and GTK2.4+, this is the common
174 file selector dialog. In X, this is a file selector box with somewhat less
175 functionality. The path and filename are distinct elements of a full file pathname.
177 If path is "", the current directory will be used. If filename is "",
178 no default filename will be supplied. The wildcard determines what files
179 are displayed in the file selector, and file extension supplies a type
180 extension for the required filename. Flags may be a combination of wxFD_OPEN,
181 wxFD_SAVE, wxFD_OVERWRITE_PROMPT, wxFD_HIDE_READONLY, wxFD_FILE_MUST_EXIST,
182 wxFD_MULTIPLE, wxFD_CHANGE_DIR or 0.
184 Both the X and Windows versions implement a wildcard filter. Typing a
185 filename containing wildcards (*, ?) in the filename text item, and
186 clicking on Ok, will result in only those files matching the pattern being
187 displayed. In the X version, supplying no default name will result in the
188 wildcard filter being inserted in the filename text item; the filter is
189 ignored if a default name is supplied.
191 The wildcard may be a specification for multiple
192 types of file with a description for each, such as:
195 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
200 @section overview_cmndlg_dir wxDirDialog overview
204 This dialog shows a directory selector dialog, allowing the user to select
209 @section overview_cmndlg_textentry wxTextEntryDialog overview
211 Classes: wxTextEntryDialog
213 This is a dialog with a text entry field. The value that the user
214 entered is obtained using wxTextEntryDialog::GetValue.
218 @section overview_cmndlg_password wxPasswordEntryDialog overview
220 Classes: wxPasswordEntryDialog
222 This is a dialog with a password entry field. The value that the user
223 entered is obtained using wxTextEntryDialog::GetValue.
227 @section overview_cmndlg_msg wxMessageDialog overview
229 Classes: wxMessageDialog
231 This dialog shows a message, plus buttons that can be chosen from OK, Cancel, Yes, and No.
232 Under Windows, an optional icon can be shown, such as an exclamation mark or question mark.
234 The return value of wxMessageDialog::ShowModal indicates
235 which button the user pressed.
239 @section overview_cmndlg_singlechoice wxSingleChoiceDialog overview
241 Classes: wxSingleChoiceDialog
243 This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
244 select one of them. The selection can be obtained from the dialog as an index,
245 a string or client data.
249 @section overview_cmndlg_multichoice wxMultiChoiceDialog overview
251 Classes: wxMultiChoiceDialog
253 This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
254 select one or more of them.