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

134
interface/dialup.h
View File

@@ -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,9 +120,11 @@ 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
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.
*/
@@ -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;

187
interface/dir.h
View File

@@ -1,19 +1,29 @@
/////////////////////////////////////////////////////////////////////////////
// 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
@@ -51,45 +61,63 @@ 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:
@@ -107,12 +135,12 @@ public:
wxString filename;
bool cont = dir.GetFirst(, filespec, flags);
bool cont = dir.GetFirst(&filename, filespec, flags);
while ( cont )
{
printf("%s\n", filename.c_str());
cont = dir.GetNext();
cont = dir.GetNext(&filename);
}
@endcode
@@ -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,

49
interface/dirctrl.h
View File

@@ -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}
<!-- @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();

12
interface/dirdlg.h
View File

@@ -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();
};

72
interface/display.h
View File

@@ -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,16 +100,17 @@ 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;
@@ -114,8 +120,8 @@ public:
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();
};

198
interface/dnd.h
View File

@@ -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.
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.
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);