| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: commondialogs.h |
| 3 | // Purpose: topic overview |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows license |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | |
| 11 | @page overview_cmndlg Common Dialogs |
| 12 | |
| 13 | Classes: |
| 14 | |
| 15 | @li wxColourDialog |
| 16 | @li wxFontDialog |
| 17 | @li wxPrintDialog |
| 18 | @li wxFileDialog |
| 19 | @li wxDirDialog |
| 20 | @li wxTextEntryDialog |
| 21 | @li wxPasswordEntryDialog |
| 22 | @li wxMessageDialog |
| 23 | @li wxSingleChoiceDialog |
| 24 | @li wxMultiChoiceDialog |
| 25 | |
| 26 | Common dialog classes and functions encapsulate commonly-needed dialog box |
| 27 | requirements. They are all 'modal', grabbing the flow of control until the user |
| 28 | dismisses the dialog, to make them easy to use within an application. |
| 29 | |
| 30 | Some dialogs have both platform-dependent and platform-independent |
| 31 | implementations, so that if underlying windowing systems do not provide the |
| 32 | required functionality, the generic classes and functions can stand in. For |
| 33 | example, under MS Windows, wxColourDialog uses the standard colour selector. |
| 34 | There is also an equivalent called wxGenericColourDialog for other platforms, |
| 35 | and a macro defines wxColourDialog to be the same as wxGenericColourDialog on |
| 36 | non-MS Windows platforms. However, under MS Windows, the generic dialog can |
| 37 | also be used, for testing or other purposes. |
| 38 | |
| 39 | @li @ref overview_cmndlg_colour |
| 40 | @li @ref overview_cmndlg_font |
| 41 | @li @ref overview_cmndlg_print |
| 42 | @li @ref overview_cmndlg_file |
| 43 | @li @ref overview_cmndlg_dir |
| 44 | @li @ref overview_cmndlg_textentry |
| 45 | @li @ref overview_cmndlg_password |
| 46 | @li @ref overview_cmndlg_msg |
| 47 | @li @ref overview_cmndlg_singlechoice |
| 48 | @li @ref overview_cmndlg_multichoice |
| 49 | |
| 50 | |
| 51 | <hr> |
| 52 | |
| 53 | |
| 54 | @section overview_cmndlg_colour wxColourDialog Overview |
| 55 | |
| 56 | Classes: wxColourDialog, wxColourData |
| 57 | |
| 58 | The wxColourDialog presents a colour selector to the user, and returns with |
| 59 | colour information. |
| 60 | |
| 61 | @subsection overview_cmndlg_colour_msw The MS Windows Colour Selector |
| 62 | |
| 63 | Under Windows, the native colour selector common dialog is used. This presents |
| 64 | a dialog box with three main regions: at the top left, a palette of 48 |
| 65 | commonly-used colours is shown. Under this, there is a palette of 16 |
| 66 | 'custom colours' which can be set by the application if desired. Additionally, |
| 67 | the user may open up the dialog box to show a right-hand panel containing |
| 68 | controls to select a precise colour, and add it to the custom colour palette. |
| 69 | |
| 70 | @subsection overview_cmndlg_colour_generic The Generic Colour Selector |
| 71 | |
| 72 | Under non-MS Windows platforms, the colour selector is a simulation of most of |
| 73 | the features of the MS Windows selector. Two palettes of 48 standard and 16 |
| 74 | custom colours are presented, with the right-hand area containing three sliders |
| 75 | for the user to select a colour from red, green and blue components. This |
| 76 | colour may be added to the custom colour palette, and will replace either the |
| 77 | currently selected custom colour, or the first one in the palette if none is |
| 78 | selected. The RGB colour sliders are not optional in the generic colour |
| 79 | selector. The generic colour selector is also available under MS Windows; use |
| 80 | the name wxGenericColourDialog. |
| 81 | |
| 82 | @subsection overview_cmndlg_colour_example Example |
| 83 | |
| 84 | In the samples/dialogs directory, there is an example of using the |
| 85 | wxColourDialog class. Here is an excerpt, which sets various parameters of a |
| 86 | wxColourData object, including a grey scale for the custom colours. If the user |
| 87 | did not cancel the dialog, the application retrieves the selected colour and |
| 88 | uses it to set the background of a window. |
| 89 | |
| 90 | @code |
| 91 | wxColourData data; |
| 92 | data.SetChooseFull(true); |
| 93 | for (int i = 0; i < 16; i++) |
| 94 | { |
| 95 | wxColour colour(i*16, i*16, i*16); |
| 96 | data.SetCustomColour(i, colour); |
| 97 | } |
| 98 | |
| 99 | wxColourDialog dialog(this, &data); |
| 100 | if (dialog.ShowModal() == wxID_OK) |
| 101 | { |
| 102 | wxColourData retData = dialog.GetColourData(); |
| 103 | wxColour col = retData.GetColour(); |
| 104 | wxBrush brush(col, wxSOLID); |
| 105 | myWindow->SetBackground(brush); |
| 106 | myWindow->Clear(); |
| 107 | myWindow->Refresh(); |
| 108 | } |
| 109 | @endcode |
| 110 | |
| 111 | |
| 112 | @section overview_cmndlg_font wxFontDialog Overview |
| 113 | |
| 114 | Classes: wxFontDialog, wxFontData |
| 115 | |
| 116 | The wxFontDialog presents a font selector to the user, and returns with font |
| 117 | and colour information. |
| 118 | |
| 119 | @subsection overview_cmndlg_font_msw The MS Windows Font Selector |
| 120 | |
| 121 | Under Windows, the native font selector common dialog is used. This presents a |
| 122 | dialog box with controls for font name, point size, style, weight, underlining, |
| 123 | strikeout and text foreground colour. A sample of the font is shown on a white |
| 124 | area of the dialog box. Note that in the translation from full MS Windows fonts |
| 125 | to wxWidgets font conventions, strikeout is ignored and a font family (such as |
| 126 | Swiss or Modern) is deduced from the actual font name (such as Arial or |
| 127 | Courier). |
| 128 | |
| 129 | @subsection overview_cmndlg_font_generic The Generic Font Selector |
| 130 | |
| 131 | Under non-MS Windows platforms, the font selector is simpler. Controls for font |
| 132 | family, point size, style, weight, underlining and text foreground colour are |
| 133 | provided, and a sample is shown upon a white background. The generic font |
| 134 | selector is also available under MS Windows; use the name wxGenericFontDialog. |
| 135 | |
| 136 | @subsection overview_cmndlg_font_example Example |
| 137 | |
| 138 | In the samples/dialogs directory, there is an example of using the wxFontDialog |
| 139 | class. The application uses the returned font and colour for drawing text on a |
| 140 | canvas. Here is an excerpt: |
| 141 | |
| 142 | @code |
| 143 | wxFontData data; |
| 144 | data.SetInitialFont(canvasFont); |
| 145 | data.SetColour(canvasTextColour); |
| 146 | |
| 147 | wxFontDialog dialog(this, &data); |
| 148 | if (dialog.ShowModal() == wxID_OK) |
| 149 | { |
| 150 | wxFontData retData = dialog.GetFontData(); |
| 151 | canvasFont = retData.GetChosenFont(); |
| 152 | canvasTextColour = retData.GetColour(); |
| 153 | myWindow->Refresh(); |
| 154 | } |
| 155 | @endcode |
| 156 | |
| 157 | |
| 158 | @section overview_cmndlg_print wxPrintDialog Overview |
| 159 | |
| 160 | Classes: wxPrintDialog, wxPrintData |
| 161 | |
| 162 | This class represents the print and print setup common dialogs. You may obtain |
| 163 | a wxPrinterDC device context from a successfully dismissed print dialog. |
| 164 | |
| 165 | The samples/printing example shows how to use it: see @ref overview_printing |
| 166 | for an excerpt from this example. |
| 167 | |
| 168 | |
| 169 | @section overview_cmndlg_file wxFileDialog Overview |
| 170 | |
| 171 | Classes: wxFileDialog |
| 172 | |
| 173 | Pops up a file selector box. On Windows and GTK 2.4+, this is the common file |
| 174 | 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 |
| 176 | pathname. |
| 177 | |
| 178 | If path is "", the current directory will be used. If filename is "", no |
| 179 | default filename will be supplied. The wildcard determines what files are |
| 180 | displayed in the file selector, and file extension supplies a type extension |
| 181 | for the required filename. Flags may be a combination of wxFD_OPEN, wxFD_SAVE, |
| 182 | wxFD_OVERWRITE_PROMPT, wxFD_HIDE_READONLY, wxFD_FILE_MUST_EXIST, wxFD_MULTIPLE, |
| 183 | wxFD_CHANGE_DIR or 0. |
| 184 | |
| 185 | Both the X and Windows versions implement a wildcard filter. Typing a filename |
| 186 | containing wildcards (*, ?) in the filename text item, and clicking on Ok, will |
| 187 | result in only those files matching the pattern being displayed. In the X |
| 188 | version, supplying no default name will result in the wildcard filter being |
| 189 | inserted in the filename text item; the filter is ignored if a default name is |
| 190 | supplied. |
| 191 | |
| 192 | The wildcard may be a specification for multiple types of file with a |
| 193 | description for each, such as: |
| 194 | |
| 195 | @verbatim |
| 196 | "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" |
| 197 | @endverbatim |
| 198 | |
| 199 | |
| 200 | @section overview_cmndlg_dir wxDirDialog Overview |
| 201 | |
| 202 | Classes: wxDirDialog |
| 203 | |
| 204 | This dialog shows a directory selector dialog, allowing the user to select a |
| 205 | single directory. |
| 206 | |
| 207 | |
| 208 | @section overview_cmndlg_textentry wxTextEntryDialog Overview |
| 209 | |
| 210 | Classes: wxTextEntryDialog |
| 211 | |
| 212 | This is a dialog with a text entry field. The value that the user entered is |
| 213 | obtained using wxTextEntryDialog::GetValue(). |
| 214 | |
| 215 | |
| 216 | @section overview_cmndlg_password wxPasswordEntryDialog Overview |
| 217 | |
| 218 | Classes: wxPasswordEntryDialog |
| 219 | |
| 220 | This is a dialog with a password entry field. The value that the user entered |
| 221 | is obtained using wxTextEntryDialog::GetValue(). |
| 222 | |
| 223 | |
| 224 | @section overview_cmndlg_msg wxMessageDialog Overview |
| 225 | |
| 226 | Classes: wxMessageDialog |
| 227 | |
| 228 | This dialog shows a message, plus buttons that can be chosen from OK, Cancel, |
| 229 | Yes, and No. Under Windows, an optional icon can be shown, such as an |
| 230 | exclamation mark or question mark. |
| 231 | |
| 232 | The return value of wxMessageDialog::ShowModal() indicates which button the |
| 233 | user pressed. |
| 234 | |
| 235 | |
| 236 | @section overview_cmndlg_singlechoice wxSingleChoiceDialog Overview |
| 237 | |
| 238 | Classes: wxSingleChoiceDialog |
| 239 | |
| 240 | This dialog shows a list of choices, plus OK and (optionally) Cancel. The user |
| 241 | can select one of them. The selection can be obtained from the dialog as an |
| 242 | index, a string or client data. |
| 243 | |
| 244 | |
| 245 | @section overview_cmndlg_multichoice wxMultiChoiceDialog Overview |
| 246 | |
| 247 | Classes: wxMultiChoiceDialog |
| 248 | |
| 249 | This dialog shows a list of choices, plus OK and (optionally) Cancel. The user |
| 250 | can select one or more of them. |
| 251 | |
| 252 | */ |
| 253 | |