Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More initial reviews of d* interface headers.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53279 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-04-21 01:40:12 +00:00
parent 1db8f1dc4a
commit bc85d676b7
6 changed files with 405 additions and 317 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
interface/dialup.h
View File

@@ -10,26 +10,33 @@
@class wxDialUpManager @class wxDialUpManager
@wxheader{dialup.h} @wxheader{dialup.h}
This class encapsulates functions dealing with verifying the connection status This class encapsulates functions dealing with verifying the connection
of the workstation (connected to the Internet via a direct connection, status of the workstation (connected to the Internet via a direct
connected through a modem or not connected at all) and to establish this connection, connected through a modem or not connected at all) and to
connection if possible/required (i.e. in the case of the modem). 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 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 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 network the next time or, on the contrary, to stop receiving data from the
when the user hangs up the modem). For this, you need to use one of the event net when the user hangs up the modem). For this, you need to use one of the
macros described below. event macros described below.
This class is different from other wxWidgets classes in that there is at most This class is different from other wxWidgets classes in that there is at
one instance of this class in the program accessed via most one instance of this class in the program accessed via Create() and
wxDialUpManager::Create and you can't you can't create the objects of this class directly.
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} @library{wxcore}
@category{net} @category{net}
@see @ref overview_sampledialup "dialup sample", wxDialUpEvent @see @ref page_samples_dialup, wxDialUpEvent
*/ */
class wxDialUpManager class wxDialUpManager
{ {
@@ -40,35 +47,39 @@ public:
~wxDialUpManager(); ~wxDialUpManager();
/** /**
Cancel dialing the number initiated with Dial() Cancel dialing the number initiated with Dial() with async parameter
with async parameter equal to @true. equal to @true.
Note that this won't result in DISCONNECTED event being sent.
@note This won't result in a DISCONNECTED event being sent.
@see IsDialing() @see IsDialing()
*/ */
bool CancelDialing(); bool CancelDialing();
/** /**
This function should create and return the object of the platform-specific This function should create and return the object of the
class derived from wxDialUpManager. You should delete the pointer when you are platform-specific class derived from wxDialUpManager. You should delete
done with it. the pointer when you are done with it.
*/ */
wxDialUpManager* Create(); wxDialUpManager* Create();
/** /**
Dial the given ISP, use @a username and @a password to authenticate. 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 The parameters are only used under Windows currently, for Unix you
functions behaviour. should use SetConnectCommand() to customize this functions behaviour.
If no @a nameOfISP is given, the function will select the default one 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) (proposing the user to choose among all connections defined on this
and if no username and/or password are given, the function will try to do machine) and if no username and/or password are given, the function
without them, but will ask the user if really needed. 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 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 If @a async is @true, the function only initiates the connection and
returns immediately - the result is reported via events (an event is sent returns immediately - the result is reported via events (an event is
anyhow, but if dialing failed it will be a DISCONNECTED one). sent anyhow, but if dialing failed it will be a DISCONNECTED one).
*/ */
bool Dial(const wxString& nameOfISP = wxEmptyString, bool Dial(const wxString& nameOfISP = wxEmptyString,
const wxString& username = wxEmptyString, const wxString& username = wxEmptyString,
@@ -83,20 +94,23 @@ public:
/** /**
Enable automatic checks for the connection status and sending of Enable automatic checks for the connection status and sending of
@c wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval
parameter is only for Unix where we do the check manually and specifies how parameter is only for Unix where we do the check manually and specifies
often should we repeat the check (each minute by default). Under Windows, the how often should we repeat the check (each minute by default). Under
notification about the change of connection status is sent by the system and so Windows, the notification about the change of connection status is sent
we don't do any polling and this parameter is ignored. by the system and so we don't do any polling and this parameter is
Returns @false if couldn't set up automatic check for online status. ignored.
@returns @false if couldn't set up automatic check for online status.
*/ */
bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60); bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60);
/** /**
This function is only implemented under Windows. This function is only implemented under Windows.
Fills the array with the names of all possible values for the first Fills the array with the names of all possible values for the first
parameter to Dial() on this machine and returns parameter to Dial() on this machine and returns their number (may be
their number (may be 0). 0).
*/ */
size_t GetISPNames(wxArrayString& names) const; size_t GetISPNames(wxArrayString& names) const;
@@ -106,11 +120,13 @@ public:
bool HangUp(); bool HangUp();
/** /**
Returns @true if the computer has a permanent network connection (i.e. is Returns @true if the computer has a permanent network connection (i.e.
on a LAN) and so there is no need to use Dial() function to go online. is on a LAN) and so there is no need to use Dial() function to go
@note this functions tries to guess the result and it is not always online.
guaranteed to be correct, so it is better to ask user for
confirmation or give him a possibility to override it. @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; bool IsAlwaysOnline() const;
@@ -123,32 +139,33 @@ public:
/** /**
Returns @true if the dialup manager was initialized correctly. If this Returns @true if the dialup manager was initialized correctly. If this
function returns @false, no other functions will work neither, so it is a function returns @false, no other functions will work neither, so it is
good idea to call this function and check its result before calling any other a good idea to call this function and check its result before calling
wxDialUpManager methods any other wxDialUpManager methods.
*/ */
bool IsOk() const; bool IsOk() const;
/** /**
Returns @true if the computer is connected to the network: under Windows, Returns @true if the computer is connected to the network: under
this just means that a RAS connection exists, under Unix we check that Windows, this just means that a RAS connection exists, under Unix we
the "well-known host" (as specified by check that the "well-known host" (as specified by SetWellKnownHost())
wxDialUpManager::SetWellKnownHost) is reachable. is reachable.
*/ */
bool IsOnline() const; bool IsOnline() const;
/** /**
, wxString&@e commandHangup = wxT("/usr/bin/poff"))
This method is for Unix only. This method is for Unix only.
Sets the commands to start up the network and to hang up again. 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, Sometimes the built-in logic for determining the online status may
so, in general, the user should be allowed to override it. This function fail, so, in general, the user should be allowed to override it. This
allows to forcefully set the online status - whatever our internal function allows to forcefully set the online status - whatever our
algorithm may think about it. internal algorithm may think about it.
@see IsOnline() @see IsOnline()
*/ */
@@ -156,9 +173,11 @@ public:
/** /**
This method is for Unix only. This method is for Unix only.
Under Unix, the value of well-known host is used to check whether we're 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 connected to the internet. It is unused under Windows, but this
is always safe to call. The default value is @c www.yahoo.com:80. function is always safe to call. The default value is
@c "www.yahoo.com:80".
*/ */
void SetWellKnownHost(const wxString& hostname, int portno = 80); void SetWellKnownHost(const wxString& hostname, int portno = 80);
}; };
@@ -169,8 +188,7 @@ public:
@class wxDialUpEvent @class wxDialUpEvent
@wxheader{dialup.h} @wxheader{dialup.h}
This is the event class for the dialup events sent by This is the event class for the dialup events sent by wxDialUpManager.
wxDialUpManager.
@library{wxcore} @library{wxcore}
@category{events} @category{events}
@@ -184,8 +202,8 @@ public:
wxDialUpEvent(bool isConnected, bool isOwnEvent); wxDialUpEvent(bool isConnected, bool isOwnEvent);
/** /**
Is this a @c CONNECTED or @c DISCONNECTED event? In other words, does it Is this a @c CONNECTED or @c DISCONNECTED event? In other words, does
notify about transition from offline to online state or vice versa? it notify about transition from offline to online state or vice versa?
*/ */
bool IsConnectedEvent() const; bool IsConnectedEvent() const;

251
interface/dir.h
View File

@@ -1,47 +1,57 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: dir.h // Name: dir.h
// Purpose: interface of wxDirTraverser // Purpose: interface of wxDir and wxDirTraverser
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
// Licence: wxWindows license // 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 @class wxDirTraverser
@wxheader{dir.h} @wxheader{dir.h}
wxDirTraverser is an abstract interface which must be implemented by objects wxDirTraverser is an abstract interface which must be implemented by
passed to wxDir::Traverse function. 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 @code
class wxDirTraverserSimple : public wxDirTraverser class wxDirTraverserSimple : public wxDirTraverser
{
public:
wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
virtual wxDirTraverseResult OnFile(const wxString& filename)
{ {
public: m_files.Add(filename);
wxDirTraverserSimple(wxArrayString& files) : m_files(files) { } return wxDIR_CONTINUE;
}
virtual wxDirTraverseResult OnFile(const wxString& filename) virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
{ {
m_files.Add(filename); return wxDIR_CONTINUE;
return wxDIR_CONTINUE; }
}
virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname)) private:
{ wxArrayString& m_files;
return wxDIR_CONTINUE; };
}
private: // get the names of all files in the array
wxArrayString& m_files; wxArrayString files;
}; wxDirTraverserSimple traverser(files);
// get the names of all files in the array wxDir dir(dirname);
wxArrayString files; dir.Traverse(traverser);
wxDirTraverserSimple traverser(files);
wxDir dir(dirname);
dir.Traverse(traverser);
@endcode @endcode
@library{wxbase} @library{wxbase}
@@ -51,69 +61,87 @@ class wxDirTraverser
{ {
public: public:
/** /**
This function is called for each directory. It may return @c wxDIR_STOP This function is called for each directory. It may return ::wxDIR_STOP
to abort traversing completely, @c wxDIR_IGNORE to skip this directory but to abort traversing completely, ::wxDIR_IGNORE to skip this directory
continue with others or @c wxDIR_CONTINUE to enumerate all files and but continue with others or ::wxDIR_CONTINUE to enumerate all files and
subdirectories in this directory. 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); virtual wxDirTraverseResult OnDir(const wxString& dirname);
/** /**
This function is called for each file. It may return @c wxDIR_STOP to abort This function is called for each file. It may return ::wxDIR_STOP to
traversing (for example, if the file being searched is found) or abort traversing (for example, if the file being searched is found) or
@c wxDIR_CONTINUE to proceed. ::wxDIR_CONTINUE to proceed.
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 OnFile(const wxString& filename); virtual wxDirTraverseResult OnFile(const wxString& filename);
/** /**
This function is called for each directory which we failed to open for This function is called for each directory which we failed to open for
enumerating. It may return @c wxDIR_STOP to abort traversing completely, enumerating. It may return ::wxDIR_STOP to abort traversing completely,
@c wxDIR_IGNORE to skip this directory but continue with others or ::wxDIR_IGNORE to skip this directory but continue with others or
@c wxDIR_CONTINUE to retry opening this directory once again. ::wxDIR_CONTINUE to retry opening this directory once again.
The base class version always returns @c wxDIR_IGNORE.
The base class version always returns ::wxDIR_IGNORE.
*/ */
virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname); 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 @class wxDir
@wxheader{dir.h} @wxheader{dir.h}
wxDir is a portable equivalent of Unix open/read/closedir functions which 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 allow enumerating of the files in a directory. wxDir allows to enumerate
as well as directories. files as well as directories.
wxDir also provides a flexible way to enumerate files recursively using wxDir also provides a flexible way to enumerate files recursively using
wxDir::Traverse or a simpler Traverse() or a simpler GetAllFiles() function.
wxDir::GetAllFiles function.
Example of use: Example of use:
@code @code
wxDir dir(wxGetCwd()); wxDir dir(wxGetCwd());
if ( !dir.IsOpened() ) if ( !dir.IsOpened() )
{ {
// deal with the error here - wxDir would already log an error message // deal with the error here - wxDir would already log an error message
// explaining the exact reason of the failure // explaining the exact reason of the failure
return; 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); bool cont = dir.GetFirst(&filename, filespec, flags);
while ( cont ) while ( cont )
{ {
printf("%s\n", filename.c_str()); printf("%s\n", filename.c_str());
cont = dir.GetNext(); cont = dir.GetNext(&filename);
} }
@endcode @endcode
@library{wxbase} @library{wxbase}
@@ -122,51 +150,55 @@ public:
class wxDir class wxDir
{ {
public: public:
//@{
/** /**
Opens the directory for enumeration, use IsOpened() Default constructor, use Open() afterwards.
to test for errors.
*/ */
wxDir(); wxDir();
/**
Opens the directory for enumeration, use IsOpened() to test for errors.
*/
wxDir(const wxString& dir); wxDir(const wxString& dir);
//@}
/** /**
Destructor cleans up the associated resources. It is not virtual and so this Destructor cleans up the associated resources. It is not virtual and so
class is not meant to be used polymorphically. this class is not meant to be used polymorphically.
*/ */
~wxDir(); ~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); static bool Exists(const wxString& dir);
/** /**
The function returns the path of the first file matching the given @e filespec The function returns the path of the first file matching the given
or an empty string if there are no files matching it. @a 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 @a flags parameter may or may not include ::wxDIR_FILES, the
function always behaves as if it were specified. By default, @a flags function always behaves as if it were specified. By default, @a flags
includes @c wxDIR_DIRS and so the function recurses into the subdirectories includes ::wxDIR_DIRS and so the function recurses into the
but if this flag is not specified, the function restricts the search only to subdirectories but if this flag is not specified, the function
the directory @a dirname itself. restricts the search only to the directory @a dirname itself.
See also: Traverse()
@see Traverse()
*/ */
static wxString FindFirst(const wxString& dirname, static wxString FindFirst(const wxString& dirname,
const wxString& filespec, const wxString& filespec,
int flags = wxDIR_DEFAULT); int flags = wxDIR_DEFAULT);
/** /**
The function appends the names of all the files under directory @a dirname The function appends the names of all the files under directory
to the array @a files (note that its old content is preserved). Only files @a dirname to the array @a files (note that its old content is
matching the @a filespec are taken, with empty spec matching all the files. preserved). Only files matching the @a filespec are taken, with empty
The @a flags parameter should always include @c wxDIR_FILES or the array spec matching all the files.
would be unchanged and should include @c wxDIR_DIRS flag to recurse into
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). subdirectories (both flags are included in the value by default).
See also: Traverse()
@see Traverse()
*/ */
static size_t GetAllFiles(const wxString& dirname, static size_t GetAllFiles(const wxString& dirname, wxArrayString* files,
wxArrayString* files,
const wxString& filespec = wxEmptyString, const wxString& filespec = wxEmptyString,
int flags = wxDIR_DEFAULT); int flags = wxDIR_DEFAULT);
@@ -179,76 +211,79 @@ public:
int flags = wxDIR_DEFAULT) const; int flags = wxDIR_DEFAULT) const;
/** /**
Returns the name of the directory itself. The returned string does not have the Returns the name of the directory itself. The returned string does not
trailing path separator (slash or backslash). have the trailing path separator (slash or backslash).
*/ */
wxString GetName() const; wxString GetName() const;
/** /**
Continue enumerating files which satisfy the criteria specified by the last Continue enumerating files which satisfy the criteria specified by the
call to GetFirst(). last call to GetFirst().
*/ */
bool GetNext(wxString* filename) const; bool GetNext(wxString* filename) const;
/** /**
Returns the size (in bytes) of all files recursively found in @c dir or Returns the size (in bytes) of all files recursively found in @c dir or
@c wxInvalidSize in case of error. @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 In case it happens that while traversing folders a file's size can not
skipped. be read, that file is added to the @a filesSkipped array, if not @NULL,
This usually happens with some special folders which are locked by the and then skipped. This usually happens with some special folders which
operating system are locked by the operating system or by another process. Remember that
or by another process. Remember that when @c filesSkipped-GetCount() is not when the size of @a filesSkipped is not zero, then the returned value
zero, is not 100% accurate and, if the skipped files were big, it could be
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. far from real size of the directory.
See also: wxFileName::GetHumanReadableSize,
wxGetDiskSpace() @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace()
*/ */
static wxULongLong GetTotalSize(const wxString& dir, static wxULongLong GetTotalSize(const wxString& dir,
wxArrayString* filesSkipped = NULL); wxArrayString* filesSkipped = NULL);
/** /**
Returns @true if the directory contains any files matching the given 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. case, even hidden files are taken into account.
*/ */
bool HasFiles(const wxString& filespec = wxEmptyString); bool HasFiles(const wxString& filespec = wxEmptyString);
/** /**
Returns @true if the directory contains any subdirectories (if a non 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. The hidden subdirectories are taken into account as well.
*/ */
bool HasSubDirs(const wxString& dirspec = wxEmptyString); bool HasSubDirs(const wxString& dirspec = wxEmptyString);
/** /**
Returns @true if the directory was successfully opened by a previous call to Returns @true if the directory was successfully opened by a previous
Open(). call to Open().
*/ */
bool IsOpened() const; bool IsOpened() const;
/** /**
Open the directory for enumerating, returns @true on success Open the directory for enumerating, returns @true on success or @false
or @false if an error occurred. if an error occurred.
*/ */
bool Open(const wxString& dir); bool Open(const wxString& dir);
/** /**
Enumerate all files and directories under the given directory recursively Enumerate all files and directories under the given directory
calling the element of the provided wxDirTraverser recursively calling the element of the provided wxDirTraverser object
object for each of them. for each of them.
More precisely, the function will really recurse into subdirectories if More precisely, the function will really recurse into subdirectories if
@a flags contains @c wxDIR_DIRS flag. It will ignore the files (but @a flags contains ::wxDIR_DIRS flag. It will ignore the files (but
still possibly recurse into subdirectories) if @c wxDIR_FILES flag is still possibly recurse into subdirectories) if ::wxDIR_FILES flag is
given. given.
For each found directory, @ref wxDirTraverser::ondir sink.OnDir is called
and @ref wxDirTraverser::onfile sink.OnFile is called for every file. For each found directory, @ref wxDirTraverser::OnDir() "sink.OnDir()"
Depending on the return value, the enumeration may continue or stop. is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called
The function returns the total number of files found or @c (size_t)-1 on for every file. Depending on the return value, the enumeration may
error. continue or stop.
See also: GetAllFiles()
The function returns the total number of files found or @c "(size_t)-1"
on error.
@see GetAllFiles()
*/ */
size_t Traverse(wxDirTraverser& sink, size_t Traverse(wxDirTraverser& sink,
const wxString& filespec = wxEmptyString, const wxString& filespec = wxEmptyString,

49
interface/dirctrl.h
View File

@@ -10,20 +10,35 @@
@class wxGenericDirCtrl @class wxGenericDirCtrl
@wxheader{dirctrl.h} @wxheader{dirctrl.h}
This control can be used to place a directory listing (with optional files) on This control can be used to place a directory listing (with optional
an arbitrary window. files) on an arbitrary window.
The control contains a wxTreeCtrl window representing the directory The control contains a wxTreeCtrl window representing the directory
hierarchy, and optionally, a wxChoice window containing a list of filters. 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} @library{wxbase}
@category{ctrl} @category{ctrl}
@appearance{genericdirctrl.png} <!-- @appearance{genericdirctrl.png} -->
*/ */
class wxGenericDirCtrl : public wxControl class wxGenericDirCtrl : public wxControl
{ {
public: public:
//@{ /**
Default constructor.
*/
wxGenericDirCtrl();
/** /**
Main constructor. Main constructor.
@@ -38,18 +53,17 @@ public:
@param size @param size
Size. Size.
@param style @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 @param filter
A filter string, using the same syntax as that for wxFileDialog. This may A filter string, using the same syntax as that for wxFileDialog.
be empty if filters This may be empty if filters are not being used. Example:
are not being used. @c "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg"
Example: "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg"
@param defaultFilter @param defaultFilter
The zero-indexed default filter setting. The zero-indexed default filter setting.
@param name @param name
The window name. The window name.
*/ */
wxGenericDirCtrl();
wxGenericDirCtrl(wxWindow* parent, const wxWindowID id = -1, wxGenericDirCtrl(wxWindow* parent, const wxWindowID id = -1,
const wxString& dir = wxDirDialogDefaultFolderStr, const wxString& dir = wxDirDialogDefaultFolderStr,
const wxPoint& pos = wxDefaultPosition, const wxPoint& pos = wxDefaultPosition,
@@ -58,7 +72,6 @@ public:
const wxString& filter = wxEmptyString, const wxString& filter = wxEmptyString,
int defaultFilter = 0, int defaultFilter = 0,
const wxString& name = wxTreeCtrlNameStr); const wxString& name = wxTreeCtrlNameStr);
//@}
/** /**
Destructor. Destructor.
@@ -66,7 +79,7 @@ public:
~wxGenericDirCtrl(); ~wxGenericDirCtrl();
/** /**
Collapse the given path. Collapse the given @a path.
*/ */
bool CollapsePath(const wxString& path); bool CollapsePath(const wxString& path);
@@ -76,7 +89,8 @@ public:
void CollapseTree(); 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, bool Create(wxWindow* parent, const wxWindowID id = -1,
const wxString& dir = wxDirDialogDefaultFolderStr, const wxString& dir = wxDirDialogDefaultFolderStr,
@@ -88,8 +102,8 @@ public:
const wxString& name = wxTreeCtrlNameStr); const wxString& name = wxTreeCtrlNameStr);
/** /**
Tries to expand as much of the given path as possible, so that the filename or Tries to expand as much of the given @a path as possible, so that the
directory is visible in the tree control. filename or directory is visible in the tree control.
*/ */
bool ExpandPath(const wxString& path); bool ExpandPath(const wxString& path);
@@ -100,6 +114,7 @@ public:
/** /**
Gets selected filename path only (else empty string). Gets selected filename path only (else empty string).
This function doesn't count a directory as a selection. This function doesn't count a directory as a selection.
*/ */
wxString GetFilePath() const; wxString GetFilePath() const;
@@ -140,8 +155,8 @@ public:
void Init(); void Init();
/** /**
Collapse and expand the tree, thus re-creating it from scratch. Collapse and expand the tree, thus re-creating it from scratch. May be
May be used to update the displayed directory content. used to update the displayed directory content.
*/ */
void ReCreateTree(); void ReCreateTree();

12
interface/dirdlg.h
View File

@@ -26,17 +26,19 @@
user. user.
@endStyleTable @endStyleTable
@note On Windows the new directory button is only available with recent
versions of the common dialogs.
@library{wxcore} @library{wxcore}
@category{cmndlg} @category{cmndlg}
@see @ref overview_wxdirdialogoverview "wxDirDialog overview", wxFileDialog @see @ref overview_cmndlg_dir, wxFileDialog
*/ */
class wxDirDialog : public wxDialog class wxDirDialog : public wxDialog
{ {
public: public:
/** /**
Constructor. Use ShowModal() to show Constructor. Use ShowModal() to show the dialog.
the dialog.
@param parent @param parent
Parent window. Parent window.
@@ -87,8 +89,8 @@ public:
void SetPath(const wxString& path); void SetPath(const wxString& path);
/** /**
Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL Shows the dialog, returning wxID_OK if the user pressed OK, and
otherwise. wxID_CANCEL otherwise.
*/ */
int ShowModal(); int ShowModal();
}; };

74
interface/display.h
View File

@@ -13,7 +13,7 @@
Determines the sizes and locations of displays connected to the system. Determines the sizes and locations of displays connected to the system.
@library{wxcore} @library{wxcore}
@category{FIXME} @category{misc}
@see wxClientDisplayRect(), wxDisplaySize(), wxDisplaySizeMM() @see wxClientDisplayRect(), wxDisplaySize(), wxDisplaySizeMM()
*/ */
@@ -21,11 +21,12 @@ class wxDisplay
{ {
public: public:
/** /**
Constructor, setting up a wxDisplay instance with the specified display. Constructor, setting up a wxDisplay instance with the specified
display.
@param index @param index
The index of the display to use. This must be non-negative The index of the display to use. This must be non-negative and
and lower than the value returned by GetCount(). lower than the value returned by GetCount().
*/ */
wxDisplay(unsigned index = 0); wxDisplay(unsigned index = 0);
@@ -35,27 +36,28 @@ public:
~wxDisplay(); ~wxDisplay();
/** /**
Changes the video mode of this display to the mode specified Changes the video mode of this display to the mode specified in the
in the mode parameter. mode parameter.
If wxDefaultVideoMode is passed in as the mode parameter,
the defined behaviour is that wxDisplay will reset the video If wxDefaultVideoMode is passed in as the mode parameter, the defined
mode to the default mode used by the display. On Windows, behaviour is that wxDisplay will reset the video mode to the default
the behavior is normal. However, there are differences on other mode used by the display. On Windows, the behavior is normal. However,
platforms. On Unix variations using X11 extensions it should there are differences on other platforms. On Unix variations using X11
behave as defined, but some irregularities may occur. extensions it should behave as defined, but some irregularities may
On wxMac passing in wxDefaultVideoMode as the mode occur.
parameter does nothing. This happens because carbon
no longer has access to DMUseScreenPrefs, an undocumented On wxMac passing in wxDefaultVideoMode as the mode parameter does
function that changed the video mode to the system nothing. This happens because carbon no longer has access to
default by using the system's 'scrn' resource. @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); bool ChangeMode(const wxVideoMode& mode = wxDefaultVideoMode);
/** /**
Returns the client area of the display. The client area is the part of the Returns the client area of the display. The client area is the part of
display available for the normal (non full screen) windows, usually it is the the display available for the normal (non full screen) windows, usually
same as GetGeometry() but it could be less if it is the same as GetGeometry() but it could be less if there is a
there is a taskbar (or equivalent) on this display. taskbar (or equivalent) on this display.
*/ */
wxRect GetClientArea() const; wxRect GetClientArea() const;
@@ -70,12 +72,13 @@ public:
wxVideoMode GetCurrentMode() const; 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; 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. @c wxNOT_FOUND if the point is not on any connected display.
@param pt @param pt
@@ -85,8 +88,10 @@ public:
/** /**
Returns the index of the display on which the given window lies. 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. Returns @c wxNOT_FOUND if the window is not on any connected display.
@param win @param win
@@ -95,27 +100,28 @@ public:
static int GetFromWindow(const wxWindow* win); static int GetFromWindow(const wxWindow* win);
/** /**
Returns the bounding rectangle of the display whose index was passed to the Returns the bounding rectangle of the display whose index was passed to
constructor. the constructor.
@see GetClientArea(), wxDisplaySize()
*/ */
wxRect GetGeometry() const; wxRect GetGeometry() const;
/** /**
Fills and returns an array with all the video modes that Fills and returns an array with all the video modes that are supported
are supported by this display, or video modes that are by this display, or video modes that are supported by this display and
supported by this display and match the mode parameter match the mode parameter (if mode is not wxDefaultVideoMode).
(if mode is not wxDefaultVideoMode).
*/ */
wxArrayVideoModes GetModes(const wxVideoMode& mode = wxDefaultVideoMode) const; 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; wxString GetName() const;
/** /**
Returns @true if the display is the primary display. The primary display is the Returns @true if the display is the primary display. The primary
one whose index is 0. display is the one whose index is 0.
*/ */
bool IsPrimary(); bool IsPrimary();
}; };

198
interface/dnd.h
View File

@@ -1,6 +1,6 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: dnd.h // Name: dnd.h
// Purpose: interface of wxTextDropTarget // Purpose: interface of wxDropSource and wx*DropTarget
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
// Licence: wxWindows license // Licence: wxWindows license
@@ -15,7 +15,7 @@
@library{wxcore} @library{wxcore}
@category{dnd} @category{dnd}
@see @ref overview_wxdndoverview, wxDropSource, wxDropTarget, wxFileDropTarget @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget
*/ */
class wxTextDropTarget : public wxDropTarget class wxTextDropTarget : public wxDropTarget
{ {
@@ -26,8 +26,8 @@ public:
wxTextDropTarget(); wxTextDropTarget();
/** /**
See wxDropTarget::OnDrop. This function is implemented See wxDropTarget::OnDrop(). This function is implemented appropriately
appropriately for text, and calls OnDropText(). for text, and calls OnDropText().
*/ */
virtual bool OnDrop(long x, long y, const void data, size_t size); virtual bool OnDrop(long x, long y, const void data, size_t size);
@@ -40,41 +40,47 @@ public:
The y coordinate of the mouse. The y coordinate of the mouse.
@param data @param data
The data being dropped: a wxString. 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, virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data);
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 @class wxDropTarget
@wxheader{dnd.h} @wxheader{dnd.h}
This class represents a target for a drag and drop operation. A wxDataObject This class represents a target for a drag and drop operation. A
can be associated with it and by default, this object will be filled with the wxDataObject can be associated with it and by default, this object will be
data from the filled with the data from the drag source, if the data formats supported by
drag source, if the data formats supported by the data object match the drag the data object match the drag source data format.
source data
format.
There are various virtual handler functions defined in this class which may be There are various virtual handler functions defined in this class which may
overridden be overridden to give visual feedback or react in a more fine-tuned way,
to give visual feedback or react in a more fine-tuned way, e.g. by not e.g. by not accepting data on the whole window area, but only a small
accepting data on portion of it. The normal sequence of calls is OnEnter(), OnDragOver()
the whole window area, but only a small portion of it. The normal sequence of possibly many times, OnDrop() and finally OnData().
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.
@library{wxcore} @library{wxcore}
@category{dnd} @category{dnd}
@see wxDropSource, wxTextDropTarget, wxFileDropTarget, wxDataFormat, @see @ref overview_dnd, @ref overview_dataobject, wxDropSource,
wxDataObject wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject
*/ */
class wxDropTarget class wxDropTarget
{ {
@@ -90,49 +96,47 @@ public:
~wxDropTarget(); ~wxDropTarget();
/** /**
This method may only be called from within OnData(). This method may only be called from within OnData(). By default, this
By default, this method copies the data from the drop source to the method copies the data from the drop source to the wxDataObject
wxDataObject associated with this drop target, associated with this drop target, calling its wxDataObject::SetData()
calling its wxDataObject::SetData method. method.
*/ */
virtual void GetData(); virtual void GetData();
/** /**
Called after OnDrop() returns @true. By default this Called after OnDrop() returns @true. By default this will usually
will usually GetData() and will return the suggested GetData() and will return the suggested default value @a def.
default value @e def.
*/ */
virtual wxDragResult OnData(wxCoord x, wxCoord y, virtual wxDragResult OnData(wxCoord x, wxCoord y, wxDragResult def);
wxDragResult def);
/** /**
Called when the mouse is being dragged over the drop target. By default, Called when the mouse is being dragged over the drop target. By
this calls functions return the suggested return value @e def. default, this calls functions return the suggested return value @a def.
@param x @param x
The x coordinate of the mouse. The x coordinate of the mouse.
@param y @param y
The y coordinate of the mouse. The y coordinate of the mouse.
@param def @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 @returns The desired operation or wxDragNone. This is used for optical
optical feedback from the side of the drop source, feedback from the side of the drop source, typically in form
typically in form of changing the icon. of changing the icon.
*/ */
virtual wxDragResult OnDragOver(wxCoord x, wxCoord y, virtual wxDragResult OnDragOver(wxCoord x, wxCoord y, wxDragResult def);
wxDragResult def);
/** /**
Called when the user drops a data object on the target. Return @false to veto Called when the user drops a data object on the target. Return @false
the operation. to veto the operation.
@param x @param x
The x coordinate of the mouse. The x coordinate of the mouse.
@param y @param y
The y coordinate of the mouse. 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); virtual bool OnDrop(wxCoord x, wxCoord y);
@@ -145,15 +149,14 @@ public:
@param y @param y
The y coordinate of the mouse. The y coordinate of the mouse.
@param def @param def
Suggested default for return value. Determined by SHIFT or CONTROL key Suggested default for return value. Determined by SHIFT or CONTROL
states. key states.
@returns Returns the desired operation or wxDragNone. This is used for @returns The desired operation or wxDragNone. This is used for optical
optical feedback from the side of the drop source, feedback from the side of the drop source, typically in form
typically in form of changing the icon. of changing the icon.
*/ */
virtual wxDragResult OnEnter(wxCoord x, wxCoord y, virtual wxDragResult OnEnter(wxCoord x, wxCoord y, wxDragResult def);
wxDragResult def);
/** /**
Called when the mouse leaves the drop target. Called when the mouse leaves the drop target.
@@ -161,8 +164,8 @@ public:
virtual void OnLeave(); virtual void OnLeave();
/** /**
Sets the data wxDataObject associated with the Sets the data wxDataObject associated with the drop target and deletes
drop target and deletes any previously associated data object. any previously associated data object.
*/ */
void SetDataObject(wxDataObject* data); void SetDataObject(wxDataObject* data);
}; };
@@ -175,25 +178,21 @@ public:
This class represents a source for a drag and drop operation. This class represents a source for a drag and drop operation.
See @ref overview_wxdndoverview and @ref overview_wxdataobjectoverview
for more information.
@library{wxcore} @library{wxcore}
@category{dnd} @category{dnd}
@see wxDropTarget, wxTextDropTarget, wxFileDropTarget @see @ref overview_dnd, @ref overview_dataobject, wxDropTarget,
wxTextDropTarget, wxFileDropTarget
*/ */
class wxDropSource class wxDropSource
{ {
public: public:
//@{
/** /**
The constructors for wxDataObject. This constructor requires that you must call SetData() later.
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
Note that the exact type of @a iconCopy and subsequent parameters differs differs between wxMSW and wxGTK: these are cursors under Windows but
between wxMSW and wxGTK: these are cursors under Windows but icons for GTK. icons for GTK. You should use the macro wxDROP_ICON() in portable
You should use the macro wxDROP_ICON() in portable
programs instead of directly using either of these types. programs instead of directly using either of these types.
@param win @param win
@@ -209,30 +208,44 @@ public:
const wxIconOrCursor& iconCopy = wxNullIconOrCursor, const wxIconOrCursor& iconCopy = wxNullIconOrCursor,
const wxIconOrCursor& iconMove = wxNullIconOrCursor, const wxIconOrCursor& iconMove = wxNullIconOrCursor,
const wxIconOrCursor& iconNone = 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, wxDropSource(wxDataObject& data, wxWindow* win = NULL,
const wxIconOrCursor& iconCopy = wxNullIconOrCursor, const wxIconOrCursor& iconCopy = wxNullIconOrCursor,
const wxIconOrCursor& iconMove = wxNullIconOrCursor, const wxIconOrCursor& iconMove = wxNullIconOrCursor,
const wxIconOrCursor& iconNone = wxNullIconOrCursor); const wxIconOrCursor& iconNone = wxNullIconOrCursor);
//@}
/** /**
Default constructor.
*/ */
~wxDropSource(); ~wxDropSource();
/** /**
Do it (call this in response to a mouse button press, for example). This starts Starts the drag-and-drop operation which will terminate when the user
the drag-and-drop operation which will terminate when the user releases the releases the mouse. Call this in response to a mouse button press, for
mouse. example.
@param flags @param flags
If wxDrag_AllowMove is included in the flags, data may If wxDrag_AllowMove is included in the flags, data may be moved and
be moved and not only copied (default). If wxDrag_DefaultMove is not only copied (default). If wxDrag_DefaultMove is specified
specified (which includes the previous flag), this is even the default (which includes the previous flag), this is even the default
operation operation.
@returns Returns the operation requested by the user, may be wxDragCopy, @returns The operation requested by the user, may be ::wxDragCopy,
wxDragMove, wxDragLink, wxDragCancel or wxDragNone if ::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if
an error occurred. an error occurred.
*/ */
virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly); virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly);
@@ -243,21 +256,18 @@ public:
wxDataObject* GetDataObject(); wxDataObject* GetDataObject();
/** /**
Overridable: you may give some custom UI feedback during the drag and drop You may give some custom UI feedback during the drag and drop operation
operation by overriding this function. It is called on each mouse move, so your
in this function. It is called on each mouse move, so your implementation must implementation must not be too slow.
not be too
slow.
@param effect @param effect
The effect to implement. One of wxDragCopy, wxDragMove, wxDragLink and The effect to implement. One of ::wxDragCopy, ::wxDragMove,
wxDragNone. ::wxDragLink and ::wxDragNone.
@param scrolling @param scrolling
@true if the window is scrolling. MSW only. @true if the window is scrolling. MSW only.
@returns Return @false if you want default feedback, or @true if you @returns @false if you want default feedback, or @true if you implement
implement your own feedback. The return values is your own feedback. The return values is ignored under GTK.
ignored under GTK.
*/ */
virtual bool GiveFeedback(wxDragResult effect); virtual bool GiveFeedback(wxDragResult effect);
@@ -272,8 +282,8 @@ public:
void SetCursor(wxDragResult res, const wxCursor& cursor); void SetCursor(wxDragResult res, const wxCursor& cursor);
/** /**
Sets the data wxDataObject associated with the Sets the data wxDataObject associated with the drop source. This will
drop source. This will not delete any previously associated data. not delete any previously associated data.
*/ */
void SetData(wxDataObject& data); void SetData(wxDataObject& data);
}; };
@@ -284,13 +294,13 @@ public:
@class wxFileDropTarget @class wxFileDropTarget
@wxheader{dnd.h} @wxheader{dnd.h}
This is a @ref overview_wxdroptarget "drop target" which accepts files (dragged This is a drop target which accepts files (dragged from File Manager or
from File Manager or Explorer). Explorer).
@library{wxcore} @library{wxcore}
@category{dnd} @category{dnd}
@see @ref overview_wxdndoverview, wxDropSource, wxDropTarget, wxTextDropTarget @see @ref overview_dnd, wxDropSource, wxDropTarget, wxTextDropTarget
*/ */
class wxFileDropTarget : public wxDropTarget class wxFileDropTarget : public wxDropTarget
{ {
@@ -301,8 +311,8 @@ public:
wxFileDropTarget(); wxFileDropTarget();
/** /**
See wxDropTarget::OnDrop. This function is implemented See wxDropTarget::OnDrop(). This function is implemented appropriately
appropriately for files, and calls OnDropFiles(). for files, and calls OnDropFiles().
*/ */
virtual bool OnDrop(long x, long y, const void data, size_t size); virtual bool OnDrop(long x, long y, const void data, size_t size);
@@ -315,6 +325,8 @@ public:
The y coordinate of the mouse. The y coordinate of the mouse.
@param filenames @param filenames
An array of filenames. An array of filenames.
Return @true to accept the data, or @false to veto the operation.
*/ */
virtual bool OnDropFiles(wxCoord x, wxCoord y, virtual bool OnDropFiles(wxCoord x, wxCoord y,
const wxArrayString& filenames); const wxArrayString& filenames);