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