X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d54cf7ff131b62cc83116d5bfb8d2b5c49de9574..7df4c51f6021fbf1b204db918a1cc5c4ddff31cc:/docs/doxygen/overviews/commondialogs.h diff --git a/docs/doxygen/overviews/commondialogs.h b/docs/doxygen/overviews/commondialogs.h index 5f25531a48..4f4f35d47e 100644 --- a/docs/doxygen/overviews/commondialogs.h +++ b/docs/doxygen/overviews/commondialogs.h @@ -6,252 +6,248 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/*! +/** + +@page overview_cmndlg Common Dialogs + +Classes: + +@li wxColourDialog +@li wxFontDialog +@li wxPrintDialog +@li wxFileDialog +@li wxDirDialog +@li wxTextEntryDialog +@li wxPasswordEntryDialog +@li wxMessageDialog +@li wxSingleChoiceDialog +@li wxMultiChoiceDialog + +Common dialog classes and functions encapsulate commonly-needed dialog box +requirements. They are all 'modal', grabbing the flow of control until the user +dismisses the dialog, to make them easy to use within an application. + +Some dialogs have both platform-dependent and platform-independent +implementations, so that if underlying windowing systems do not provide the +required functionality, the generic classes and functions can stand in. For +example, under MS Windows, wxColourDialog uses the standard colour selector. +There is also an equivalent called wxGenericColourDialog for other platforms, +and a macro defines wxColourDialog to be the same as wxGenericColourDialog on +non-MS Windows platforms. However, under MS Windows, the generic dialog can +also be used, for testing or other purposes. + +@li @ref overview_cmndlg_colour +@li @ref overview_cmndlg_font +@li @ref overview_cmndlg_print +@li @ref overview_cmndlg_file +@li @ref overview_cmndlg_dir +@li @ref overview_cmndlg_textentry +@li @ref overview_cmndlg_password +@li @ref overview_cmndlg_msg +@li @ref overview_cmndlg_singlechoice +@li @ref overview_cmndlg_multichoice + + +
+ + +@section overview_cmndlg_colour wxColourDialog Overview + +Classes: wxColourDialog, wxColourData + +The wxColourDialog presents a colour selector to the user, and returns with +colour information. + +@subsection overview_cmndlg_colour_msw The MS Windows Colour Selector + +Under Windows, the native colour selector common dialog is used. This presents +a dialog box with three main regions: at the top left, a palette of 48 +commonly-used colours is shown. Under this, there is a palette of 16 +'custom colours' which can be set by the application if desired. Additionally, +the user may open up the dialog box to show a right-hand panel containing +controls to select a precise colour, and add it to the custom colour palette. + +@subsection overview_cmndlg_colour_generic The Generic Colour Selector - @page overview_cmndlg Common dialogs overview - - Classes: #wxColourDialog, #wxFontDialog, #wxPrintDialog, #wxFileDialog, - #wxDirDialog, #wxTextEntryDialog, #wxPasswordEntryDialog, - #wxMessageDialog, #wxSingleChoiceDialog, #wxMultiChoiceDialog +Under non-MS Windows platforms, the colour selector is a simulation of most of +the features of the MS Windows selector. Two palettes of 48 standard and 16 +custom colours are presented, with the right-hand area containing three sliders +for the user to select a colour from red, green and blue components. This +colour may be added to the custom colour palette, and will replace either the +currently selected custom colour, or the first one in the palette if none is +selected. The RGB colour sliders are not optional in the generic colour +selector. The generic colour selector is also available under MS Windows; use +the name wxGenericColourDialog. + +@subsection overview_cmndlg_colour_example Example + +In the samples/dialogs directory, there is an example of using the +wxColourDialog class. Here is an excerpt, which sets various parameters of a +wxColourData object, including a grey scale for the custom colours. If the user +did not cancel the dialog, the application retrieves the selected colour and +uses it to set the background of a window. + +@code +wxColourData data; +data.SetChooseFull(true); +for (int i = 0; i < 16; i++) +{ + wxColour colour(i*16, i*16, i*16); + data.SetCustomColour(i, colour); +} + +wxColourDialog dialog(this, &data); +if (dialog.ShowModal() == wxID_OK) +{ + wxColourData retData = dialog.GetColourData(); + wxColour col = retData.GetColour(); + wxBrush brush(col, wxSOLID); + myWindow->SetBackground(brush); + myWindow->Clear(); + myWindow->Refresh(); +} +@endcode - Common dialog classes and functions encapsulate commonly-needed dialog box requirements. - They are all 'modal', grabbing the flow of control until the user dismisses the dialog, - to make them easy to use within an application. - - Some dialogs have both platform-dependent and platform-independent implementations, - so that if underlying windowing systems do not provide the required functionality, - the generic classes and functions can stand in. For example, under MS Windows, wxColourDialog - uses the standard colour selector. There is also an equivalent called wxGenericColourDialog - for other platforms, and a macro defines wxColourDialog to be the same as wxGenericColourDialog - on non-MS Windows platforms. However, under MS Windows, the generic dialog can also be - used, for testing or other purposes. - - - @li @ref overview_cmndlg_colour - @li @ref overview_cmndlg_font - @li @ref overview_cmndlg_print - @li @ref overview_cmndlg_file - @li @ref overview_cmndlg_dir - @li @ref overview_cmndlg_textentry - @li @ref overview_cmndlg_password - @li @ref overview_cmndlg_msg - @li @ref overview_cmndlg_singlechoice - @li @ref overview_cmndlg_multichoice - - -
+@section overview_cmndlg_font wxFontDialog Overview - @section overview_cmndlg_colour wxColourDialog overview - - Classes: #wxColourDialog, #wxColourData - - The wxColourDialog presents a colour selector to the user, and returns - with colour information. - - @subsection overview_cmndlg_colour_msw The MS Windows colour selector - - Under Windows, the native colour selector common dialog is used. This - presents a dialog box with three main regions: at the top left, a - palette of 48 commonly-used colours is shown. Under this, there is a - palette of 16 'custom colours' which can be set by the application if - desired. Additionally, the user may open up the dialog box to show - a right-hand panel containing controls to select a precise colour, and add - it to the custom colour palette. - - @subsection overview_cmndlg_colour_generic The generic colour selector +Classes: wxFontDialog, wxFontData - Under non-MS Windows platforms, the colour selector is a simulation of - most of the features of the MS Windows selector. Two palettes of 48 - standard and 16 custom colours are presented, with the right-hand area - containing three sliders for the user to select a colour from red, - green and blue components. This colour may be added to the custom colour - palette, and will replace either the currently selected custom colour, - or the first one in the palette if none is selected. The RGB colour sliders - are not optional in the generic colour selector. The generic colour - selector is also available under MS Windows; use the name - wxGenericColourDialog. +The wxFontDialog presents a font selector to the user, and returns with font +and colour information. - @subsection overview_cmndlg_colour_example Example +@subsection overview_cmndlg_font_msw The MS Windows Font Selector - In the samples/dialogs directory, there is an example of using - the wxColourDialog class. Here is an excerpt, which - sets various parameters of a wxColourData object, including - a grey scale for the custom colours. If the user did not cancel - the dialog, the application retrieves the selected colour and - uses it to set the background of a window. +Under Windows, the native font selector common dialog is used. This presents a +dialog box with controls for font name, point size, style, weight, underlining, +strikeout and text foreground colour. A sample of the font is shown on a white +area of the dialog box. Note that in the translation from full MS Windows fonts +to wxWidgets font conventions, strikeout is ignored and a font family (such as +Swiss or Modern) is deduced from the actual font name (such as Arial or +Courier). - @code - wxColourData data; - data.SetChooseFull(true); - for (int i = 0; i 16; i++) - { - wxColour colour(i*16, i*16, i*16); - data.SetCustomColour(i, colour); - } +@subsection overview_cmndlg_font_generic The Generic Font Selector - wxColourDialog dialog(this, &data); - if (dialog.ShowModal() == wxID_OK) - { - wxColourData retData = dialog.GetColourData(); - wxColour col = retData.GetColour(); - wxBrush brush(col, wxSOLID); - myWindow-SetBackground(brush); - myWindow-Clear(); - myWindow-Refresh(); - } - @endcode +Under non-MS Windows platforms, the font selector is simpler. Controls for font +family, point size, style, weight, underlining and text foreground colour are +provided, and a sample is shown upon a white background. The generic font +selector is also available under MS Windows; use the name wxGenericFontDialog. +@subsection overview_cmndlg_font_example Example +In the samples/dialogs directory, there is an example of using the wxFontDialog +class. The application uses the returned font and colour for drawing text on a +canvas. Here is an excerpt: - @section overview_cmndlg_font wxFontDialog overview +@code +wxFontData data; +data.SetInitialFont(canvasFont); +data.SetColour(canvasTextColour); - Classes: #wxFontDialog, #wxFontData +wxFontDialog dialog(this, &data); +if (dialog.ShowModal() == wxID_OK) +{ + wxFontData retData = dialog.GetFontData(); + canvasFont = retData.GetChosenFont(); + canvasTextColour = retData.GetColour(); + myWindow->Refresh(); +} +@endcode - The wxFontDialog presents a font selector to the user, and returns - with font and colour information. - @subsection overview_cmndlg_font_msw The MS Windows font selector +@section overview_cmndlg_print wxPrintDialog Overview - Under Windows, the native font selector common dialog is used. This - presents a dialog box with controls for font name, point size, style, weight, - underlining, strikeout and text foreground colour. A sample of the - font is shown on a white area of the dialog box. Note that - in the translation from full MS Windows fonts to wxWidgets font - conventions, strikeout is ignored and a font family (such as - Swiss or Modern) is deduced from the actual font name (such as Arial - or Courier). +Classes: wxPrintDialog, wxPrintData - @subsection overview_cmndlg_font_generic The generic font selector +This class represents the print and print setup common dialogs. You may obtain +a wxPrinterDC device context from a successfully dismissed print dialog. - Under non-MS Windows platforms, the font selector is simpler. - Controls for font family, point size, style, weight, - underlining and text foreground colour are provided, and - a sample is shown upon a white background. The generic font selector - is also available under MS Windows; use the name wxGenericFontDialog. +The samples/printing example shows how to use it: see @ref overview_printing +for an excerpt from this example. - @subsection overview_cmndlg_font_example Example - In the samples/dialogs directory, there is an example of using - the wxFontDialog class. The application uses the returned font - and colour for drawing text on a canvas. Here is an excerpt: +@section overview_cmndlg_file wxFileDialog Overview - @code - wxFontData data; - data.SetInitialFont(canvasFont); - data.SetColour(canvasTextColour); +Classes: wxFileDialog - wxFontDialog dialog(this, &data); - if (dialog.ShowModal() == wxID_OK) - { - wxFontData retData = dialog.GetFontData(); - canvasFont = retData.GetChosenFont(); - canvasTextColour = retData.GetColour(); - myWindow-Refresh(); - } - @endcode +Pops up a file selector box. On Windows and GTK 2.4+, this is the common file +selector dialog. In X, this is a file selector box with somewhat less +functionality. The path and filename are distinct elements of a full file +pathname. +If path is "", the current directory will be used. If filename is "", no +default filename will be supplied. The wildcard determines what files are +displayed in the file selector, and file extension supplies a type extension +for the required filename. Flags may be a combination of wxFD_OPEN, wxFD_SAVE, +wxFD_OVERWRITE_PROMPT, wxFD_HIDE_READONLY, wxFD_FILE_MUST_EXIST, wxFD_MULTIPLE, +wxFD_CHANGE_DIR or 0. +Both the X and Windows versions implement a wildcard filter. Typing a filename +containing wildcards (*, ?) in the filename text item, and clicking on Ok, will +result in only those files matching the pattern being displayed. In the X +version, supplying no default name will result in the wildcard filter being +inserted in the filename text item; the filter is ignored if a default name is +supplied. - @section overview_cmndlg_print wxPrintDialog overview +The wildcard may be a specification for multiple types of file with a +description for each, such as: - Classes: #wxPrintDialog, #wxPrintData +@verbatim +"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" +@endverbatim - This class represents the print and print setup common dialogs. - You may obtain a #wxPrinterDC device context from - a successfully dismissed print dialog. - The samples/printing example shows how to use it: see @ref overview_printing for - an excerpt from this example. +@section overview_cmndlg_dir wxDirDialog Overview +Classes: wxDirDialog +This dialog shows a directory selector dialog, allowing the user to select a +single directory. - @section overview_cmndlg_file wxFileDialog overview - Classes: #wxFileDialog +@section overview_cmndlg_textentry wxTextEntryDialog Overview - Pops up a file selector box. In Windows and GTK2.4+, this is the common - file selector dialog. In X, this is a file selector box with somewhat less - functionality. The path and filename are distinct elements of a full file pathname. +Classes: wxTextEntryDialog - If path is "", the current directory will be used. If filename is "", - no default filename will be supplied. The wildcard determines what files - are displayed in the file selector, and file extension supplies a type - extension for the required filename. Flags may be a combination of wxFD_OPEN, - wxFD_SAVE, wxFD_OVERWRITE_PROMPT, wxFD_HIDE_READONLY, wxFD_FILE_MUST_EXIST, - wxFD_MULTIPLE, wxFD_CHANGE_DIR or 0. +This is a dialog with a text entry field. The value that the user entered is +obtained using wxTextEntryDialog::GetValue(). - Both the X and Windows versions implement a wildcard filter. Typing a - filename containing wildcards (*, ?) in the filename text item, and - clicking on Ok, will result in only those files matching the pattern being - displayed. In the X version, supplying no default name will result in the - wildcard filter being inserted in the filename text item; the filter is - ignored if a default name is supplied. - The wildcard may be a specification for multiple - types of file with a description for each, such as: +@section overview_cmndlg_password wxPasswordEntryDialog Overview - @code - "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" - @endcode +Classes: wxPasswordEntryDialog +This is a dialog with a password entry field. The value that the user entered +is obtained using wxTextEntryDialog::GetValue(). - @section overview_cmndlg_dir wxDirDialog overview +@section overview_cmndlg_msg wxMessageDialog Overview - Classes: #wxDirDialog +Classes: wxMessageDialog - This dialog shows a directory selector dialog, allowing the user to select - a single directory. +This dialog shows a message, plus buttons that can be chosen from OK, Cancel, +Yes, and No. Under Windows, an optional icon can be shown, such as an +exclamation mark or question mark. +The return value of wxMessageDialog::ShowModal() indicates which button the +user pressed. - @section overview_cmndlg_textentry wxTextEntryDialog overview +@section overview_cmndlg_singlechoice wxSingleChoiceDialog Overview - Classes: #wxTextEntryDialog +Classes: wxSingleChoiceDialog - This is a dialog with a text entry field. The value that the user - entered is obtained using wxTextEntryDialog::GetValue. +This dialog shows a list of choices, plus OK and (optionally) Cancel. The user +can select one of them. The selection can be obtained from the dialog as an +index, a string or client data. +@section overview_cmndlg_multichoice wxMultiChoiceDialog Overview - @section overview_cmndlg_password wxPasswordEntryDialog overview +Classes: wxMultiChoiceDialog - Classes: #wxPasswordEntryDialog - - This is a dialog with a password entry field. The value that the user - entered is obtained using wxTextEntryDialog::GetValue. - - - - @section overview_cmndlg_msg wxMessageDialog overview - - Classes: #wxMessageDialog - - This dialog shows a message, plus buttons that can be chosen from OK, Cancel, Yes, and No. - Under Windows, an optional icon can be shown, such as an exclamation mark or question mark. - - The return value of wxMessageDialog::ShowModal indicates - which button the user pressed. - - - - @section overview_cmndlg_singlechoice wxSingleChoiceDialog overview - - Classes: #wxSingleChoiceDialog - - This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can - select one of them. The selection can be obtained from the dialog as an index, - a string or client data. - - - - @section overview_cmndlg_multichoice wxMultiChoiceDialog overview - - Classes: #wxMultiChoiceDialog - - This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can - select one or more of them. +This dialog shows a list of choices, plus OK and (optionally) Cancel. The user +can select one or more of them. */