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