docs/latex/wx/tcommdlg.tex

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