From: Bryan Petty Date: Mon, 21 Apr 2008 01:40:12 +0000 (+0000) Subject: More initial reviews of d* interface headers. X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/bc85d676b7e8b54d7c53a4ad0a357a569fc7c309 More initial reviews of d* interface headers. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53279 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/interface/dialup.h b/interface/dialup.h index 2b72e9786b..165bf57581 100644 --- a/interface/dialup.h +++ b/interface/dialup.h @@ -10,26 +10,33 @@ @class wxDialUpManager @wxheader{dialup.h} - This class encapsulates functions dealing with verifying the connection status - of the workstation (connected to the Internet via a direct connection, - connected through a modem or not connected at all) and to establish this - connection if possible/required (i.e. in the case of the modem). + This class encapsulates functions dealing with verifying the connection + status of the workstation (connected to the Internet via a direct + connection, connected through a modem or not connected at all) and to + establish this connection if possible/required (i.e. in the case of the + modem). The program may also wish to be notified about the change in the connection status (for example, to perform some action when the user connects to the - network the next time or, on the contrary, to stop receiving data from the net - when the user hangs up the modem). For this, you need to use one of the event - macros described below. + network the next time or, on the contrary, to stop receiving data from the + net when the user hangs up the modem). For this, you need to use one of the + event macros described below. - This class is different from other wxWidgets classes in that there is at most - one instance of this class in the program accessed via - wxDialUpManager::Create and you can't - create the objects of this class directly. + This class is different from other wxWidgets classes in that there is at + most one instance of this class in the program accessed via Create() and + you can't create the objects of this class directly. + + @beginEventTable{wxDialUpEvent} + @event{EVT_DIALUP_CONNECTED(func)} + A connection with the network was established. + @event{EVT_DIALUP_DISCONNECTED(func)} + The connection with the network was lost. + @endEventTable @library{wxcore} @category{net} - @see @ref overview_sampledialup "dialup sample", wxDialUpEvent + @see @ref page_samples_dialup, wxDialUpEvent */ class wxDialUpManager { @@ -40,35 +47,39 @@ public: ~wxDialUpManager(); /** - Cancel dialing the number initiated with Dial() - with async parameter equal to @true. - Note that this won't result in DISCONNECTED event being sent. + Cancel dialing the number initiated with Dial() with async parameter + equal to @true. + + @note This won't result in a DISCONNECTED event being sent. @see IsDialing() */ bool CancelDialing(); /** - This function should create and return the object of the platform-specific - class derived from wxDialUpManager. You should delete the pointer when you are - done with it. + This function should create and return the object of the + platform-specific class derived from wxDialUpManager. You should delete + the pointer when you are done with it. */ wxDialUpManager* Create(); /** Dial the given ISP, use @a username and @a password to authenticate. - The parameters are only used under Windows currently, for Unix you should use - SetConnectCommand() to customize this - functions behaviour. + + The parameters are only used under Windows currently, for Unix you + should use SetConnectCommand() to customize this functions behaviour. + If no @a nameOfISP is given, the function will select the default one - (proposing the user to choose among all connections defined on this machine) - and if no username and/or password are given, the function will try to do - without them, but will ask the user if really needed. - If @a async parameter is @false, the function waits until the end of dialing - and returns @true upon successful completion. + (proposing the user to choose among all connections defined on this + machine) and if no username and/or password are given, the function + will try to do without them, but will ask the user if really needed. + + If @a async parameter is @false, the function waits until the end of + dialing and returns @true upon successful completion. + If @a async is @true, the function only initiates the connection and - returns immediately - the result is reported via events (an event is sent - anyhow, but if dialing failed it will be a DISCONNECTED one). + returns immediately - the result is reported via events (an event is + sent anyhow, but if dialing failed it will be a DISCONNECTED one). */ bool Dial(const wxString& nameOfISP = wxEmptyString, const wxString& username = wxEmptyString, @@ -83,20 +94,23 @@ public: /** Enable automatic checks for the connection status and sending of - @c wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval - parameter is only for Unix where we do the check manually and specifies how - often should we repeat the check (each minute by default). Under Windows, the - notification about the change of connection status is sent by the system and so - we don't do any polling and this parameter is ignored. - Returns @false if couldn't set up automatic check for online status. + wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval + parameter is only for Unix where we do the check manually and specifies + how often should we repeat the check (each minute by default). Under + Windows, the notification about the change of connection status is sent + by the system and so we don't do any polling and this parameter is + ignored. + + @returns @false if couldn't set up automatic check for online status. */ bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60); /** This function is only implemented under Windows. + Fills the array with the names of all possible values for the first - parameter to Dial() on this machine and returns - their number (may be 0). + parameter to Dial() on this machine and returns their number (may be + 0). */ size_t GetISPNames(wxArrayString& names) const; @@ -106,11 +120,13 @@ public: bool HangUp(); /** - Returns @true if the computer has a permanent network connection (i.e. is - on a LAN) and so there is no need to use Dial() function to go online. - @note this functions tries to guess the result and it is not always - guaranteed to be correct, so it is better to ask user for - confirmation or give him a possibility to override it. + Returns @true if the computer has a permanent network connection (i.e. + is on a LAN) and so there is no need to use Dial() function to go + online. + + @note This function tries to guess the result and it is not always + guaranteed to be correct, so it is better to ask user for + confirmation or give him a possibility to override it. */ bool IsAlwaysOnline() const; @@ -123,32 +139,33 @@ public: /** Returns @true if the dialup manager was initialized correctly. If this - function returns @false, no other functions will work neither, so it is a - good idea to call this function and check its result before calling any other - wxDialUpManager methods + function returns @false, no other functions will work neither, so it is + a good idea to call this function and check its result before calling + any other wxDialUpManager methods. */ bool IsOk() const; /** - Returns @true if the computer is connected to the network: under Windows, - this just means that a RAS connection exists, under Unix we check that - the "well-known host" (as specified by - wxDialUpManager::SetWellKnownHost) is reachable. + Returns @true if the computer is connected to the network: under + Windows, this just means that a RAS connection exists, under Unix we + check that the "well-known host" (as specified by SetWellKnownHost()) + is reachable. */ bool IsOnline() const; /** - , wxString&@e commandHangup = wxT("/usr/bin/poff")) This method is for Unix only. + Sets the commands to start up the network and to hang up again. */ - void SetConnectCommand() const; + void SetConnectCommand(const wxString& commandDial = "/usr/bin/pon", + const wxString& commandHangup = "/usr/bin/poff") const; /** - Sometimes the built-in logic for determining the online status may fail, - so, in general, the user should be allowed to override it. This function - allows to forcefully set the online status - whatever our internal - algorithm may think about it. + Sometimes the built-in logic for determining the online status may + fail, so, in general, the user should be allowed to override it. This + function allows to forcefully set the online status - whatever our + internal algorithm may think about it. @see IsOnline() */ @@ -156,9 +173,11 @@ public: /** This method is for Unix only. + Under Unix, the value of well-known host is used to check whether we're - connected to the internet. It is unused under Windows, but this function - is always safe to call. The default value is @c www.yahoo.com:80. + connected to the internet. It is unused under Windows, but this + function is always safe to call. The default value is + @c "www.yahoo.com:80". */ void SetWellKnownHost(const wxString& hostname, int portno = 80); }; @@ -169,8 +188,7 @@ public: @class wxDialUpEvent @wxheader{dialup.h} - This is the event class for the dialup events sent by - wxDialUpManager. + This is the event class for the dialup events sent by wxDialUpManager. @library{wxcore} @category{events} @@ -184,8 +202,8 @@ public: wxDialUpEvent(bool isConnected, bool isOwnEvent); /** - Is this a @c CONNECTED or @c DISCONNECTED event? In other words, does it - notify about transition from offline to online state or vice versa? + Is this a @c CONNECTED or @c DISCONNECTED event? In other words, does + it notify about transition from offline to online state or vice versa? */ bool IsConnectedEvent() const; diff --git a/interface/dir.h b/interface/dir.h index cb9ca73917..4e65800c52 100644 --- a/interface/dir.h +++ b/interface/dir.h @@ -1,47 +1,57 @@ ///////////////////////////////////////////////////////////////////////////// // Name: dir.h -// Purpose: interface of wxDirTraverser +// Purpose: interface of wxDir and wxDirTraverser // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + Possible return values of wxDirTraverser callback functions. +*/ +enum wxDirTraverseResult +{ + wxDIR_IGNORE = -1, ///< Ignore this directory but continue with others. + wxDIR_STOP, ///< Stop traversing. + wxDIR_CONTINUE ///< Continue into this directory. +}; + /** @class wxDirTraverser @wxheader{dir.h} - wxDirTraverser is an abstract interface which must be implemented by objects - passed to wxDir::Traverse function. + wxDirTraverser is an abstract interface which must be implemented by + objects passed to wxDir::Traverse() function. - Example of use (this works almost like wxDir::GetAllFiles): + Example of use (this works almost like wxDir::GetAllFiles()): @code class wxDirTraverserSimple : public wxDirTraverser + { + public: + wxDirTraverserSimple(wxArrayString& files) : m_files(files) { } + + virtual wxDirTraverseResult OnFile(const wxString& filename) { - public: - wxDirTraverserSimple(wxArrayString& files) : m_files(files) { } - - virtual wxDirTraverseResult OnFile(const wxString& filename) - { - m_files.Add(filename); - return wxDIR_CONTINUE; - } - - virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname)) - { - return wxDIR_CONTINUE; - } - - private: - wxArrayString& m_files; - }; - - // get the names of all files in the array - wxArrayString files; - wxDirTraverserSimple traverser(files); - - wxDir dir(dirname); - dir.Traverse(traverser); + m_files.Add(filename); + return wxDIR_CONTINUE; + } + + virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname)) + { + return wxDIR_CONTINUE; + } + + private: + wxArrayString& m_files; + }; + + // get the names of all files in the array + wxArrayString files; + wxDirTraverserSimple traverser(files); + + wxDir dir(dirname); + dir.Traverse(traverser); @endcode @library{wxbase} @@ -51,69 +61,87 @@ class wxDirTraverser { public: /** - This function is called for each directory. It may return @c wxDIR_STOP - to abort traversing completely, @c wxDIR_IGNORE to skip this directory but - continue with others or @c wxDIR_CONTINUE to enumerate all files and + This function is called for each directory. It may return ::wxDIR_STOP + to abort traversing completely, ::wxDIR_IGNORE to skip this directory + but continue with others or ::wxDIR_CONTINUE to enumerate all files and subdirectories in this directory. - This is a pure virtual function and must be implemented in the derived class. + + This is a pure virtual function and must be implemented in the derived + class. */ virtual wxDirTraverseResult OnDir(const wxString& dirname); /** - This function is called for each file. It may return @c wxDIR_STOP to abort - traversing (for example, if the file being searched is found) or - @c wxDIR_CONTINUE to proceed. - This is a pure virtual function and must be implemented in the derived class. + This function is called for each file. It may return ::wxDIR_STOP to + abort traversing (for example, if the file being searched is found) or + ::wxDIR_CONTINUE to proceed. + + This is a pure virtual function and must be implemented in the derived + class. */ virtual wxDirTraverseResult OnFile(const wxString& filename); /** This function is called for each directory which we failed to open for - enumerating. It may return @c wxDIR_STOP to abort traversing completely, - @c wxDIR_IGNORE to skip this directory but continue with others or - @c wxDIR_CONTINUE to retry opening this directory once again. - The base class version always returns @c wxDIR_IGNORE. + enumerating. It may return ::wxDIR_STOP to abort traversing completely, + ::wxDIR_IGNORE to skip this directory but continue with others or + ::wxDIR_CONTINUE to retry opening this directory once again. + + The base class version always returns ::wxDIR_IGNORE. */ virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname); }; +/** + These flags define what kind of filenames are included in the list of files + enumerated by wxDir::GetFirst() and wxDir::GetNext(). +*/ +enum +{ + wxDIR_FILES = 0x0001, ///< Includes files. + wxDIR_DIRS = 0x0002, ///< Includes directories. + wxDIR_HIDDEN = 0x0004, ///< Includes hidden files. + wxDIR_DOTDOT = 0x0008, ///< Includes "." and "..". + + wxDIR_DEFAULT = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN +}; + /** @class wxDir @wxheader{dir.h} wxDir is a portable equivalent of Unix open/read/closedir functions which - allow enumerating of the files in a directory. wxDir allows to enumerate files - as well as directories. + allow enumerating of the files in a directory. wxDir allows to enumerate + files as well as directories. wxDir also provides a flexible way to enumerate files recursively using - wxDir::Traverse or a simpler - wxDir::GetAllFiles function. + Traverse() or a simpler GetAllFiles() function. Example of use: @code wxDir dir(wxGetCwd()); - if ( !dir.IsOpened() ) - { - // deal with the error here - wxDir would already log an error message - // explaining the exact reason of the failure - return; - } + if ( !dir.IsOpened() ) + { + // deal with the error here - wxDir would already log an error message + // explaining the exact reason of the failure + return; + } - puts("Enumerating object files in current directory:"); + puts("Enumerating object files in current directory:"); - wxString filename; + wxString filename; - bool cont = dir.GetFirst(, filespec, flags); - while ( cont ) - { - printf("%s\n", filename.c_str()); + bool cont = dir.GetFirst(&filename, filespec, flags); + while ( cont ) + { + printf("%s\n", filename.c_str()); - cont = dir.GetNext(); - } + cont = dir.GetNext(&filename); + } @endcode @library{wxbase} @@ -122,51 +150,55 @@ public: class wxDir { public: - //@{ /** - Opens the directory for enumeration, use IsOpened() - to test for errors. + Default constructor, use Open() afterwards. */ wxDir(); + /** + Opens the directory for enumeration, use IsOpened() to test for errors. + */ wxDir(const wxString& dir); - //@} /** - Destructor cleans up the associated resources. It is not virtual and so this - class is not meant to be used polymorphically. + Destructor cleans up the associated resources. It is not virtual and so + this class is not meant to be used polymorphically. */ ~wxDir(); /** - Test for existence of a directory with the given name + Test for existence of a directory with the given name. */ static bool Exists(const wxString& dir); /** - The function returns the path of the first file matching the given @e filespec - or an empty string if there are no files matching it. - The @a flags parameter may or may not include @c wxDIR_FILES, the + The function returns the path of the first file matching the given + @a filespec or an empty string if there are no files matching it. + + The @a flags parameter may or may not include ::wxDIR_FILES, the function always behaves as if it were specified. By default, @a flags - includes @c wxDIR_DIRS and so the function recurses into the subdirectories - but if this flag is not specified, the function restricts the search only to - the directory @a dirname itself. - See also: Traverse() + includes ::wxDIR_DIRS and so the function recurses into the + subdirectories but if this flag is not specified, the function + restricts the search only to the directory @a dirname itself. + + @see Traverse() */ static wxString FindFirst(const wxString& dirname, const wxString& filespec, int flags = wxDIR_DEFAULT); /** - The function appends the names of all the files under directory @a dirname - to the array @a files (note that its old content is preserved). Only files - matching the @a filespec are taken, with empty spec matching all the files. - The @a flags parameter should always include @c wxDIR_FILES or the array - would be unchanged and should include @c wxDIR_DIRS flag to recurse into + The function appends the names of all the files under directory + @a dirname to the array @a files (note that its old content is + preserved). Only files matching the @a filespec are taken, with empty + spec matching all the files. + + The @a flags parameter should always include ::wxDIR_FILES or the array + would be unchanged and should include ::wxDIR_DIRS flag to recurse into subdirectories (both flags are included in the value by default). - See also: Traverse() + + @see Traverse() */ - static size_t GetAllFiles(const wxString& dirname, - wxArrayString* files, + static size_t GetAllFiles(const wxString& dirname, wxArrayString* files, const wxString& filespec = wxEmptyString, int flags = wxDIR_DEFAULT); @@ -179,76 +211,79 @@ public: int flags = wxDIR_DEFAULT) const; /** - Returns the name of the directory itself. The returned string does not have the - trailing path separator (slash or backslash). + Returns the name of the directory itself. The returned string does not + have the trailing path separator (slash or backslash). */ wxString GetName() const; /** - Continue enumerating files which satisfy the criteria specified by the last - call to GetFirst(). + Continue enumerating files which satisfy the criteria specified by the + last call to GetFirst(). */ bool GetNext(wxString* filename) const; /** Returns the size (in bytes) of all files recursively found in @c dir or @c wxInvalidSize in case of error. - In case it happens that while traversing folders a file's size can not be read, - that file is added to the @c filesSkipped array, if not @NULL, and then - skipped. - This usually happens with some special folders which are locked by the - operating system - or by another process. Remember that when @c filesSkipped-GetCount() is not - zero, - then the returned value is not 100% accurate and, if the skipped files were - big, it could be + + In case it happens that while traversing folders a file's size can not + be read, that file is added to the @a filesSkipped array, if not @NULL, + and then skipped. This usually happens with some special folders which + are locked by the operating system or by another process. Remember that + when the size of @a filesSkipped is not zero, then the returned value + is not 100% accurate and, if the skipped files were big, it could be far from real size of the directory. - See also: wxFileName::GetHumanReadableSize, - wxGetDiskSpace() + + @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace() */ static wxULongLong GetTotalSize(const wxString& dir, wxArrayString* filesSkipped = NULL); /** Returns @true if the directory contains any files matching the given - @e filespec. If @a filespec is empty, look for any files at all. In any + @a filespec. If @a filespec is empty, look for any files at all. In any case, even hidden files are taken into account. */ bool HasFiles(const wxString& filespec = wxEmptyString); /** Returns @true if the directory contains any subdirectories (if a non - empty @e filespec is given, only check for directories matching it). + empty @a filespec is given, only check for directories matching it). The hidden subdirectories are taken into account as well. */ bool HasSubDirs(const wxString& dirspec = wxEmptyString); /** - Returns @true if the directory was successfully opened by a previous call to - Open(). + Returns @true if the directory was successfully opened by a previous + call to Open(). */ bool IsOpened() const; /** - Open the directory for enumerating, returns @true on success - or @false if an error occurred. + Open the directory for enumerating, returns @true on success or @false + if an error occurred. */ bool Open(const wxString& dir); /** - Enumerate all files and directories under the given directory recursively - calling the element of the provided wxDirTraverser - object for each of them. + Enumerate all files and directories under the given directory + recursively calling the element of the provided wxDirTraverser object + for each of them. + More precisely, the function will really recurse into subdirectories if - @a flags contains @c wxDIR_DIRS flag. It will ignore the files (but - still possibly recurse into subdirectories) if @c wxDIR_FILES flag is + @a flags contains ::wxDIR_DIRS flag. It will ignore the files (but + still possibly recurse into subdirectories) if ::wxDIR_FILES flag is given. - For each found directory, @ref wxDirTraverser::ondir sink.OnDir is called - and @ref wxDirTraverser::onfile sink.OnFile is called for every file. - Depending on the return value, the enumeration may continue or stop. - The function returns the total number of files found or @c (size_t)-1 on - error. - See also: GetAllFiles() + + For each found directory, @ref wxDirTraverser::OnDir() "sink.OnDir()" + is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called + for every file. Depending on the return value, the enumeration may + continue or stop. + + The function returns the total number of files found or @c "(size_t)-1" + on error. + + @see GetAllFiles() */ size_t Traverse(wxDirTraverser& sink, const wxString& filespec = wxEmptyString, diff --git a/interface/dirctrl.h b/interface/dirctrl.h index 018686b534..b83c4248df 100644 --- a/interface/dirctrl.h +++ b/interface/dirctrl.h @@ -10,20 +10,35 @@ @class wxGenericDirCtrl @wxheader{dirctrl.h} - This control can be used to place a directory listing (with optional files) on - an arbitrary window. + This control can be used to place a directory listing (with optional + files) on an arbitrary window. The control contains a wxTreeCtrl window representing the directory hierarchy, and optionally, a wxChoice window containing a list of filters. + @beginStyleTable + @style{wxDIRCTRL_DIR_ONLY} + Only show directories, and not files. + @style{wxDIRCTRL_3D_INTERNAL} + Use 3D borders for internal controls. + @style{wxDIRCTRL_SELECT_FIRST} + When setting the default path, select the first file in the + directory. + @style{wxDIRCTRL_EDIT_LABELS} + Allow the folder and file labels to be editable. + @endStyleTable + @library{wxbase} @category{ctrl} - @appearance{genericdirctrl.png} + */ class wxGenericDirCtrl : public wxControl { public: - //@{ + /** + Default constructor. + */ + wxGenericDirCtrl(); /** Main constructor. @@ -38,18 +53,17 @@ public: @param size Size. @param style - Window style. Please see wxGenericDirCtrl for a list of possible styles. + Window style. Please see wxGenericDirCtrl for a list of possible + styles. @param filter - A filter string, using the same syntax as that for wxFileDialog. This may - be empty if filters - are not being used. - Example: "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" + A filter string, using the same syntax as that for wxFileDialog. + This may be empty if filters are not being used. Example: + @c "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" @param defaultFilter The zero-indexed default filter setting. @param name The window name. */ - wxGenericDirCtrl(); wxGenericDirCtrl(wxWindow* parent, const wxWindowID id = -1, const wxString& dir = wxDirDialogDefaultFolderStr, const wxPoint& pos = wxDefaultPosition, @@ -58,7 +72,6 @@ public: const wxString& filter = wxEmptyString, int defaultFilter = 0, const wxString& name = wxTreeCtrlNameStr); - //@} /** Destructor. @@ -66,7 +79,7 @@ public: ~wxGenericDirCtrl(); /** - Collapse the given path. + Collapse the given @a path. */ bool CollapsePath(const wxString& path); @@ -76,7 +89,8 @@ public: void CollapseTree(); /** - Create function for two-step construction. See wxGenericDirCtrl() for details. + Create function for two-step construction. See wxGenericDirCtrl() for + details. */ bool Create(wxWindow* parent, const wxWindowID id = -1, const wxString& dir = wxDirDialogDefaultFolderStr, @@ -88,8 +102,8 @@ public: const wxString& name = wxTreeCtrlNameStr); /** - Tries to expand as much of the given path as possible, so that the filename or - directory is visible in the tree control. + Tries to expand as much of the given @a path as possible, so that the + filename or directory is visible in the tree control. */ bool ExpandPath(const wxString& path); @@ -100,6 +114,7 @@ public: /** Gets selected filename path only (else empty string). + This function doesn't count a directory as a selection. */ wxString GetFilePath() const; @@ -140,8 +155,8 @@ public: void Init(); /** - Collapse and expand the tree, thus re-creating it from scratch. - May be used to update the displayed directory content. + Collapse and expand the tree, thus re-creating it from scratch. May be + used to update the displayed directory content. */ void ReCreateTree(); diff --git a/interface/dirdlg.h b/interface/dirdlg.h index c6bd03c273..4d21deac85 100644 --- a/interface/dirdlg.h +++ b/interface/dirdlg.h @@ -26,17 +26,19 @@ user. @endStyleTable + @note On Windows the new directory button is only available with recent + versions of the common dialogs. + @library{wxcore} @category{cmndlg} - @see @ref overview_wxdirdialogoverview "wxDirDialog overview", wxFileDialog + @see @ref overview_cmndlg_dir, wxFileDialog */ class wxDirDialog : public wxDialog { public: /** - Constructor. Use ShowModal() to show - the dialog. + Constructor. Use ShowModal() to show the dialog. @param parent Parent window. @@ -87,8 +89,8 @@ public: void SetPath(const wxString& path); /** - Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL - otherwise. + Shows the dialog, returning wxID_OK if the user pressed OK, and + wxID_CANCEL otherwise. */ int ShowModal(); }; diff --git a/interface/display.h b/interface/display.h index e4a3c747e2..71eeeba4f5 100644 --- a/interface/display.h +++ b/interface/display.h @@ -13,7 +13,7 @@ Determines the sizes and locations of displays connected to the system. @library{wxcore} - @category{FIXME} + @category{misc} @see wxClientDisplayRect(), wxDisplaySize(), wxDisplaySizeMM() */ @@ -21,11 +21,12 @@ class wxDisplay { public: /** - Constructor, setting up a wxDisplay instance with the specified display. + Constructor, setting up a wxDisplay instance with the specified + display. @param index - The index of the display to use. This must be non-negative - and lower than the value returned by GetCount(). + The index of the display to use. This must be non-negative and + lower than the value returned by GetCount(). */ wxDisplay(unsigned index = 0); @@ -35,27 +36,28 @@ public: ~wxDisplay(); /** - Changes the video mode of this display to the mode specified - in the mode parameter. - If wxDefaultVideoMode is passed in as the mode parameter, - the defined behaviour is that wxDisplay will reset the video - mode to the default mode used by the display. On Windows, - the behavior is normal. However, there are differences on other - platforms. On Unix variations using X11 extensions it should - behave as defined, but some irregularities may occur. - On wxMac passing in wxDefaultVideoMode as the mode - parameter does nothing. This happens because carbon - no longer has access to DMUseScreenPrefs, an undocumented - function that changed the video mode to the system - default by using the system's 'scrn' resource. + Changes the video mode of this display to the mode specified in the + mode parameter. + + If wxDefaultVideoMode is passed in as the mode parameter, the defined + behaviour is that wxDisplay will reset the video mode to the default + mode used by the display. On Windows, the behavior is normal. However, + there are differences on other platforms. On Unix variations using X11 + extensions it should behave as defined, but some irregularities may + occur. + + On wxMac passing in wxDefaultVideoMode as the mode parameter does + nothing. This happens because carbon no longer has access to + @c DMUseScreenPrefs(), an undocumented function that changed the video + mode to the system default by using the system's "scrn" resource. */ bool ChangeMode(const wxVideoMode& mode = wxDefaultVideoMode); /** - Returns the client area of the display. The client area is the part of the - display available for the normal (non full screen) windows, usually it is the - same as GetGeometry() but it could be less if - there is a taskbar (or equivalent) on this display. + Returns the client area of the display. The client area is the part of + the display available for the normal (non full screen) windows, usually + it is the same as GetGeometry() but it could be less if there is a + taskbar (or equivalent) on this display. */ wxRect GetClientArea() const; @@ -70,12 +72,13 @@ public: wxVideoMode GetCurrentMode() const; /** - Returns the bit depth of the display whose index was passed to the constructor. + Returns the bit depth of the display whose index was passed to the + constructor. */ int GetDepth() const; /** - Returns the index of the display on which the given point lies. Returns + Returns the index of the display on which the given point lies, or @c wxNOT_FOUND if the point is not on any connected display. @param pt @@ -85,8 +88,10 @@ public: /** Returns the index of the display on which the given window lies. - If the window is on more than one display it gets the display that overlaps the - window the most. + + If the window is on more than one display it gets the display that + overlaps the window the most. + Returns @c wxNOT_FOUND if the window is not on any connected display. @param win @@ -95,27 +100,28 @@ public: static int GetFromWindow(const wxWindow* win); /** - Returns the bounding rectangle of the display whose index was passed to the - constructor. + Returns the bounding rectangle of the display whose index was passed to + the constructor. + + @see GetClientArea(), wxDisplaySize() */ wxRect GetGeometry() const; /** - Fills and returns an array with all the video modes that - are supported by this display, or video modes that are - supported by this display and match the mode parameter - (if mode is not wxDefaultVideoMode). + Fills and returns an array with all the video modes that are supported + by this display, or video modes that are supported by this display and + match the mode parameter (if mode is not wxDefaultVideoMode). */ wxArrayVideoModes GetModes(const wxVideoMode& mode = wxDefaultVideoMode) const; /** - Returns the display's name. A name is not available on all platforms. + Returns the display's name. A name is not available on all platforms. */ wxString GetName() const; /** - Returns @true if the display is the primary display. The primary display is the - one whose index is 0. + Returns @true if the display is the primary display. The primary + display is the one whose index is 0. */ bool IsPrimary(); }; diff --git a/interface/dnd.h b/interface/dnd.h index e93ddeef7e..b82f304cdc 100644 --- a/interface/dnd.h +++ b/interface/dnd.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: dnd.h -// Purpose: interface of wxTextDropTarget +// Purpose: interface of wxDropSource and wx*DropTarget // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -15,7 +15,7 @@ @library{wxcore} @category{dnd} - @see @ref overview_wxdndoverview, wxDropSource, wxDropTarget, wxFileDropTarget + @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget */ class wxTextDropTarget : public wxDropTarget { @@ -26,8 +26,8 @@ public: wxTextDropTarget(); /** - See wxDropTarget::OnDrop. This function is implemented - appropriately for text, and calls OnDropText(). + See wxDropTarget::OnDrop(). This function is implemented appropriately + for text, and calls OnDropText(). */ virtual bool OnDrop(long x, long y, const void data, size_t size); @@ -40,41 +40,47 @@ public: The y coordinate of the mouse. @param data The data being dropped: a wxString. + + Return @true to accept the data, or @false to veto the operation. */ - virtual bool OnDropText(wxCoord x, wxCoord y, - const wxString& data); + virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data); }; +/** + Result returned from a wxDropSource::DoDragDrop() call. +*/ +enum wxDragResult +{ + wxDragError, ///< Error prevented the D&D operation from completing. + wxDragNone, ///< Drag target didn't accept the data. + wxDragCopy, ///< The data was successfully copied. + wxDragMove, ///< The data was successfully moved (MSW only). + wxDragLink, ///< Operation is a drag-link. + wxDragCancel ///< The operation was cancelled by user (not an error). +}; + /** @class wxDropTarget @wxheader{dnd.h} - This class represents a target for a drag and drop operation. A wxDataObject - can be associated with it and by default, this object will be filled with the - data from the - drag source, if the data formats supported by the data object match the drag - source data - format. - - There are various virtual handler functions defined in this class which may be - overridden - to give visual feedback or react in a more fine-tuned way, e.g. by not - accepting data on - the whole window area, but only a small portion of it. The normal sequence of - calls is - wxDropTarget::OnEnter, possibly many times wxDropTarget::OnDragOver, - wxDropTarget::OnDrop and finally wxDropTarget::OnData. - - See @ref overview_wxdndoverview and @ref overview_wxdataobjectoverview - for more information. + This class represents a target for a drag and drop operation. A + wxDataObject can be associated with it and by default, this object will be + filled with the data from the drag source, if the data formats supported by + the data object match the drag source data format. + + There are various virtual handler functions defined in this class which may + be overridden to give visual feedback or react in a more fine-tuned way, + e.g. by not accepting data on the whole window area, but only a small + portion of it. The normal sequence of calls is OnEnter(), OnDragOver() + possibly many times, OnDrop() and finally OnData(). @library{wxcore} @category{dnd} - @see wxDropSource, wxTextDropTarget, wxFileDropTarget, wxDataFormat, - wxDataObject + @see @ref overview_dnd, @ref overview_dataobject, wxDropSource, + wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject */ class wxDropTarget { @@ -90,49 +96,47 @@ public: ~wxDropTarget(); /** - This method may only be called from within OnData(). - By default, this method copies the data from the drop source to the - wxDataObject associated with this drop target, - calling its wxDataObject::SetData method. + This method may only be called from within OnData(). By default, this + method copies the data from the drop source to the wxDataObject + associated with this drop target, calling its wxDataObject::SetData() + method. */ virtual void GetData(); /** - Called after OnDrop() returns @true. By default this - will usually GetData() and will return the suggested - default value @e def. + Called after OnDrop() returns @true. By default this will usually + GetData() and will return the suggested default value @a def. */ - virtual wxDragResult OnData(wxCoord x, wxCoord y, - wxDragResult def); + virtual wxDragResult OnData(wxCoord x, wxCoord y, wxDragResult def); /** - Called when the mouse is being dragged over the drop target. By default, - this calls functions return the suggested return value @e def. + Called when the mouse is being dragged over the drop target. By + default, this calls functions return the suggested return value @a def. @param x The x coordinate of the mouse. @param y The y coordinate of the mouse. @param def - Suggested value for return value. Determined by SHIFT or CONTROL key states. + Suggested value for return value. Determined by SHIFT or CONTROL + key states. - @returns Returns the desired operation or wxDragNone. This is used for - optical feedback from the side of the drop source, - typically in form of changing the icon. + @returns The desired operation or wxDragNone. This is used for optical + feedback from the side of the drop source, typically in form + of changing the icon. */ - virtual wxDragResult OnDragOver(wxCoord x, wxCoord y, - wxDragResult def); + virtual wxDragResult OnDragOver(wxCoord x, wxCoord y, wxDragResult def); /** - Called when the user drops a data object on the target. Return @false to veto - the operation. + Called when the user drops a data object on the target. Return @false + to veto the operation. @param x The x coordinate of the mouse. @param y The y coordinate of the mouse. - @returns Return @true to accept the data, @false to veto the operation. + @returns @true to accept the data, or @false to veto the operation. */ virtual bool OnDrop(wxCoord x, wxCoord y); @@ -145,15 +149,14 @@ public: @param y The y coordinate of the mouse. @param def - Suggested default for return value. Determined by SHIFT or CONTROL key - states. + Suggested default for return value. Determined by SHIFT or CONTROL + key states. - @returns Returns the desired operation or wxDragNone. This is used for - optical feedback from the side of the drop source, - typically in form of changing the icon. + @returns The desired operation or wxDragNone. This is used for optical + feedback from the side of the drop source, typically in form + of changing the icon. */ - virtual wxDragResult OnEnter(wxCoord x, wxCoord y, - wxDragResult def); + virtual wxDragResult OnEnter(wxCoord x, wxCoord y, wxDragResult def); /** Called when the mouse leaves the drop target. @@ -161,8 +164,8 @@ public: virtual void OnLeave(); /** - Sets the data wxDataObject associated with the - drop target and deletes any previously associated data object. + Sets the data wxDataObject associated with the drop target and deletes + any previously associated data object. */ void SetDataObject(wxDataObject* data); }; @@ -175,25 +178,21 @@ public: This class represents a source for a drag and drop operation. - See @ref overview_wxdndoverview and @ref overview_wxdataobjectoverview - for more information. - @library{wxcore} @category{dnd} - @see wxDropTarget, wxTextDropTarget, wxFileDropTarget + @see @ref overview_dnd, @ref overview_dataobject, wxDropTarget, + wxTextDropTarget, wxFileDropTarget */ class wxDropSource { public: - //@{ /** - The constructors for wxDataObject. - If you use the constructor without @a data parameter you must call - SetData() later. - Note that the exact type of @a iconCopy and subsequent parameters differs - between wxMSW and wxGTK: these are cursors under Windows but icons for GTK. - You should use the macro wxDROP_ICON() in portable + This constructor requires that you must call SetData() later. + + Note that the exact type of @a iconCopy and subsequent parameters + differs between wxMSW and wxGTK: these are cursors under Windows but + icons for GTK. You should use the macro wxDROP_ICON() in portable programs instead of directly using either of these types. @param win @@ -209,30 +208,44 @@ public: const wxIconOrCursor& iconCopy = wxNullIconOrCursor, const wxIconOrCursor& iconMove = wxNullIconOrCursor, const wxIconOrCursor& iconNone = wxNullIconOrCursor); + /** + Note that the exact type of @a iconCopy and subsequent parameters + differs between wxMSW and wxGTK: these are cursors under Windows but + icons for GTK. You should use the macro wxDROP_ICON() in portable + programs instead of directly using either of these types. + + @param win + The window which initiates the drag and drop operation. + @param iconCopy + The icon or cursor used for feedback for copy operation. + @param iconMove + The icon or cursor used for feedback for move operation. + @param iconNone + The icon or cursor used for feedback when operation can't be done. + */ wxDropSource(wxDataObject& data, wxWindow* win = NULL, const wxIconOrCursor& iconCopy = wxNullIconOrCursor, const wxIconOrCursor& iconMove = wxNullIconOrCursor, const wxIconOrCursor& iconNone = wxNullIconOrCursor); - //@} /** - + Default constructor. */ ~wxDropSource(); /** - Do it (call this in response to a mouse button press, for example). This starts - the drag-and-drop operation which will terminate when the user releases the - mouse. + Starts the drag-and-drop operation which will terminate when the user + releases the mouse. Call this in response to a mouse button press, for + example. @param flags - If wxDrag_AllowMove is included in the flags, data may - be moved and not only copied (default). If wxDrag_DefaultMove is - specified (which includes the previous flag), this is even the default - operation + If wxDrag_AllowMove is included in the flags, data may be moved and + not only copied (default). If wxDrag_DefaultMove is specified + (which includes the previous flag), this is even the default + operation. - @returns Returns the operation requested by the user, may be wxDragCopy, - wxDragMove, wxDragLink, wxDragCancel or wxDragNone if + @returns The operation requested by the user, may be ::wxDragCopy, + ::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if an error occurred. */ virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly); @@ -243,21 +256,18 @@ public: wxDataObject* GetDataObject(); /** - Overridable: you may give some custom UI feedback during the drag and drop - operation - in this function. It is called on each mouse move, so your implementation must - not be too - slow. + You may give some custom UI feedback during the drag and drop operation + by overriding this function. It is called on each mouse move, so your + implementation must not be too slow. @param effect - The effect to implement. One of wxDragCopy, wxDragMove, wxDragLink and - wxDragNone. + The effect to implement. One of ::wxDragCopy, ::wxDragMove, + ::wxDragLink and ::wxDragNone. @param scrolling @true if the window is scrolling. MSW only. - @returns Return @false if you want default feedback, or @true if you - implement your own feedback. The return values is - ignored under GTK. + @returns @false if you want default feedback, or @true if you implement + your own feedback. The return values is ignored under GTK. */ virtual bool GiveFeedback(wxDragResult effect); @@ -272,8 +282,8 @@ public: void SetCursor(wxDragResult res, const wxCursor& cursor); /** - Sets the data wxDataObject associated with the - drop source. This will not delete any previously associated data. + Sets the data wxDataObject associated with the drop source. This will + not delete any previously associated data. */ void SetData(wxDataObject& data); }; @@ -284,13 +294,13 @@ public: @class wxFileDropTarget @wxheader{dnd.h} - This is a @ref overview_wxdroptarget "drop target" which accepts files (dragged - from File Manager or Explorer). + This is a drop target which accepts files (dragged from File Manager or + Explorer). @library{wxcore} @category{dnd} - @see @ref overview_wxdndoverview, wxDropSource, wxDropTarget, wxTextDropTarget + @see @ref overview_dnd, wxDropSource, wxDropTarget, wxTextDropTarget */ class wxFileDropTarget : public wxDropTarget { @@ -301,8 +311,8 @@ public: wxFileDropTarget(); /** - See wxDropTarget::OnDrop. This function is implemented - appropriately for files, and calls OnDropFiles(). + See wxDropTarget::OnDrop(). This function is implemented appropriately + for files, and calls OnDropFiles(). */ virtual bool OnDrop(long x, long y, const void data, size_t size); @@ -315,6 +325,8 @@ public: The y coordinate of the mouse. @param filenames An array of filenames. + + Return @true to accept the data, or @false to veto the operation. */ virtual bool OnDropFiles(wxCoord x, wxCoord y, const wxArrayString& filenames);