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