From d18d9f6047a08fce5b82e7dc647bec348c2aa3d3 Mon Sep 17 00:00:00 2001 From: Bryan Petty Date: Tue, 8 Apr 2008 05:34:11 +0000 Subject: [PATCH] Finished initial review of [cl*-cm*] interface headers. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53086 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/clipbrd.h | 159 +++++++++------- interface/clntdata.h | 76 ++++---- interface/clrpicker.h | 40 ++-- interface/cmdline.h | 418 +++++++++++++++++++++++++++------------- interface/cmdproc.h | 144 +++++++------- interface/cmndata.h | 421 +++++++++++++++++++++++++---------------- interface/datectrl.h | 2 +- interface/defs.h | 131 +++++++++++++ interface/filepicker.h | 4 +- interface/fontpicker.h | 2 +- 10 files changed, 908 insertions(+), 489 deletions(-) diff --git a/interface/clipbrd.h b/interface/clipbrd.h index 56cb32f0c0..b97503e504 100644 --- a/interface/clipbrd.h +++ b/interface/clipbrd.h @@ -6,63 +6,65 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + The backwards compatible access macro that returns the global clipboard + object pointer. +*/ +#define wxTheClipboard + /** @class wxClipboard @wxheader{clipbrd.h} - A class for manipulating the clipboard. Note that this is not compatible with - the - clipboard class from wxWidgets 1.xx, which has the same name but a different - implementation. + A class for manipulating the clipboard. - To use the clipboard, you call member functions of the global @b wxTheClipboard - object. + To use the clipboard, you call member functions of the global + ::wxTheClipboard object. - See also the @ref overview_wxdataobjectoverview for further information. + See the @ref overview_dataobject for further information. - Call wxClipboard::Open to get ownership of the clipboard. If this operation - returns @true, you - now own the clipboard. Call wxClipboard::SetData to put data - on the clipboard, or wxClipboard::GetData to - retrieve data from the clipboard. Call wxClipboard::Close to close - the clipboard and relinquish ownership. You should keep the clipboard open only - momentarily. + Call wxClipboard::Open() to get ownership of the clipboard. If this + operation returns @true, you now own the clipboard. Call + wxClipboard::SetData() to put data on the clipboard, or + wxClipboard::GetData() to retrieve data from the clipboard. Call + wxClipboard::Close() to close the clipboard and relinquish ownership. You + should keep the clipboard open only momentarily. For example: @code // Write some text to the clipboard - if (wxTheClipboard-Open()) - { - // This data objects are held by the clipboard, + if (wxTheClipboard->Open()) + { + // This data objects are held by the clipboard, // so do not delete them in the app. - wxTheClipboard-SetData( new wxTextDataObject("Some text") ); - wxTheClipboard-Close(); - } - - // Read some text - if (wxTheClipboard-Open()) - { - if (wxTheClipboard-IsSupported( wxDF_TEXT )) + wxTheClipboard->SetData( new wxTextDataObject("Some text") ); + wxTheClipboard->Close(); + } + + // Read some text + if (wxTheClipboard->Open()) + { + if (wxTheClipboard->IsSupported( wxDF_TEXT )) { - wxTextDataObject data; - wxTheClipboard-GetData( data ); - wxMessageBox( data.GetText() ); - } - wxTheClipboard-Close(); - } + wxTextDataObject data; + wxTheClipboard->GetData( data ); + wxMessageBox( data.GetText() ); + } + wxTheClipboard->Close(); + } @endcode @library{wxcore} @category{dnd} - @see @ref overview_wxdndoverview, wxDataObject + @see @ref overview_dnd, @ref overview_dataobject, wxDataObject */ class wxClipboard : public wxObject { public: /** - Constructor. + Default constructor. */ wxClipboard(); @@ -72,38 +74,42 @@ public: ~wxClipboard(); /** - Call this function to add the data object to the clipboard. You may call - this function repeatedly after having cleared the clipboard using Clear(). - After this function has been called, the clipboard owns the data, so do not - delete - the data explicitly. + Call this function to add the data object to the clipboard. You may + call this function repeatedly after having cleared the clipboard using + Clear(). + + After this function has been called, the clipboard owns the data, so do + not delete the data explicitly. @see SetData() */ bool AddData(wxDataObject* data); /** - Clears the global clipboard object and the system's clipboard if possible. + Clears the global clipboard object and the system's clipboard if + possible. */ void Clear(); /** - Call this function to close the clipboard, having opened it with Open(). + Call this function to close the clipboard, having opened it with + Open(). */ void Close(); /** Flushes the clipboard: this means that the data which is currently on - clipboard will stay available even after the application exits (possibly - eating memory), otherwise the clipboard will be emptied on exit. - Returns @false if the operation is unsuccessful for any reason. + clipboard will stay available even after the application exits + (possibly eating memory), otherwise the clipboard will be emptied on + exit. + + @returns @false if the operation is unsuccessful for any reason. */ bool Flush(); /** - Call this function to fill @a data with data on the clipboard, if available in - the required - format. Returns @true on success. + Call this function to fill @a data with data on the clipboard, if + available in the required format. Returns @true on success. */ bool GetData(wxDataObject& data); @@ -113,34 +119,41 @@ public: bool IsOpened() const; /** - Returns @true if there is data which matches the data format of the given data - object currently @b available (IsSupported sounds like a misnomer, FIXME: better deprecate this name?) on the clipboard. + Returns @true if there is data which matches the data format of the + given data object currently @b available on the clipboard. + + @todo The name of this function is misleading. This should be renamed + to something that more accurately indicates what it does. */ bool IsSupported(const wxDataFormat& format); /** - Returns @true if we are using the primary selection, @false if clipboard - one. - See @ref useprimary() UsePrimarySelection for more information. + Returns @true if we are using the primary selection, @false if + clipboard one. + + @see UsePrimarySelection() */ bool IsUsingPrimarySelection() const; /** - Call this function to open the clipboard before calling SetData() - and GetData(). - Call Close() when you have finished with the clipboard. You - should keep the clipboard open for only a very short time. - Returns @true on success. This should be tested (as in the sample shown above). + Call this function to open the clipboard before calling SetData() and + GetData(). + + Call Close() when you have finished with the clipboard. You should keep + the clipboard open for only a very short time. + + @returns @true on success. This should be tested (as in the sample + shown above). */ bool Open(); /** - Call this function to set the data object to the clipboard. This function will - clear all previous contents in the clipboard, so calling it several times - does not make any sense. - After this function has been called, the clipboard owns the data, so do not - delete - the data explicitly. + Call this function to set the data object to the clipboard. This + function will clear all previous contents in the clipboard, so calling + it several times does not make any sense. + + After this function has been called, the clipboard owns the data, so do + not delete the data explicitly. @see AddData() */ @@ -148,16 +161,18 @@ public: /** On platforms supporting it (all X11-based ports), wxClipboard uses the - CLIPBOARD X11 selection by default. When this function is called with @true - argument, all subsequent clipboard operations will use PRIMARY selection until - this function is called again with @false. - On the other platforms, there is no PRIMARY selection and so all clipboard - operations will fail. This allows to implement the standard X11 handling of the - clipboard which consists in copying data to the CLIPBOARD selection only when - the user explicitly requests it (i.e. by selection @c "Copy" menu - command) but putting the currently selected text into the PRIMARY selection - automatically, without overwriting the normal clipboard contents with the - currently selected text on the other platforms. + CLIPBOARD X11 selection by default. When this function is called with + @true, all subsequent clipboard operations will use PRIMARY selection + until this function is called again with @false. + + On the other platforms, there is no PRIMARY selection and so all + clipboard operations will fail. This allows to implement the standard + X11 handling of the clipboard which consists in copying data to the + CLIPBOARD selection only when the user explicitly requests it (i.e. by + selecting the "Copy" menu command) but putting the currently selected + text into the PRIMARY selection automatically, without overwriting the + normal clipboard contents with the currently selected text on the other + platforms. */ void UsePrimarySelection(bool primary = true); }; diff --git a/interface/clntdata.h b/interface/clntdata.h index d47c225c99..62d7a86429 100644 --- a/interface/clntdata.h +++ b/interface/clntdata.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: clntdata.h -// Purpose: interface of wxClientDataContainer +// Purpose: interface of wxClientData[Container] and wxStringClientData // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -12,17 +12,16 @@ This class is a mixin that provides storage and management of "client data." This data can either be of type void - in which case the data - @e container does not take care of freeing the data again - or it is of type wxClientData or its derivatives. In that case the - container will free the memory itself later. - Note that you @e must not assign both void data and data - derived from the wxClientData class to a container. + @e container does not take care of freeing the data again or it is of + type wxClientData or its derivatives. In that case the container will free + the memory itself later. Note that you @e must not assign both void data + and data derived from the wxClientData class to a container. - NOTE: This functionality is currently duplicated in wxEvtHandler in - order to avoid having more than one vtable in that class hierarchy. + @note This functionality is currently duplicated in wxEvtHandler in order + to avoid having more than one vtable in that class hierarchy. @library{wxbase} - @category{FIXME} + @category{containers} @see wxEvtHandler, wxClientData */ @@ -30,12 +29,12 @@ class wxClientDataContainer { public: /** - + Default constructor. */ wxClientDataContainer(); /** - + Destructor. */ ~wxClientDataContainer(); @@ -66,33 +65,30 @@ public: @class wxClientData @wxheader{clntdata.h} - All classes deriving from wxEvtHandler - (such as all controls and wxApp) - can hold arbitrary data which is here referred to as "client data". - This is useful e.g. for scripting languages which need to handle - shadow objects for most of wxWidgets' classes and which store - a handle to such a shadow class as client data in that class. - This data can either be of type void - in which case the data - @e container does not take care of freeing the data again - or it is of type wxClientData or its derivatives. In that case the - container (e.g. a control) will free the memory itself later. - Note that you @e must not assign both void data and data - derived from the wxClientData class to a container. - - Some controls can hold various items and these controls can - additionally hold client data for each item. This is the case for - wxChoice, wxComboBox - and wxListBox. wxTreeCtrl - has a specialized class wxTreeItemData - for each item in the tree. - - If you want to add client data to your own classes, you may - use the mix-in class wxClientDataContainer. + All classes deriving from wxEvtHandler (such as all controls and wxApp) can + hold arbitrary data which is here referred to as "client data". This is + useful e.g. for scripting languages which need to handle shadow objects for + most of wxWidgets' classes and which store a handle to such a shadow class + as client data in that class. This data can either be of type void - in + which case the data @e container does not take care of freeing the data + again or it is of type wxClientData or its derivatives. In that case the + container (e.g. a control) will free the memory itself later. Note that you + @e must not assign both void data and data derived from the wxClientData + class to a container. + + Some controls can hold various items and these controls can additionally + hold client data for each item. This is the case for wxChoice, wxComboBox + and wxListBox. wxTreeCtrl has a specialized class wxTreeItemData for each + item in the tree. + + If you want to add client data to your own classes, you may use the mix-in + class wxClientDataContainer. @library{wxbase} - @category{FIXME} + @category{containers} - @see wxEvtHandler, wxTreeItemData, wxStringClientData, wxClientDataContainer + @see wxEvtHandler, wxTreeItemData, wxStringClientData, + wxClientDataContainer */ class wxClientData { @@ -117,18 +113,20 @@ public: Predefined client data class for holding a string. @library{wxbase} - @category{FIXME} + @category{containers} */ class wxStringClientData : public wxClientData { public: - //@{ /** - Create client data with string. + Default constructor. */ wxStringClientData(); + + /** + Create client data with string. + */ wxStringClientData(const wxString& data); - //@} /** Get string client data. diff --git a/interface/clrpicker.h b/interface/clrpicker.h index 32a89c6af8..908e953a7b 100644 --- a/interface/clrpicker.h +++ b/interface/clrpicker.h @@ -10,12 +10,11 @@ @class wxColourPickerCtrl @wxheader{clrpicker.h} - This control allows the user to select a colour. The generic implementation is - a button which brings up a wxColourDialog when clicked. Native implementation - may differ but this is usually a (small) widget which give access to the - colour-chooser - dialog. - It is only available if @c wxUSE_COLOURPICKERCTRL is set to 1 (the default). + This control allows the user to select a colour. The generic implementation + is a button which brings up a wxColourDialog when clicked. Native + implementation may differ but this is usually a (small) widget which give + access to the colour-chooser dialog. It is only available if + @c wxUSE_COLOURPICKERCTRL is set to 1 (the default). @beginStyleTable @style{wxCLRP_DEFAULT_STYLE} @@ -31,9 +30,17 @@ (instead of no label at all). @endStyleTable + @beginEventTable{wxColourPickerEvent} + @event{EVT_COLOURPICKER_CHANGED(id, func)} + The user changed the colour selected in the control either using the + button or using text control (see @c wxCLRP_USE_TEXTCTRL; note that + in this case the event is fired only if the user’s input is valid, + i.e. recognizable). + @endEventTable + @library{wxcore} - @category{miscpickers} - @appearance{colourpickerctrl.png} + @category{pickers} + @see wxColourDialog, wxColourPickerEvent */ @@ -41,8 +48,7 @@ class wxColourPickerCtrl : public wxPickerBase { public: /** - Initializes the object and calls Create() with - all the parameters. + Initializes the object and calls Create() with all the parameters. */ wxColourPickerCtrl(wxWindow* parent, wxWindowID id, const wxColour& colour = wxBLACK, @@ -53,6 +59,8 @@ public: const wxString& name = "colourpickerctrl"); /** + Creates a colour picker with the given arguments. + @param parent Parent window, must not be non-@NULL. @param id @@ -88,7 +96,7 @@ public: //@{ /** - Sets the currently selected colour. See wxColour::Set. + Sets the currently selected colour. See wxColour::Set(). */ void SetColour(const wxColour& col); void SetColour(const wxString& colname); @@ -101,11 +109,15 @@ public: @class wxColourPickerEvent @wxheader{clrpicker.h} - This event class is used for the events generated by - wxColourPickerCtrl. + This event class is used for the events generated by wxColourPickerCtrl. + + @beginEventTable{wxColourPickerEvent} + @event{EVT_COLOURPICKER_CHANGED(id, func)} + Generated whenever the selected colour changes. + @endEventTable @library{wxcore} - @category{FIXME} + @category{events} @see wxColourPickerCtrl */ diff --git a/interface/cmdline.h b/interface/cmdline.h index 110364bb6f..11d7b27d75 100644 --- a/interface/cmdline.h +++ b/interface/cmdline.h @@ -6,6 +6,84 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + wxCmdLineEntryDesc::flags field is a combination of these bit masks. + + Notice that by default (i.e. if flags are just 0), options are optional + (sic) and each call to wxCmdLineEntryDesc::AddParam() allows one more + parameter - this may be changed by giving non-default flags to it, i.e. use + wxCMD_LINE_OPTION_MANDATORY to require that the option is given and + wxCMD_LINE_PARAM_OPTIONAL to make a parameter optional. Also, + wxCMD_LINE_PARAM_MULTIPLE may be specified if the programs accepts a + variable number of parameters - but it only can be given for the last + parameter in the command line description. If you use this flag, you will + probably need to use wxCmdLineEntryDesc::GetParamCount() to retrieve the + number of parameters effectively specified after calling + wxCmdLineEntryDesc::Parse(). + + wxCMD_LINE_NEEDS_SEPARATOR can be specified to require a separator (either + a colon, an equal sign or white space) between the option name and its + value. By default, no separator is required. +*/ +enum +{ + wxCMD_LINE_OPTION_MANDATORY = 0x01, ///< This option must be given. + wxCMD_LINE_PARAM_OPTIONAL = 0x02, ///< The parameter may be omitted. + wxCMD_LINE_PARAM_MULTIPLE = 0x04, ///< The parameter may be repeated. + wxCMD_LINE_OPTION_HELP = 0x08, ///< This option is a help request. + wxCMD_LINE_NEEDS_SEPARATOR = 0x10 ///< Must have a separator before the value. +}; + +/** + The possible values of wxCmdLineEntryDesc::type which specifies the type of + the value accepted by an option. +*/ +enum wxCmdLineParamType +{ + wxCMD_LINE_VAL_STRING, + wxCMD_LINE_VAL_NUMBER, + wxCMD_LINE_VAL_DATE, + wxCMD_LINE_VAL_DOUBLE, + wxCMD_LINE_VAL_NONE +}; + +/** + The type of a command line entity used for wxCmdLineEntryDesc::kind. +*/ +enum wxCmdLineEntryType +{ + wxCMD_LINE_SWITCH, + wxCMD_LINE_OPTION, + wxCMD_LINE_PARAM, + wxCMD_LINE_NONE ///< Use this to terminate the list. +}; + +/** + The structure wxCmdLineEntryDesc is used to describe the one command line + switch, option or parameter. An array of such structures should be passed + to wxCmdLineParser::SetDesc(). Also, the meanings of parameters of the + wxCmdLineParser::AddXXX() functions are the same as of the corresponding + fields in this structure. + + The field @c shortName is the usual, short, name of the switch or the + option. @c longName is the corresponding long name or empty if the option + has no long name. Both of these fields are unused for the parameters. Both + the short and long option names can contain only letters, digits and the + underscores. + + @c description is used by the wxCmdLineEntryDesc::Usage() method to + construct a help message explaining the syntax of the program. +*/ +struct wxCmdLineEntryDesc +{ + wxCmdLineEntryType kind; + const char *shortName; + const char *longName; + const char *description; + wxCmdLineParamType type; + int flags; +}; + /** @class wxCmdLineParser @wxheader{cmdline.h} @@ -22,62 +100,168 @@ To use it you should follow these steps: - -# @ref wxCmdLineParser::construction construct an object of this class - giving it the command line to parse and optionally its description or use - @c AddXXX() functions later - -# call @c Parse() - -# use @c Found() to retrieve the results + -# @ref cmdlineparser_construction "Construct" an object of this class + giving it the command line to parse and optionally its description or + use the @c AddXXX() functions later. + -# Call Parse(). + -# Use Found() to retrieve the results. In the documentation below the following terminology is used: - - @e switch - This is a boolean option which can be given or not, but - which doesn't have any value. We use the word switch to distinguish such boolean - options from more generic options like those described below. For example, - @c -v might be a switch meaning "enable verbose mode". - - @e option - Option for us here is something which comes with a value 0 - unlike a switch. For example, @c -o:filename might be an option which allows - to specify the name of the output file. - - @e parameter - This is a required program argument. + - @b switch: This is a boolean option which can be given or not, but which + doesn't have any value. We use the word switch to distinguish + such boolean options from more generic options like those + described below. For example, @c "-v" might be a switch + meaning "enable verbose mode". + - @b option: Option for us here is something which comes with a value 0 + unlike a switch. For example, @c -o:filename might be an + option for specifing the name of the output file. + - @b parameter: This is a required program argument. + + + @section cmdlineparser_construction Construction + + Before Parse() can be called, the command line parser object must have the + command line to parse and also the rules saying which switches, options and + parameters are valid - this is called command line description in what + follows. + + You have complete freedom of choice as to when specify the required + information, the only restriction is that it must be done before calling + Parse(). + + To specify the command line to parse you may use either one of constructors + accepting it (wxCmdLineParser(int, char**) or + wxCmdLineParser(const wxString&) usually) or, if you use the default + constructor, you can do it later by calling SetCmdLine(). + + The same holds for command line description: it can be specified either in + the constructor (with or without the command line itself) or constructed + later using either SetDesc() or combination of AddSwitch(), AddOption() and + AddParam() methods. + Using constructors or SetDesc() uses a (usually const static) table + containing the command line description. If you want to decide which + options to accept during the run-time, using one of the AddXXX() functions + above might be preferable. + + + @section cmdlineparser_customization Customization + + wxCmdLineParser has several global options which may be changed by the + application. All of the functions described in this section should be + called before Parse(). + + First global option is the support for long (also known as GNU-style) + options. The long options are the ones which start with two dashes and look + like "--verbose", i.e. they generally are complete words and not some + abbreviations of them. As long options are used by more and more + applications, they are enabled by default, but may be disabled with + DisableLongOptions(). + + Another global option is the set of characters which may be used to start + an option (otherwise, the word on the command line is assumed to be a + parameter). Under Unix, "-" is always used, but Windows has at least two + common choices for this: "-" and "/". Some programs also use "+". The + default is to use what suits most the current platform, but may be changed + with SetSwitchChars() method. + + Finally, SetLogo() can be used to show some application-specific text + before the explanation given by Usage() function. + + + @section cmdlineparser_parsing Parsing the Command Line + + After the command line description was constructed and the desired options + were set, you can finally call Parse() method. It returns 0 if the command + line was correct and was parsed, -1 if the help option was specified (this + is a separate case as, normally, the program will terminate after this) or + a positive number if there was an error during the command line parsing. + + In the latter case, the appropriate error message and usage information are + logged by wxCmdLineParser itself using the standard wxWidgets logging + functions. + + + @section cmdlineparser_results Getting Results + + After calling Parse() (and if it returned 0), you may access the results of + parsing using one of overloaded Found() methods. + + For a simple switch, you will simply call Found to determine if the switch + was given or not, for an option or a parameter, you will call a version of + Found() which also returns the associated value in the provided variable. + All Found() functions return true if the switch or option were found in the + command line or false if they were not specified. @library{wxbase} @category{appmanagement} - @see wxApp::argc and wxApp::argv, console sample + @see wxApp::argc, wxApp::argv, @ref page_samples_console "Console Sample" */ class wxCmdLineParser { public: - //@{ /** - Specifies both the command line (in Windows format) and the - @ref setdesc() "command line description". + Default constructor, you must use SetCmdLine() later. */ wxCmdLineParser(); + + //@{ + /** + Constructor which specifies the command line to parse. This is the + traditional (Unix) command line format. The parameters @a argc and + @a argv have the same meaning as the typical @c main() function. + + The second overloaded constructor is only available in Unicode build. + The first one is available in both ANSI and Unicode modes because under + some platforms the command line arguments are passed as ASCII strings + even to Unicode programs. + */ wxCmdLineParser(int argc, char** argv); wxCmdLineParser(int argc, wchar_t** argv); + //@} + + /** + Constructor which specify the command line to parse in Windows format. + The parameter cmdline has the same meaning as the corresponding + parameter of @c WinMain(). + */ wxCmdLineParser(const wxString& cmdline); + + /** + Specifies the @ref SetDesc() "command line description" but not the + command line. You must use SetCmdLine() later. + */ wxCmdLineParser(const wxCmdLineEntryDesc* desc); + + /** + Specifies both the command line (in Unix format) and the + @ref SetDesc() "command line description". + */ wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc, char** argv); + + /** + Specifies both the command line (in Windows format) and the + @ref SetDesc() "command line description". + */ wxCmdLineParser(const wxCmdLineEntryDesc* desc, const wxString& cmdline); - //@} /** Frees resources allocated by the object. - @note destructor is not virtual, don't use this class polymorphically. + + @note This destructor is not virtual, don't use this class + polymorphically. */ ~wxCmdLineParser(); /** - Add an option @a name with an optional long name @a lng (no long name if - it is empty, which is default) taking a value of the given type (string by - default) to the command line description. + Add an option @a name with an optional long name @a lng (no long name + if it is empty, which is default) taking a value of the given type + (string by default) to the command line description. */ void AddOption(const wxString& name, const wxString& lng = wxEmptyString, @@ -93,9 +277,9 @@ public: int flags = 0); /** - Add a switch @a name with an optional long name @a lng (no long name if it - is empty, which is default), description @a desc and flags @a flags to the - command line description. + Add a switch @a name with an optional long name @a lng (no long name if + it is empty, which is default), description @a desc and flags @a flags + to the command line description. */ void AddSwitch(const wxString& name, const wxString& lng = wxEmptyString, @@ -110,140 +294,86 @@ public: bool AreLongOptionsEnabled() const; /** - Before Parse() can be called, the command line - parser object must have the command line to parse and also the rules saying - which switches, options and parameters are valid - this is called command line - description in what follows. - You have complete freedom of choice as to when specify the required information, - the only restriction is that it must be done before calling - Parse(). - To specify the command line to parse you may use either one of constructors - accepting it (@c wxCmdLineParser(argc, argv) or @c wxCmdLineParser(const - wxString) usually) - or, if you use the default constructor, you can do it later by calling - SetCmdLine(). - The same holds for command line description: it can be specified either in - the @ref wxcmdlineparserctor() constructor (with or without - the command line itself) or constructed later using either - SetDesc() or combination of - AddSwitch(), - AddOption() and - AddParam() methods. - Using constructors or SetDesc() uses a (usually - @c const static) table containing the command line description. If you want - to decide which options to accept during the run-time, using one of the - @c AddXXX() functions above might be preferable. + Breaks down the string containing the full command line in words. The + words are separated by whitespace. The quotes can be used in the input + string to quote the white space and the back slashes can be used to + quote the quotes. */ - + static wxArrayString ConvertStringToArgs(const wxChar cmdline); /** - Breaks down the string containing the full command line in words. The words are - separated by whitespace. The quotes can be used in the input string to quote - the white space and the back slashes can be used to quote the quotes. + Identical to EnableLongOptions(@false). */ - static wxArrayString ConvertStringToArgs(const wxChar cmdline); + void DisableLongOptions(); /** - wxCmdLineParser has several global options which may be changed by the - application. All of the functions described in this section should be called - before Parse(). - First global option is the support for long (also known as GNU-style) options. - The long options are the ones which start with two dashes (@c "--") and look - like this: @c --verbose, i.e. they generally are complete words and not some - abbreviations of them. As long options are used by more and more applications, - they are enabled by default, but may be disabled with - DisableLongOptions(). - Another global option is the set of characters which may be used to start an - option (otherwise, the word on the command line is assumed to be a parameter). - Under Unix, @c '-' is always used, but Windows has at least two common - choices for this: @c '-' and @c '/'. Some programs also use @c '+'. - The default is to use what suits most the current platform, but may be changed - with SetSwitchChars() method. - Finally, SetLogo() can be used to show some - application-specific text before the explanation given by - Usage() function. + Enable or disable support for the long options. + + As long options are not (yet) POSIX-compliant, this option allows to + disable them. + + @see @ref cmdlineparser_customization and AreLongOptionsEnabled() */ + void EnableLongOptions(bool enable = true); + /** + Returns @true if the given switch was found, @false otherwise. + */ + bool Found(const wxString& name) const; /** - Identical to @ref enablelongoptions() EnableLongOptions(@false). + Returns true if an option taking a string value was found and stores + the value in the provided pointer (which should not be @NULL). */ - void DisableLongOptions(); + bool Found(const wxString& name, wxString* value) const; /** - Enable or disable support for the long options. - As long options are not (yet) POSIX-compliant, this option allows to disable - them. + Returns @true if an option taking an integer value was found and stores + the value in the provided pointer (which should not be @NULL). + */ + bool Found(const wxString& name, long* value) const; - @see Customization() and AreLongOptionsEnabled() + /** + Returns @true if an option taking a float value was found and stores + the value in the provided pointer (which should not be @NULL). */ - void EnableLongOptions(bool enable = true); + bool Found(const wxString& name, double* value) const; - //@{ /** Returns @true if an option taking a date value was found and stores the value in the provided pointer (which should not be @NULL). */ - bool Found(const wxString& name) const; - bool Found(const wxString& name, wxString* value) const; - bool Found(const wxString& name, long* value) const; - bool Found(const wxString& name, double* value) const; bool Found(const wxString& name, wxDateTime* value) const; - //@} /** Returns the value of Nth parameter (as string only). */ - wxString GetParam(size_t n = 0u) const; + wxString GetParam(size_t n = 0) const; /** - Returns the number of parameters found. This function makes sense mostly if you - had used @c wxCMD_LINE_PARAM_MULTIPLE flag. + Returns the number of parameters found. This function makes sense + mostly if you had used @c wxCMD_LINE_PARAM_MULTIPLE flag. */ size_t GetParamCount() const; - /** - After calling Parse() (and if it returned 0), - you may access the results of parsing using one of overloaded @c Found() - methods. - For a simple switch, you will simply call - Found() to determine if the switch was given - or not, for an option or a parameter, you will call a version of @c Found() - which also returns the associated value in the provided variable. All - @c Found() functions return @true if the switch or option were found in the - command line or @false if they were not specified. - */ - - /** Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help" - option was encountered and the help message was given or a positive value if a - syntax error occurred. + option was encountered and the help message was given or a positive + value if a syntax error occurred. @param giveUsage - If @true (default), the usage message is given if a - syntax error was encountered while parsing the command line or if help was - requested. If @false, only error messages about possible syntax errors - are given, use Usage to show the usage message - from the caller if needed. + If @true (default), the usage message is given if a syntax error + was encountered while parsing the command line or if help was + requested. If @false, only error messages about possible syntax + errors are given, use Usage to show the usage message from the + caller if needed. */ int Parse(bool giveUsage = true); - /** - After the command line description was constructed and the desired options were - set, you can finally call Parse() method. - It returns 0 if the command line was correct and was parsed, -1 if the help - option was specified (this is a separate case as, normally, the program will - terminate after this) or a positive number if there was an error during the - command line parsing. - In the latter case, the appropriate error message and usage information are - logged by wxCmdLineParser itself using the standard wxWidgets logging functions. - */ - - //@{ /** - Set command line to parse after using one of the constructors which don't do it. + Set the command line to parse after using one of the constructors which + don't do it. */ void SetCmdLine(int argc, char** argv); void SetCmdLine(int argc, wchar_t** argv); @@ -251,28 +381,52 @@ public: //@} /** - Construct the command line description - Take the command line description from the wxCMD_LINE_NONE terminated table. + Constructs the command line description. + + Take the command line description from the wxCMD_LINE_NONE terminated + table. + Example of usage: + + @code + static const wxCmdLineEntryDesc cmdLineDesc[] = + { + { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" }, + { wxCMD_LINE_SWITCH, "q", "quiet", "be quiet" }, + + { wxCMD_LINE_OPTION, "o", "output", "output file" }, + { wxCMD_LINE_OPTION, "i", "input", "input dir" }, + { wxCMD_LINE_OPTION, "s", "size", "output block size", wxCMD_LINE_VAL_NUMBER }, + { wxCMD_LINE_OPTION, "d", "date", "output file date", wxCMD_LINE_VAL_DATE }, + + { wxCMD_LINE_PARAM, NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE }, + + { wxCMD_LINE_NONE } + }; + + wxCmdLineParser parser; + + parser.SetDesc(cmdLineDesc); + @endcode */ void SetDesc(const wxCmdLineEntryDesc* desc); /** - @a logo is some extra text which will be shown by - Usage() method. + The @a logo is some extra text which will be shown by Usage() method. */ void SetLogo(const wxString& logo); /** - @a switchChars contains all characters with which an option or switch may - start. Default is @c "-" for Unix, @c "-/" for Windows. + @a switchChars contains all characters with which an option or switch + may start. Default is @c "-" for Unix, @c "-/" for Windows. */ void SetSwitchChars(const wxString& switchChars); /** - Give the standard usage message describing all program options. It will use the - options and parameters descriptions specified earlier, so the resulting message - will not be helpful to the user unless the descriptions were indeed specified. + Give the standard usage message describing all program options. It will + use the options and parameters descriptions specified earlier, so the + resulting message will not be helpful to the user unless the + descriptions were indeed specified. @see SetLogo() */ diff --git a/interface/cmdproc.h b/interface/cmdproc.h index 21b5adc151..76c0577b07 100644 --- a/interface/cmdproc.h +++ b/interface/cmdproc.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: cmdproc.h -// Purpose: interface of wxCommand +// Purpose: interface of wxCommandProcessor and wxCommand // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -10,15 +10,15 @@ @class wxCommand @wxheader{cmdproc.h} - wxCommand is a base class for modelling an application command, - which is an action usually performed by selecting a menu item, pressing - a toolbar button or any other means provided by the application to - change the data or view. + wxCommand is a base class for modelling an application command, which is an + action usually performed by selecting a menu item, pressing a toolbar + button or any other means provided by the application to change the data or + view. @library{wxcore} - @category{FIXME} + @category{docview} - @see Overview() + @see @ref overview_docview_wxcommand */ class wxCommand : public wxObject { @@ -26,12 +26,15 @@ public: /** Constructor. wxCommand is an abstract class, so you will need to derive a new class and call this constructor from your own constructor. - @a canUndo tells the command processor whether this command is undo-able. You - can achieve the same functionality by overriding the CanUndo member function - (if for example - the criteria for undoability is context-dependent). - @a name must be supplied for the command processor to display the command name - in the application's edit menu. + + @param canUndo + Tells the command processor whether this command is undo-able. You + can achieve the same functionality by overriding the CanUndo() + member function (if for example the criteria for undoability is + context-dependent). + @param name + Must be supplied for the command processor to display the command + name in the application's edit menu. */ wxCommand(bool canUndo = false, const wxString& name = NULL); @@ -46,10 +49,13 @@ public: bool CanUndo(); /** - Override this member function to execute the appropriate action when called. - Return @true to indicate that the action has taken place, @false otherwise. - Returning @false will indicate to the command processor that the action is - not undoable and should not be added to the command history. + Override this member function to execute the appropriate action when + called. + + @returns @true to indicate that the action has taken place, @false + otherwise. Returning @false will indicate to the command + processor that the action is not undoable and should not be + added to the command history. */ bool Do(); @@ -60,21 +66,25 @@ public: /** Override this member function to un-execute a previous Do. - Return @true to indicate that the action has taken place, @false otherwise. - Returning @false will indicate to the command processor that the action is - not redoable and no change should be made to the command history. - How you implement this command is totally application dependent, but typical - strategies include: - Perform an inverse operation on the last modified piece of - data in the document. When redone, a copy of data stored in command - is pasted back or some operation reapplied. This relies on the fact that - you know the ordering of Undos; the user can never Undo at an arbitrary position - in the command history. - Restore the entire document state (perhaps using document transactioning). - Potentially very inefficient, but possibly easier to code if the user interface - and data are complex, and an 'inverse execute' operation is hard to write. - The docview sample uses the first method, to remove or restore segments - in the drawing. + + How you implement this command is totally application dependent, but + typical strategies include: + + - Perform an inverse operation on the last modified piece of data in + the document. When redone, a copy of data stored in command is pasted + back or some operation reapplied. This relies on the fact that you + know the ordering of Undos; the user can never Undo at an arbitrary + position in the command history. + - Restore the entire document state (perhaps using document + transactioning). Potentially very inefficient, but possibly easier to + code if the user interface and data are complex, and an "inverse + execute" operation is hard to write. The docview sample uses the + first method, to remove or restore segments in the drawing. + + @returns @true to indicate that the action has taken place, @false + otherwise. Returning @false will indicate to the command + processor that the action is not redoable and no change should + be made to the command history. */ bool Undo(); }; @@ -85,24 +95,25 @@ public: @class wxCommandProcessor @wxheader{cmdproc.h} - wxCommandProcessor is a class that maintains a history of wxCommands, - with undo/redo functionality built-in. Derive a new class from this - if you want different behaviour. + wxCommandProcessor is a class that maintains a history of wxCommands, with + undo/redo functionality built-in. Derive a new class from this if you want + different behaviour. @library{wxcore} - @category{FIXME} + @category{docview} - @see @ref overview_wxcommandprocessoroverview "wxCommandProcessor overview", - wxCommand + @see @ref overview_docview_wxcommandproc, wxCommand */ class wxCommandProcessor : public wxObject { public: /** Constructor. - @a maxCommands may be set to a positive integer to limit the number of - commands stored to it, otherwise (and by default) the list of commands can grow - arbitrarily. + + @param maxCommands + May be set to a positive integer to limit the number of commands + stored to it, otherwise (and by default) the list of commands can + grow arbitrarily. */ wxCommandProcessor(int maxCommands = -1); @@ -112,20 +123,21 @@ public: ~wxCommandProcessor(); /** - Returns @true if the currently-active command can be undone, @false otherwise. + Returns @true if the currently-active command can be undone, @false + otherwise. */ virtual bool CanUndo(); /** - Deletes all commands in the list and sets the current command pointer to @c - @NULL. + Deletes all commands in the list and sets the current command pointer + to @NULL. */ virtual void ClearCommands(); /** Returns the list of commands. */ - wxList GetCommands() const; + wxList& GetCommands() const; /** Returns the edit menu associated with the command processor. @@ -133,14 +145,15 @@ public: wxMenu* GetEditMenu() const; /** - Returns the maximum number of commands that the command processor stores. + Returns the maximum number of commands that the command processor + stores. */ int GetMaxCommands() const; /** Returns the string that will be appended to the Redo menu item. */ - const wxString GetRedoAccelerator() const; + const wxString& GetRedoAccelerator() const; /** Returns the string that will be shown for the redo menu item. @@ -150,7 +163,7 @@ public: /** Returns the string that will be appended to the Undo menu item. */ - const wxString GetUndoAccelerator() const; + const wxString& GetUndoAccelerator() const; /** Returns the string that will be shown for the undo menu item. @@ -166,21 +179,20 @@ public: /** Returns a boolean value that indicates if changes have been made since - the last save operation. This only works if - MarkAsSaved() - is called whenever the project is saved. + the last save operation. This only works if MarkAsSaved() is called + whenever the project is saved. */ virtual bool IsDirty(); /** - You must call this method whenever the project is saved if you plan to use - IsDirty(). + You must call this method whenever the project is saved if you plan to + use IsDirty(). */ virtual void MarkAsSaved(); /** - Executes (redoes) the current command (the command that has just been undone if - any). + Executes (redoes) the current command (the command that has just been + undone if any). */ virtual bool Redo(); @@ -193,8 +205,8 @@ public: void SetEditMenu(wxMenu* menu); /** - Sets the menu labels according to the currently set menu and the current - command state. + Sets the menu labels according to the currently set menu and the + current command state. */ void SetMenuStrings(); @@ -210,18 +222,20 @@ public: /** Submits a new command to the command processor. The command processor - calls wxCommand::Do to execute the command; if it succeeds, the command - is stored in the history list, and the associated edit menu (if any) updated - appropriately. If it fails, the command is deleted - immediately. Once Submit has been called, the passed command should not - be deleted directly by the application. - @a storeIt indicates whether the successful command should be stored - in the history list. + calls wxCommand::Do() to execute the command; if it succeeds, the + command is stored in the history list, and the associated edit menu (if + any) updated appropriately. If it fails, the command is deleted + immediately. Once Submit() has been called, the passed command should + not be deleted directly by the application. + + @param storeIt + Indicates whether the successful command should be stored in the + history list. */ virtual bool Submit(wxCommand* command, bool storeIt = true); /** - Undoes the command just executed. + Undoes the last command executed. */ virtual bool Undo(); }; diff --git a/interface/cmndata.h b/interface/cmndata.h index 2ab3aeb250..70c26781d1 100644 --- a/interface/cmndata.h +++ b/interface/cmndata.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: cmndata.h -// Purpose: interface of wxFontData +// Purpose: interface of common wx*Data classes (font, colour, print) // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -10,86 +10,92 @@ @class wxFontData @wxheader{cmndata.h} - @ref overview_wxfontdialogoverview "wxFontDialog overview" - This class holds a variety of information related to font dialogs. @library{wxcore} - @category{FIXME} + @category{cmndlg} - @see Overview(), wxFont, wxFontDialog + @see @ref overview_cmndlg_font, wxFont, wxFontDialog */ class wxFontData : public wxObject { public: /** - Constructor. Initializes @e fontColour to black, @e showHelp to black, - @e allowSymbols to @true, @e enableEffects to @true, - @e minSize to 0 and @e maxSize to 0. + Constructor. Initializes @e fontColour to black, @e showHelp to @false, + @e allowSymbols to @true, @e enableEffects to @true, @e minSize to 0 + and @e maxSize to 0. */ wxFontData(); /** - Enables or disables 'effects' under MS Windows or generic only. This refers to - the - controls for manipulating colour, strikeout and underline properties. + Enables or disables "effects" under Windows or generic only. This + refers to the controls for manipulating colour, strikeout and underline + properties. + The default value is @true. */ void EnableEffects(bool enable); /** - Under MS Windows, returns a flag determining whether symbol fonts can be - selected. Has no - effect on other platforms. + Under Windows, returns a flag determining whether symbol fonts can be + selected. Has no effect on other platforms. + The default value is @true. */ bool GetAllowSymbols(); /** Gets the font chosen by the user if the user pressed OK - (wxFontDialog::ShowModal returned wxID_OK). + (wxFontDialog::ShowModal() returned wxID_OK). */ wxFont GetChosenFont(); /** Gets the colour associated with the font dialog. + The default value is black. */ - wxColour GetColour(); + wxColour& GetColour(); /** - Determines whether 'effects' are enabled under Windows. This refers to the - controls for manipulating colour, strikeout and underline properties. + Determines whether "effects" are enabled under Windows. This refers to + the controls for manipulating colour, strikeout and underline + properties. + The default value is @true. */ bool GetEnableEffects(); /** - Gets the font that will be initially used by the font dialog. This should have - previously been set by the application. + Gets the font that will be initially used by the font dialog. This + should have previously been set by the application. */ wxFont GetInitialFont(); /** Returns @true if the Help button will be shown (Windows only). + The default value is @false. */ bool GetShowHelp(); /** - Under MS Windows, determines whether symbol fonts can be selected. Has no + Under Windows, determines whether symbol fonts can be selected. Has no effect on other platforms. + The default value is @true. */ void SetAllowSymbols(bool allowSymbols); /** - Sets the font that will be returned to the user (for internal use only). + Sets the font that will be returned to the user (for internal use + only). */ void SetChosenFont(const wxFont& font); /** Sets the colour that will be used for the font foreground colour. + The default colour is black. */ void SetColour(const wxColour& colour); @@ -101,6 +107,7 @@ public: /** Sets the valid range for the font point size (Windows only). + The default is 0, 0 (unrestricted range). */ void SetRange(int min, int max); @@ -108,6 +115,7 @@ public: /** Determines whether the Help button will be displayed in the font dialog (Windows only). + The default value is @false. */ void SetShowHelp(bool showHelp); @@ -127,26 +135,31 @@ public: This class holds a variety of information related to wxPageSetupDialog. It contains a wxPrintData member which is used to hold basic printer - configuration data (as opposed to the - user-interface configuration settings stored by wxPageSetupDialogData). + configuration data (as opposed to the user-interface configuration settings + stored by wxPageSetupDialogData). @library{wxcore} @category{printing} - @see @ref overview_printingoverview "Printing framework overview", - wxPageSetupDialog + @see @ref overview_printing, wxPageSetupDialog */ class wxPageSetupDialogData : public wxObject { public: - //@{ /** - Construct an object from a print data object. + Default constructor. */ wxPageSetupDialogData(); + + /** + Copy constructor. + */ wxPageSetupDialogData(wxPageSetupDialogData& data); + + /** + Construct an object from a print data object. + */ wxPageSetupDialogData(wxPrintData& printData); - //@} /** Destructor. @@ -154,7 +167,7 @@ public: ~wxPageSetupDialogData(); /** - Enables or disables the 'Help' button (Windows only). + Enables or disables the "Help" button (Windows only). */ void EnableHelp(bool flag); @@ -174,21 +187,21 @@ public: void EnablePaper(bool flag); /** - Enables or disables the @b Printer button, which invokes a printer setup dialog. + Enables or disables the "Printer" button, which invokes a printer setup + dialog. */ void EnablePrinter(bool flag); /** - Returns @true if the dialog will simply return default printer information (such - as orientation) - instead of showing a dialog. Windows only. + Returns @true if the dialog will simply return default printer + information (such as orientation) instead of showing a dialog (Windows + only). */ bool GetDefaultInfo() const; /** - Returns @true if the page setup dialog will take its minimum margin values from - the currently - selected printer properties. Windows only. + Returns @true if the page setup dialog will take its minimum margin + values from the currently selected printer properties (Windows only). */ bool GetDefaultMinMargins() const; @@ -229,21 +242,20 @@ public: /** Returns the right (x) and bottom (y) minimum margins the user can enter - (Windows only). Units - are in millimetres + (Windows only). Units are in millimetres. */ wxPoint GetMinMarginBottomRight() const; /** - Returns the left (x) and top (y) minimum margins the user can enter (Windows - only). Units - are in millimetres + Returns the left (x) and top (y) minimum margins the user can enter + (Windows only). Units are in millimetres. */ wxPoint GetMinMarginTopLeft() const; /** Returns the paper id (stored in the internal wxPrintData object). - For further information, see wxPrintData::SetPaperId. + + @see wxPrintData::SetPaperId() */ wxPaperSize GetPaperId() const; @@ -253,29 +265,27 @@ public: wxSize GetPaperSize() const; /** - Returns a reference to the @ref overview_wxprintdata "print data" associated - with this object. + Returns a reference to the print data associated with this object. */ wxPrintData GetPrintData(); /** - Returns @true if the print data associated with the dialog data is valid. - This can return @false on Windows if the current printer is not set, for example. - On all other platforms, it returns @true. + Returns @true if the print data associated with the dialog data is + valid. This can return @false on Windows if the current printer is not + set, for example. On all other platforms, it returns @true. */ bool IsOk() const; /** - Pass @true if the dialog will simply return default printer information (such as - orientation) - instead of showing a dialog. Windows only. + Pass @true if the dialog will simply return default printer information + (such as orientation) instead of showing a dialog (Windows only). */ void SetDefaultInfo(bool flag); /** - Pass @true if the page setup dialog will take its minimum margin values from the - currently - selected printer properties. Windows only. Units are in millimetres + Pass @true if the page setup dialog will take its minimum margin values + from the currently selected printer properties (Windows only). Units + are in millimetres. */ void SetDefaultMinMargins(bool flag); @@ -290,45 +300,46 @@ public: void SetMarginTopLeft(const wxPoint& pt); /** - Sets the right (x) and bottom (y) minimum margins the user can enter (Windows - only). Units are - in millimetres. + Sets the right (x) and bottom (y) minimum margins the user can enter + (Windows only). Units are in millimetres. */ void SetMinMarginBottomRight(const wxPoint& pt); /** - Sets the left (x) and top (y) minimum margins the user can enter (Windows - only). Units are - in millimetres. + Sets the left (x) and top (y) minimum margins the user can enter + (Windows only). Units are in millimetres. */ void SetMinMarginTopLeft(const wxPoint& pt); /** - Sets the paper size id. For further information, see wxPrintData::SetPaperId. - Calling this function overrides the explicit paper dimensions passed in - SetPaperSize(). + Sets the paper size id. Calling this function overrides the explicit + paper dimensions passed in SetPaperSize(). + + @see wxPrintData::SetPaperId() */ void SetPaperId(wxPaperSize& id); /** - Sets the paper size in millimetres. If a corresponding paper id is found, it - will be set in the - internal wxPrintData object, otherwise the paper size overrides the paper id. + Sets the paper size in millimetres. If a corresponding paper id is + found, it will be set in the internal wxPrintData object, otherwise the + paper size overrides the paper id. */ void SetPaperSize(const wxSize& size); /** - Sets the @ref overview_wxprintdata "print data" associated with this object. + Sets the print data associated with this object. */ void SetPrintData(const wxPrintData& printData); - //@{ /** - Assigns page setup data to this object. + Assigns print data to this object. */ void operator =(const wxPrintData& data); + + /** + Assigns page setup data to this object. + */ void operator =(const wxPageSetupDialogData& data); - //@} }; @@ -340,18 +351,17 @@ public: This class holds a variety of information related to colour dialogs. @library{wxcore} - @category{FIXME} + @category{cmndlg} - @see wxColour, wxColourDialog, @ref overview_wxcolourdialogoverview - "wxColourDialog overview" + @see wxColour, wxColourDialog, @ref overview_cmndlg_colour */ class wxColourData : public wxObject { public: /** - Constructor. Initializes the custom colours to @c wxNullColour, - the @e data colour setting - to black, and the @e choose full setting to @true. + Constructor. Initializes the custom colours to @c wxNullColour, the + @e data colour setting to black, and the @e choose full setting to + @true. */ wxColourData(); @@ -361,46 +371,55 @@ public: ~wxColourData(); /** - Under Windows, determines whether the Windows colour dialog will display the - full dialog - with custom colour selection controls. Under PalmOS, determines whether colour - dialog - will display full rgb colour picker or only available palette indexer. - Has no meaning under other platforms. + Under Windows, determines whether the Windows colour dialog will + display the full dialog with custom colour selection controls. Under + PalmOS, determines whether colour dialog will display full rgb colour + picker or only available palette indexer. Has no meaning under other + platforms. + The default value is @true. */ bool GetChooseFull() const; /** Gets the current colour associated with the colour dialog. + The default colour is black. */ - wxColour GetColour() const; + wxColour& GetColour() const; /** - Gets the @e ith custom colour associated with the colour dialog. @a i should - be an integer between 0 and 15. - The default custom colours are invalid colours. + Returns custom colours associated with the colour dialog. + + @param i + An integer between 0 and 15, being any of the 15 custom colours + that the user has saved. The default custom colours are invalid + colours. */ - wxColour GetCustomColour(int i) const; + wxColour& GetCustomColour(int i) const; /** - Under Windows, tells the Windows colour dialog to display the full dialog - with custom colour selection controls. Under other platforms, has no effect. + Under Windows, tells the Windows colour dialog to display the full + dialog with custom colour selection controls. Under other platforms, + has no effect. + The default value is @true. */ void SetChooseFull(const bool flag); /** Sets the default colour for the colour dialog. + The default colour is black. */ void SetColour(const wxColour& colour); /** - Sets the @e ith custom colour for the colour dialog. @a i should - be an integer between 0 and 15. - The default custom colours are invalid colours. + Sets custom colours for the colour dialog. + + @param i + An integer between 0 and 15 for whatever custom colour you want to + set. The default custom colours are invalid colours. */ void SetCustomColour(int i, const wxColour& colour); @@ -412,32 +431,93 @@ public: +/** + Enumeration of various printer bin sources. + + @see wxPrintData::SetBin() +*/ +enum wxPrintBin +{ + wxPRINTBIN_DEFAULT, + + wxPRINTBIN_ONLYONE, + wxPRINTBIN_LOWER, + wxPRINTBIN_MIDDLE, + wxPRINTBIN_MANUAL, + wxPRINTBIN_ENVELOPE, + wxPRINTBIN_ENVMANUAL, + wxPRINTBIN_AUTO, + wxPRINTBIN_TRACTOR, + wxPRINTBIN_SMALLFMT, + wxPRINTBIN_LARGEFMT, + wxPRINTBIN_LARGECAPACITY, + wxPRINTBIN_CASSETTE, + wxPRINTBIN_FORMSOURCE, + + wxPRINTBIN_USER, +}; + /** @class wxPrintData @wxheader{cmndata.h} - This class holds a variety of information related to printers and - printer device contexts. This class is used to create a wxPrinterDC - and a wxPostScriptDC. It is also used as a data member of wxPrintDialogData - and wxPageSetupDialogData, as part of the mechanism for transferring data + This class holds a variety of information related to printers and printer + device contexts. This class is used to create a wxPrinterDC and a + wxPostScriptDC. It is also used as a data member of wxPrintDialogData and + wxPageSetupDialogData, as part of the mechanism for transferring data between the print dialogs and the application. + @remarks + + The following functions are specific to PostScript printing and have not + yet been documented: + + @code + const wxString& GetPrinterCommand() const ; + const wxString& GetPrinterOptions() const ; + const wxString& GetPreviewCommand() const ; + const wxString& GetFilename() const ; + const wxString& GetFontMetricPath() const ; + double GetPrinterScaleX() const ; + double GetPrinterScaleY() const ; + long GetPrinterTranslateX() const ; + long GetPrinterTranslateY() const ; + // wxPRINT_MODE_PREVIEW, wxPRINT_MODE_FILE, wxPRINT_MODE_PRINTER + wxPrintMode GetPrintMode() const ; + + void SetPrinterCommand(const wxString& command) ; + void SetPrinterOptions(const wxString& options) ; + void SetPreviewCommand(const wxString& command) ; + void SetFilename(const wxString& filename) ; + void SetFontMetricPath(const wxString& path) ; + void SetPrinterScaleX(double x) ; + void SetPrinterScaleY(double y) ; + void SetPrinterScaling(double x, double y) ; + void SetPrinterTranslateX(long x) ; + void SetPrinterTranslateY(long y) ; + void SetPrinterTranslation(long x, long y) ; + void SetPrintMode(wxPrintMode printMode) ; + @endcode + @library{wxcore} @category{printing} - @see @ref overview_printingoverview "Printing framework overview", - wxPrintDialog, wxPageSetupDialog, wxPrintDialogData, wxPageSetupDialogData, @ref overview_wxprintdialogoverview "wxPrintDialog Overview", wxPrinterDC, wxPostScriptDC + @see @ref overview_printing, wxPrintDialog, wxPageSetupDialog, + wxPrintDialogData, wxPageSetupDialogData, @ref overview_cmndlg_print, + wxPrinterDC, wxPostScriptDC */ class wxPrintData : public wxObject { public: - //@{ /** - Copy constructor. + Default constructor. */ wxPrintData(); + + /** + Copy constructor. + */ wxPrintData(const wxPrintData& data); - //@} /** Destructor. @@ -445,8 +525,9 @@ public: ~wxPrintData(); /** - Returns the current bin (papersource). By default, the system is left to select - the bin (@c wxPRINTBIN_DEFAULT is returned). + Returns the current bin (papersource). By default, the system is left + to select the bin (@c wxPRINTBIN_DEFAULT is returned). + See SetBin() for the full list of bin values. */ wxPrintBin GetBin() const; @@ -478,37 +559,43 @@ public: int GetOrientation() const; /** - Returns the paper size id. For more information, see SetPaperId(). + Returns the paper size id. + + @see SetPaperId() */ wxPaperSize GetPaperId() const; /** - Returns the printer name. If the printer name is the empty string, it indicates - that the default - printer should be used. + Returns the printer name. If the printer name is the empty string, it + indicates that the default printer should be used. */ const wxString GetPrinterName() const; /** - Returns the current print quality. This can be a positive integer, denoting the - number of dots per inch, or - one of the following identifiers: + Returns the current print quality. This can be a positive integer, + denoting the number of dots per inch, or one of the following + identifiers: - On input you should pass one of these identifiers, but on return you may get - back a positive integer - indicating the current resolution setting. + - wxPRINT_QUALITY_HIGH + - wxPRINT_QUALITY_MEDIUM + - wxPRINT_QUALITY_LOW + - wxPRINT_QUALITY_DRAFT + + On input you should pass one of these identifiers, but on return you + may get back a positive integer indicating the current resolution + setting. */ wxPrintQuality GetQuality() const; /** Returns @true if the print data is valid for using in print dialogs. - This can return @false on Windows if the current printer is not set, for example. - On all other platforms, it returns @true. + This can return @false on Windows if the current printer is not set, + for example. On all other platforms, it returns @true. */ bool IsOk() const; /** - Sets the current bin. Possible values are: + Sets the current bin. */ void SetBin(wxPrintBin flag); @@ -539,39 +626,38 @@ public: void SetOrientation(int orientation); /** - Sets the paper id. This indicates the type of paper to be used. For a mapping - between - paper id, paper size and string name, see wxPrintPaperDatabase in @c paper.h - (not yet documented). - @a paperId can be one of: + Sets the paper id. This indicates the type of paper to be used. For a + mapping between paper id, paper size and string name, see + wxPrintPaperDatabase in @c "paper.h" (not yet documented). */ void SetPaperId(wxPaperSize paperId); /** - Sets the printer name. This can be the empty string to indicate that the default - printer should be used. + Sets the printer name. This can be the empty string to indicate that + the default printer should be used. */ void SetPrinterName(const wxString& printerName); /** - Sets the desired print quality. This can be a positive integer, denoting the - number of dots per inch, or - one of the following identifiers: + Sets the desired print quality. This can be a positive integer, + denoting the number of dots per inch, or one of the following + identifiers: + + - wxPRINT_QUALITY_HIGH + - wxPRINT_QUALITY_MEDIUM + - wxPRINT_QUALITY_LOW + - wxPRINT_QUALITY_DRAFT - On input you should pass one of these identifiers, but on return you may get - back a positive integer - indicating the current resolution setting. + On input you should pass one of these identifiers, but on return you + may get back a positive integer indicating the current resolution + setting. */ void SetQuality(wxPrintQuality quality); - //@{ /** - Assigns print setup data to this object. wxPrintSetupData is deprecated, - but retained for backward compatibility. + Assigns print data to this object. */ void operator =(const wxPrintData& data); - void operator =(const wxPrintSetupData& data); - //@} }; @@ -581,26 +667,31 @@ public: @wxheader{cmndata.h} This class holds information related to the visual characteristics of - wxPrintDialog. - It contains a wxPrintData object with underlying printing settings. + wxPrintDialog. It contains a wxPrintData object with underlying printing + settings. @library{wxcore} @category{printing} - @see @ref overview_printingoverview "Printing framework overview", - wxPrintDialog, @ref overview_wxprintdialogoverview "wxPrintDialog Overview" + @see @ref overview_printing, wxPrintDialog, @ref overview_cmndlg_print */ class wxPrintDialogData : public wxObject { public: - //@{ /** - Construct an object from a print dialog data object. + Default constructor. */ wxPrintDialogData(); + + /** + Copy constructor. + */ wxPrintDialogData(wxPrintDialogData& dialogData); + + /** + Construct an object from a print dialog data object. + */ wxPrintDialogData(wxPrintData& printData); - //@} /** Destructor. @@ -608,22 +699,22 @@ public: ~wxPrintDialogData(); /** - Enables or disables the 'Help' button. + Enables or disables the "Help" button. */ void EnableHelp(bool flag); /** - Enables or disables the 'Page numbers' controls. + Enables or disables the "Page numbers" controls. */ void EnablePageNumbers(bool flag); /** - Enables or disables the 'Print to file' checkbox. + Enables or disables the "Print to file" checkbox. */ void EnablePrintToFile(bool flag); /** - Enables or disables the 'Selection' radio button. + Enables or disables the "Selection" radio button. */ void EnableSelection(bool flag); @@ -660,7 +751,7 @@ public: /** Returns a reference to the internal wxPrintData object. */ - wxPrintData GetPrintData(); + wxPrintData& GetPrintData(); /** Returns @true if the user has selected printing to a file. @@ -668,26 +759,25 @@ public: bool GetPrintToFile() const; /** - Returns @true if the user requested that the selection be printed (where - 'selection' is - a concept specific to the application). + Returns @true if the user requested that the selection be printed + (where "selection" is a concept specific to the application). */ bool GetSelection() const; /** - Returns the @e to page number, as entered by the user. + Returns the @e "print to" page number, as entered by the user. */ int GetToPage() const; /** Returns @true if the print data is valid for using in print dialogs. - This can return @false on Windows if the current printer is not set, for example. - On all other platforms, it returns @true. + This can return @false on Windows if the current printer is not set, + for example. On all other platforms, it returns @true. */ bool IsOk() const; /** - Sets the 'Collate' checkbox to @true or @false. + Sets the "Collate" checkbox to @true or @false. */ void SetCollate(bool flag); @@ -707,7 +797,8 @@ public: void SetMinPage(int page); /** - Sets the default number of copies the user has requested to be printed out. + Sets the default number of copies the user has requested to be printed + out. */ void SetNoCopies(int n); @@ -717,35 +808,39 @@ public: void SetPrintData(const wxPrintData& printData); /** - Sets the 'Print to file' checkbox to @true or @false. + Sets the "Print to file" checkbox to @true or @false. */ void SetPrintToFile(bool flag); /** - Selects the 'Selection' radio button. The effect of printing the selection - depends on how the application - implements this command, if at all. + Selects the "Selection" radio button. The effect of printing the + selection depends on how the application implements this command, if at + all. */ void SetSelection(bool flag); /** + @deprecated This function has been deprecated since version 2.5.4. + Determines whether the dialog to be shown will be the Print dialog (pass @false) or Print Setup dialog (pass @true). - This function has been deprecated since version 2.5.4. + */ void SetSetupDialog(bool flag); /** - Sets the @e to page number. + Sets the @e "print to" page number. */ void SetToPage(int page); - //@{ /** - Assigns another print dialog data object to this object. + Assigns print data to this object. */ void operator =(const wxPrintData& data); + + /** + Assigns another print dialog data object to this object. + */ void operator =(const wxPrintDialogData& data); - //@} }; diff --git a/interface/datectrl.h b/interface/datectrl.h index 5c55af5a13..499c9048c6 100644 --- a/interface/datectrl.h +++ b/interface/datectrl.h @@ -48,7 +48,7 @@ @endEventTable @library{wxadv} - @category{miscpickers} + @category{pickers} @appearance{datepickerctrl.png} @see wxCalendarCtrl, wxDateEvent diff --git a/interface/defs.h b/interface/defs.h index 8064aab26f..47fd6ffaac 100644 --- a/interface/defs.h +++ b/interface/defs.h @@ -6,6 +6,137 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + Paper size types for use with the printing framework. + + @see overview_printing, wxPrintData::SetPaperId() +*/ +enum wxPaperSize +{ + wxPAPER_NONE, ///< Use specific dimensions + wxPAPER_LETTER, ///< Letter, 8 1/2 by 11 inches + wxPAPER_LEGAL, ///< Legal, 8 1/2 by 14 inches + wxPAPER_A4, ///< A4 Sheet, 210 by 297 millimeters + wxPAPER_CSHEET, ///< C Sheet, 17 by 22 inches + wxPAPER_DSHEET, ///< D Sheet, 22 by 34 inches + wxPAPER_ESHEET, ///< E Sheet, 34 by 44 inches + wxPAPER_LETTERSMALL, ///< Letter Small, 8 1/2 by 11 inches + wxPAPER_TABLOID, ///< Tabloid, 11 by 17 inches + wxPAPER_LEDGER, ///< Ledger, 17 by 11 inches + wxPAPER_STATEMENT, ///< Statement, 5 1/2 by 8 1/2 inches + wxPAPER_EXECUTIVE, ///< Executive, 7 1/4 by 10 1/2 inches + wxPAPER_A3, ///< A3 sheet, 297 by 420 millimeters + wxPAPER_A4SMALL, ///< A4 small sheet, 210 by 297 millimeters + wxPAPER_A5, ///< A5 sheet, 148 by 210 millimeters + wxPAPER_B4, ///< B4 sheet, 250 by 354 millimeters + wxPAPER_B5, ///< B5 sheet, 182-by-257-millimeter paper + wxPAPER_FOLIO, ///< Folio, 8-1/2-by-13-inch paper + wxPAPER_QUARTO, ///< Quarto, 215-by-275-millimeter paper + wxPAPER_10X14, ///< 10-by-14-inch sheet + wxPAPER_11X17, ///< 11-by-17-inch sheet + wxPAPER_NOTE, ///< Note, 8 1/2 by 11 inches + wxPAPER_ENV_9, ///< #9 Envelope, 3 7/8 by 8 7/8 inches + wxPAPER_ENV_10, ///< #10 Envelope, 4 1/8 by 9 1/2 inches + wxPAPER_ENV_11, ///< #11 Envelope, 4 1/2 by 10 3/8 inches + wxPAPER_ENV_12, ///< #12 Envelope, 4 3/4 by 11 inches + wxPAPER_ENV_14, ///< #14 Envelope, 5 by 11 1/2 inches + wxPAPER_ENV_DL, ///< DL Envelope, 110 by 220 millimeters + wxPAPER_ENV_C5, ///< C5 Envelope, 162 by 229 millimeters + wxPAPER_ENV_C3, ///< C3 Envelope, 324 by 458 millimeters + wxPAPER_ENV_C4, ///< C4 Envelope, 229 by 324 millimeters + wxPAPER_ENV_C6, ///< C6 Envelope, 114 by 162 millimeters + wxPAPER_ENV_C65, ///< C65 Envelope, 114 by 229 millimeters + wxPAPER_ENV_B4, ///< B4 Envelope, 250 by 353 millimeters + wxPAPER_ENV_B5, ///< B5 Envelope, 176 by 250 millimeters + wxPAPER_ENV_B6, ///< B6 Envelope, 176 by 125 millimeters + wxPAPER_ENV_ITALY, ///< Italy Envelope, 110 by 230 millimeters + wxPAPER_ENV_MONARCH, ///< Monarch Envelope, 3 7/8 by 7 1/2 inches + wxPAPER_ENV_PERSONAL, ///< 6 3/4 Envelope, 3 5/8 by 6 1/2 inches + wxPAPER_FANFOLD_US, ///< US Std Fanfold, 14 7/8 by 11 inches + wxPAPER_FANFOLD_STD_GERMAN, ///< German Std Fanfold, 8 1/2 by 12 inches + wxPAPER_FANFOLD_LGL_GERMAN, ///< German Legal Fanfold, 8 1/2 by 13 inches + + // Windows 95 Only + + wxPAPER_ISO_B4, ///< B4 (ISO) 250 x 353 mm + wxPAPER_JAPANESE_POSTCARD, ///< Japanese Postcard 100 x 148 mm + wxPAPER_9X11, ///< 9 x 11 in + wxPAPER_10X11, ///< 10 x 11 in + wxPAPER_15X11, ///< 15 x 11 in + wxPAPER_ENV_INVITE, ///< Envelope Invite 220 x 220 mm + wxPAPER_LETTER_EXTRA, ///< Letter Extra 9 \275 x 12 in + wxPAPER_LEGAL_EXTRA, ///< Legal Extra 9 \275 x 15 in + wxPAPER_TABLOID_EXTRA, ///< Tabloid Extra 11.69 x 18 in + wxPAPER_A4_EXTRA, ///< A4 Extra 9.27 x 12.69 in + wxPAPER_LETTER_TRANSVERSE, ///< Letter Transverse 8 \275 x 11 in + wxPAPER_A4_TRANSVERSE, ///< A4 Transverse 210 x 297 mm + wxPAPER_LETTER_EXTRA_TRANSVERSE, ///< Letter Extra Transverse 9\275 x 12 in + wxPAPER_A_PLUS, ///< SuperA/SuperA/A4 227 x 356 mm + wxPAPER_B_PLUS, ///< SuperB/SuperB/A3 305 x 487 mm + wxPAPER_LETTER_PLUS, ///< Letter Plus 8.5 x 12.69 in + wxPAPER_A4_PLUS, ///< A4 Plus 210 x 330 mm + wxPAPER_A5_TRANSVERSE, ///< A5 Transverse 148 x 210 mm + wxPAPER_B5_TRANSVERSE, ///< B5 (JIS) Transverse 182 x 257 mm + wxPAPER_A3_EXTRA, ///< A3 Extra 322 x 445 mm + wxPAPER_A5_EXTRA, ///< A5 Extra 174 x 235 mm + wxPAPER_B5_EXTRA, ///< B5 (ISO) Extra 201 x 276 mm + wxPAPER_A2, ///< A2 420 x 594 mm + wxPAPER_A3_TRANSVERSE, ///< A3 Transverse 297 x 420 mm + wxPAPER_A3_EXTRA_TRANSVERSE, ///< A3 Extra Transverse 322 x 445 mm + + wxPAPER_DBL_JAPANESE_POSTCARD, ///< Japanese Double Postcard 200 x 148 mm + wxPAPER_A6, ///< A6 105 x 148 mm + wxPAPER_JENV_KAKU2, ///< Japanese Envelope Kaku #2 + wxPAPER_JENV_KAKU3, ///< Japanese Envelope Kaku #3 + wxPAPER_JENV_CHOU3, ///< Japanese Envelope Chou #3 + wxPAPER_JENV_CHOU4, ///< Japanese Envelope Chou #4 + wxPAPER_LETTER_ROTATED, ///< Letter Rotated 11 x 8 1/2 in + wxPAPER_A3_ROTATED, ///< A3 Rotated 420 x 297 mm + wxPAPER_A4_ROTATED, ///< A4 Rotated 297 x 210 mm + wxPAPER_A5_ROTATED, ///< A5 Rotated 210 x 148 mm + wxPAPER_B4_JIS_ROTATED, ///< B4 (JIS) Rotated 364 x 257 mm + wxPAPER_B5_JIS_ROTATED, ///< B5 (JIS) Rotated 257 x 182 mm + wxPAPER_JAPANESE_POSTCARD_ROTATED, ///< Japanese Postcard Rotated 148 x 100 mm + wxPAPER_DBL_JAPANESE_POSTCARD_ROTATED, ///< Double Japanese Postcard Rotated 148 x 200 mm + wxPAPER_A6_ROTATED, ///< A6 Rotated 148 x 105 mm + wxPAPER_JENV_KAKU2_ROTATED, ///< Japanese Envelope Kaku #2 Rotated + wxPAPER_JENV_KAKU3_ROTATED, ///< Japanese Envelope Kaku #3 Rotated + wxPAPER_JENV_CHOU3_ROTATED, ///< Japanese Envelope Chou #3 Rotated + wxPAPER_JENV_CHOU4_ROTATED, ///< Japanese Envelope Chou #4 Rotated + wxPAPER_B6_JIS, ///< B6 (JIS) 128 x 182 mm + wxPAPER_B6_JIS_ROTATED, ///< B6 (JIS) Rotated 182 x 128 mm + wxPAPER_12X11, ///< 12 x 11 in + wxPAPER_JENV_YOU4, ///< Japanese Envelope You #4 + wxPAPER_JENV_YOU4_ROTATED, ///< Japanese Envelope You #4 Rotated + wxPAPER_P16K, ///< PRC 16K 146 x 215 mm + wxPAPER_P32K, ///< PRC 32K 97 x 151 mm + wxPAPER_P32KBIG, ///< PRC 32K(Big) 97 x 151 mm + wxPAPER_PENV_1, ///< PRC Envelope #1 102 x 165 mm + wxPAPER_PENV_2, ///< PRC Envelope #2 102 x 176 mm + wxPAPER_PENV_3, ///< PRC Envelope #3 125 x 176 mm + wxPAPER_PENV_4, ///< PRC Envelope #4 110 x 208 mm + wxPAPER_PENV_5, ///< PRC Envelope #5 110 x 220 mm + wxPAPER_PENV_6, ///< PRC Envelope #6 120 x 230 mm + wxPAPER_PENV_7, ///< PRC Envelope #7 160 x 230 mm + wxPAPER_PENV_8, ///< PRC Envelope #8 120 x 309 mm + wxPAPER_PENV_9, ///< PRC Envelope #9 229 x 324 mm + wxPAPER_PENV_10, ///< PRC Envelope #10 324 x 458 mm + wxPAPER_P16K_ROTATED, ///< PRC 16K Rotated + wxPAPER_P32K_ROTATED, ///< PRC 32K Rotated + wxPAPER_P32KBIG_ROTATED, ///< PRC 32K(Big) Rotated + wxPAPER_PENV_1_ROTATED, ///< PRC Envelope #1 Rotated 165 x 102 mm + wxPAPER_PENV_2_ROTATED, ///< PRC Envelope #2 Rotated 176 x 102 mm + wxPAPER_PENV_3_ROTATED, ///< PRC Envelope #3 Rotated 176 x 125 mm + wxPAPER_PENV_4_ROTATED, ///< PRC Envelope #4 Rotated 208 x 110 mm + wxPAPER_PENV_5_ROTATED, ///< PRC Envelope #5 Rotated 220 x 110 mm + wxPAPER_PENV_6_ROTATED, ///< PRC Envelope #6 Rotated 230 x 120 mm + wxPAPER_PENV_7_ROTATED, ///< PRC Envelope #7 Rotated 230 x 160 mm + wxPAPER_PENV_8_ROTATED, ///< PRC Envelope #8 Rotated 309 x 120 mm + wxPAPER_PENV_9_ROTATED, ///< PRC Envelope #9 Rotated 324 x 229 mm + wxPAPER_PENV_10_ROTATED ///< PRC Envelope #10 Rotated 458 x 324 m +}; + + /** @ingroup group_funcmacro_byteorder */ //@{ diff --git a/interface/filepicker.h b/interface/filepicker.h index 2c9e5bdbfc..023f303051 100644 --- a/interface/filepicker.h +++ b/interface/filepicker.h @@ -42,7 +42,7 @@ @endStyleTable @library{wxcore} - @category{miscpickers} + @category{pickers} @appearance{filepickerctrl.png} @see wxFileDialog, wxFileDirPickerEvent @@ -160,7 +160,7 @@ public: @endStyleTable @library{wxcore} - @category{miscpickers} + @category{pickers} @appearance{dirpickerctrl.png} @see wxDirDialog, wxFileDirPickerEvent diff --git a/interface/fontpicker.h b/interface/fontpicker.h index a616a86c49..c813540a7d 100644 --- a/interface/fontpicker.h +++ b/interface/fontpicker.h @@ -37,7 +37,7 @@ @endStyleTable @library{wxcore} - @category{miscpickers} + @category{pickers} @appearance{fontpickerctrl.png} @see wxFontDialog, wxFontPickerEvent -- 2.45.2