docs/doxygen/overviews/commondialogs.h

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