@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
{
~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,
/**
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;
bool HangUp();
/**
- Returns @true if the computer has a permanent network connection (i.e. is
- on a LAN) and so there is no need to use Dial() function to go online.
- @note this functions tries to guess the result and it is not always
- guaranteed to be correct, so it is better to ask user for
- confirmation or give him a possibility to override it.
+ Returns @true if the computer has a permanent network connection (i.e.
+ is on a LAN) and so there is no need to use Dial() function to go
+ online.
+
+ @note This function tries to guess the result and it is not always
+ guaranteed to be correct, so it is better to ask user for
+ confirmation or give him a possibility to override it.
*/
bool IsAlwaysOnline() const;
/**
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()
*/
/**
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);
};
@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}
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;
/////////////////////////////////////////////////////////////////////////////
// Name: dir.h
-// Purpose: interface of wxDirTraverser
+// Purpose: interface of wxDir and wxDirTraverser
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+/**
+ Possible return values of wxDirTraverser callback functions.
+*/
+enum wxDirTraverseResult
+{
+ wxDIR_IGNORE = -1, ///< Ignore this directory but continue with others.
+ wxDIR_STOP, ///< Stop traversing.
+ wxDIR_CONTINUE ///< Continue into this directory.
+};
+
/**
@class wxDirTraverser
@wxheader{dir.h}
- wxDirTraverser is an abstract interface which must be implemented by objects
- passed to wxDir::Traverse function.
+ wxDirTraverser is an abstract interface which must be implemented by
+ objects passed to wxDir::Traverse() function.
- Example of use (this works almost like wxDir::GetAllFiles):
+ Example of use (this works almost like wxDir::GetAllFiles()):
@code
class wxDirTraverserSimple : public wxDirTraverser
+ {
+ public:
+ wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
+
+ virtual wxDirTraverseResult OnFile(const wxString& filename)
{
- public:
- wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
-
- virtual wxDirTraverseResult OnFile(const wxString& filename)
- {
- m_files.Add(filename);
- return wxDIR_CONTINUE;
- }
-
- virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
- {
- return wxDIR_CONTINUE;
- }
-
- private:
- wxArrayString& m_files;
- };
-
- // get the names of all files in the array
- wxArrayString files;
- wxDirTraverserSimple traverser(files);
-
- wxDir dir(dirname);
- dir.Traverse(traverser);
+ m_files.Add(filename);
+ return wxDIR_CONTINUE;
+ }
+
+ virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
+ {
+ return wxDIR_CONTINUE;
+ }
+
+ private:
+ wxArrayString& m_files;
+ };
+
+ // get the names of all files in the array
+ wxArrayString files;
+ wxDirTraverserSimple traverser(files);
+
+ wxDir dir(dirname);
+ dir.Traverse(traverser);
@endcode
@library{wxbase}
{
public:
/**
- This function is called for each directory. It may return @c wxDIR_STOP
- to abort traversing completely, @c wxDIR_IGNORE to skip this directory but
- continue with others or @c wxDIR_CONTINUE to enumerate all files and
+ This function is called for each directory. It may return ::wxDIR_STOP
+ to abort traversing completely, ::wxDIR_IGNORE to skip this directory
+ but continue with others or ::wxDIR_CONTINUE to enumerate all files and
subdirectories in this directory.
- This is a pure virtual function and must be implemented in the derived class.
+
+ This is a pure virtual function and must be implemented in the derived
+ class.
*/
virtual wxDirTraverseResult OnDir(const wxString& dirname);
/**
- This function is called for each file. It may return @c wxDIR_STOP to abort
- traversing (for example, if the file being searched is found) or
- @c wxDIR_CONTINUE to proceed.
- This is a pure virtual function and must be implemented in the derived class.
+ This function is called for each file. It may return ::wxDIR_STOP to
+ abort traversing (for example, if the file being searched is found) or
+ ::wxDIR_CONTINUE to proceed.
+
+ This is a pure virtual function and must be implemented in the derived
+ class.
*/
virtual wxDirTraverseResult OnFile(const wxString& filename);
/**
This function is called for each directory which we failed to open for
- enumerating. It may return @c wxDIR_STOP to abort traversing completely,
- @c wxDIR_IGNORE to skip this directory but continue with others or
- @c wxDIR_CONTINUE to retry opening this directory once again.
- The base class version always returns @c wxDIR_IGNORE.
+ enumerating. It may return ::wxDIR_STOP to abort traversing completely,
+ ::wxDIR_IGNORE to skip this directory but continue with others or
+ ::wxDIR_CONTINUE to retry opening this directory once again.
+
+ The base class version always returns ::wxDIR_IGNORE.
*/
virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname);
};
+/**
+ These flags define what kind of filenames are included in the list of files
+ enumerated by wxDir::GetFirst() and wxDir::GetNext().
+*/
+enum
+{
+ wxDIR_FILES = 0x0001, ///< Includes files.
+ wxDIR_DIRS = 0x0002, ///< Includes directories.
+ wxDIR_HIDDEN = 0x0004, ///< Includes hidden files.
+ wxDIR_DOTDOT = 0x0008, ///< Includes "." and "..".
+
+ wxDIR_DEFAULT = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
+};
+
/**
@class wxDir
@wxheader{dir.h}
wxDir is a portable equivalent of Unix open/read/closedir functions which
- allow enumerating of the files in a directory. wxDir allows to enumerate files
- as well as directories.
+ allow enumerating of the files in a directory. wxDir allows to enumerate
+ files as well as directories.
wxDir also provides a flexible way to enumerate files recursively using
- wxDir::Traverse or a simpler
- wxDir::GetAllFiles function.
+ Traverse() or a simpler GetAllFiles() function.
Example of use:
@code
wxDir dir(wxGetCwd());
- if ( !dir.IsOpened() )
- {
- // deal with the error here - wxDir would already log an error message
- // explaining the exact reason of the failure
- return;
- }
+ if ( !dir.IsOpened() )
+ {
+ // deal with the error here - wxDir would already log an error message
+ // explaining the exact reason of the failure
+ return;
+ }
- puts("Enumerating object files in current directory:");
+ puts("Enumerating object files in current directory:");
- wxString filename;
+ wxString filename;
- bool cont = dir.GetFirst(, filespec, flags);
- while ( cont )
- {
- printf("%s\n", filename.c_str());
+ bool cont = dir.GetFirst(&filename, filespec, flags);
+ while ( cont )
+ {
+ printf("%s\n", filename.c_str());
- cont = dir.GetNext();
- }
+ cont = dir.GetNext(&filename);
+ }
@endcode
@library{wxbase}
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);
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,
@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.
@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,
const wxString& filter = wxEmptyString,
int defaultFilter = 0,
const wxString& name = wxTreeCtrlNameStr);
- //@}
/**
Destructor.
~wxGenericDirCtrl();
/**
- Collapse the given path.
+ Collapse the given @a path.
*/
bool CollapsePath(const wxString& path);
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,
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);
/**
Gets selected filename path only (else empty string).
+
This function doesn't count a directory as a selection.
*/
wxString GetFilePath() const;
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();
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.
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();
};
Determines the sizes and locations of displays connected to the system.
@library{wxcore}
- @category{FIXME}
+ @category{misc}
@see wxClientDisplayRect(), wxDisplaySize(), wxDisplaySizeMM()
*/
{
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);
~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;
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
/**
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
static int GetFromWindow(const wxWindow* win);
/**
- Returns the bounding rectangle of the display whose index was passed to the
- constructor.
+ Returns the bounding rectangle of the display whose index was passed to
+ the constructor.
+
+ @see GetClientArea(), wxDisplaySize()
*/
wxRect GetGeometry() const;
/**
- Fills and returns an array with all the video modes that
- are supported by this display, or video modes that are
- supported by this display and match the mode parameter
- (if mode is not wxDefaultVideoMode).
+ Fills and returns an array with all the video modes that are supported
+ by this display, or video modes that are supported by this display and
+ match the mode parameter (if mode is not wxDefaultVideoMode).
*/
wxArrayVideoModes GetModes(const wxVideoMode& mode = wxDefaultVideoMode) const;
/**
- Returns the display's name. A name is not available on all platforms.
+ Returns the display's name. A name is not available on all platforms.
*/
wxString GetName() const;
/**
- Returns @true if the display is the primary display. The primary display is the
- one whose index is 0.
+ Returns @true if the display is the primary display. The primary
+ display is the one whose index is 0.
*/
bool IsPrimary();
};
/////////////////////////////////////////////////////////////////////////////
// Name: dnd.h
-// Purpose: interface of wxTextDropTarget
+// Purpose: interface of wxDropSource and wx*DropTarget
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
@library{wxcore}
@category{dnd}
- @see @ref overview_wxdndoverview, wxDropSource, wxDropTarget, wxFileDropTarget
+ @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget
*/
class wxTextDropTarget : public wxDropTarget
{
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);
The y coordinate of the mouse.
@param data
The data being dropped: a wxString.
+
+ Return @true to accept the data, or @false to veto the operation.
*/
- virtual bool OnDropText(wxCoord x, wxCoord y,
- const wxString& data);
+ virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data);
};
+/**
+ Result returned from a wxDropSource::DoDragDrop() call.
+*/
+enum wxDragResult
+{
+ wxDragError, ///< Error prevented the D&D operation from completing.
+ wxDragNone, ///< Drag target didn't accept the data.
+ wxDragCopy, ///< The data was successfully copied.
+ wxDragMove, ///< The data was successfully moved (MSW only).
+ wxDragLink, ///< Operation is a drag-link.
+ wxDragCancel ///< The operation was cancelled by user (not an error).
+};
+
/**
@class wxDropTarget
@wxheader{dnd.h}
- This class represents a target for a drag and drop operation. A wxDataObject
- can be associated with it and by default, this object will be filled with the
- data from the
- drag source, if the data formats supported by the data object match the drag
- source data
- format.
-
- There are various virtual handler functions defined in this class which may be
- overridden
- to give visual feedback or react in a more fine-tuned way, e.g. by not
- accepting data on
- the whole window area, but only a small portion of it. The normal sequence of
- calls is
- wxDropTarget::OnEnter, possibly many times wxDropTarget::OnDragOver,
- wxDropTarget::OnDrop and finally wxDropTarget::OnData.
-
- See @ref overview_wxdndoverview and @ref overview_wxdataobjectoverview
- for more information.
+ This class represents a target for a drag and drop operation. A
+ wxDataObject can be associated with it and by default, this object will be
+ filled with the data from the drag source, if the data formats supported by
+ the data object match the drag source data format.
+
+ There are various virtual handler functions defined in this class which may
+ be overridden to give visual feedback or react in a more fine-tuned way,
+ e.g. by not accepting data on the whole window area, but only a small
+ portion of it. The normal sequence of calls is OnEnter(), OnDragOver()
+ possibly many times, OnDrop() and finally OnData().
@library{wxcore}
@category{dnd}
- @see wxDropSource, wxTextDropTarget, wxFileDropTarget, wxDataFormat,
- wxDataObject
+ @see @ref overview_dnd, @ref overview_dataobject, wxDropSource,
+ wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject
*/
class wxDropTarget
{
~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);
@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.
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);
};
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
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);
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);
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);
};
@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
{
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);
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);
projects / wxWidgets.git / commitdiff
