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 license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /*!
  10
  11  @page overview_cmndlg Common dialogs overview
  12
  13  Classes: #wxColourDialog, #wxFontDialog, #wxPrintDialog, #wxFileDialog,
  14           #wxDirDialog, #wxTextEntryDialog, #wxPasswordEntryDialog,
  15           #wxMessageDialog, #wxSingleChoiceDialog, #wxMultiChoiceDialog
  16
  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.
  20
  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.
  28
  29
  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
  40
  41
  42  <hr>
  43
  44
  45  @section overview_cmndlg_colour wxColourDialog overview
  46
  47  Classes: #wxColourDialog, #wxColourData
  48
  49  The wxColourDialog presents a colour selector to the user, and returns
  50  with colour information.
  51
  52  @subsection overview_cmndlg_colour_msw The MS Windows colour selector
  53
  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.
  61
  62  @subsection overview_cmndlg_colour_generic The generic colour selector
  63
  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.
  74
  75  @subsection overview_cmndlg_colour_example Example
  76
  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.
  83
  84  @code
  85    wxColourData data;
  86    data.SetChooseFull(true);
  87    for (int i = 0; i  16; i++)
  88    {
  89      wxColour colour(i*16, i*16, i*16);
  90      data.SetCustomColour(i, colour);
  91    }
  92
  93    wxColourDialog dialog(this, &data);
  94    if (dialog.ShowModal() == wxID_OK)
  95    {
  96      wxColourData retData = dialog.GetColourData();
  97      wxColour col = retData.GetColour();
  98      wxBrush brush(col, wxSOLID);
  99      myWindow-SetBackground(brush);
 100      myWindow-Clear();
 101      myWindow-Refresh();
 102    }
 103  @endcode
 104
 105
 106
 107  @section overview_cmndlg_font wxFontDialog overview
 108
 109  Classes: #wxFontDialog, #wxFontData
 110
 111  The wxFontDialog presents a font selector to the user, and returns
 112  with font and colour information.
 113
 114  @subsection overview_cmndlg_font_msw The MS Windows font selector
 115
 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
 123  or Courier).
 124
 125  @subsection overview_cmndlg_font_generic The generic font selector
 126
 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.
 132
 133  @subsection overview_cmndlg_font_example Example
 134
 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:
 138
 139  @code
 140    wxFontData data;
 141    data.SetInitialFont(canvasFont);
 142    data.SetColour(canvasTextColour);
 143
 144    wxFontDialog dialog(this, &data);
 145    if (dialog.ShowModal() == wxID_OK)
 146    {
 147      wxFontData retData = dialog.GetFontData();
 148      canvasFont = retData.GetChosenFont();
 149      canvasTextColour = retData.GetColour();
 150      myWindow-Refresh();
 151    }
 152  @endcode
 153
 154
 155
 156  @section overview_cmndlg_print wxPrintDialog overview
 157
 158  Classes: #wxPrintDialog, #wxPrintData
 159
 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.
 163
 164  The samples/printing example shows how to use it: see @ref overview_printing for
 165  an excerpt from this example.
 166
 167
 168
 169  @section overview_cmndlg_file wxFileDialog overview
 170
 171  Classes: #wxFileDialog
 172
 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.
 176
 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.
 183
 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.
 190
 191  The wildcard may be a specification for multiple
 192  types of file with a description for each, such as:
 193
 194  @code
 195  "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
 196  @endcode
 197
 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
 205  a single directory.
 206
 207
 208
 209  @section overview_cmndlg_textentry wxTextEntryDialog overview
 210
 211  Classes: #wxTextEntryDialog
 212
 213  This is a dialog with a text entry field. The value that the user
 214  entered is obtained using wxTextEntryDialog::GetValue.
 215
 216
 217
 218  @section overview_cmndlg_password wxPasswordEntryDialog overview
 219
 220  Classes: #wxPasswordEntryDialog
 221
 222  This is a dialog with a password entry field. The value that the user
 223  entered is obtained using wxTextEntryDialog::GetValue.
 224
 225
 226
 227  @section overview_cmndlg_msg wxMessageDialog overview
 228
 229  Classes: #wxMessageDialog
 230
 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.
 233
 234  The return value of wxMessageDialog::ShowModal indicates
 235  which button the user pressed.
 236
 237
 238
 239  @section overview_cmndlg_singlechoice wxSingleChoiceDialog overview
 240
 241  Classes: #wxSingleChoiceDialog
 242
 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.
 246
 247
 248
 249  @section overview_cmndlg_multichoice wxMultiChoiceDialog overview
 250
 251  Classes: #wxMultiChoiceDialog
 252
 253  This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
 254  select one or more of them.
 255
 256 */
 257