docs/doxygen/overviews/commondialogs.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        commondialogs.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   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