docs/doxygen/overviews/commondialogs.h

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