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

add wxPosixPermissions enumeration; it provides more readable synonims for wxS_I* flags and makes it easier to document which flags can be used in wxFile functions and wxFileName::Mkdir (and in future wxFileName::Chmod)

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@55908 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-09-27 10:27:44 +00:00
parent 5fed01a943
commit f41d6c8cd7
10 changed files with 811 additions and 465 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
interface/wx/file.h
View File

@@ -7,25 +7,56 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
//@{
/** /**
These constants define the file access rights and are used with wxFile::Create and wxFile::Open. We redefine these constants here because S_IREAD &c are _not_ standard
however, we do assume that the values correspond to the Unix umask bits.
*/ */
#define wxS_IRUSR 00400 enum wxPosixPermissions
#define wxS_IWUSR 00200 {
#define wxS_IXUSR 00100 /// standard Posix names for these permission flags
//@{
wxS_IRUSR = 00400,
wxS_IWUSR = 00200,
wxS_IXUSR = 00100,
#define wxS_IRGRP 00040 wxS_IRGRP = 00040,
#define wxS_IWGRP 00020 wxS_IWGRP = 00020,
#define wxS_IXGRP 00010 wxS_IXGRP = 00010,
#define wxS_IROTH 00004 wxS_IROTH = 00004,
#define wxS_IWOTH 00002 wxS_IWOTH = 00002,
#define wxS_IXOTH 00001 wxS_IXOTH = 00001,
//@}
/** Default mode for the new files: corresponds to umask 022 */ /// longer but more readable synonims for the constants above
#define wxS_DEFAULT (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH) //@{
//@} wxPOSIX_USER_READ = wxS_IRUSR,
wxPOSIX_USER_WRITE = wxS_IWUSR,
wxPOSIX_USER_EXECUTE = wxS_IXUSR,
wxPOSIX_GROUP_READ = wxS_IRGRP,
wxPOSIX_GROUP_WRITE = wxS_IWGRP,
wxPOSIX_GROUP_EXECUTE = wxS_IXGRP,
wxPOSIX_OTHERS_READ = wxS_IROTH,
wxPOSIX_OTHERS_WRITE = wxS_IWOTH,
wxPOSIX_OTHERS_EXECUTE = wxS_IXOTH,
//@}
/// Default mode for the new files: allow reading/writing them to everybody but
/// the effective file mode will be set after anding this value with umask and
/// so won't include wxS_IW{GRP,OTH} for the default 022 umask value
wxS_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | \
wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | \
wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE),
/// Default mode for the new directories (see wxFileName::Mkdir): allow
/// reading/writing/executing them to everybody, but just like wxS_DEFAULT
/// the effective directory mode will be set after anding this value with umask
wxS_DIR_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | wxPOSIX_USER_EXECUTE | \
wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | wxPOSIX_GROUP_EXECUTE | \
wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE | wxPOSIX_OTHERS_EXECUTE)
};
@@ -274,8 +305,8 @@ public:
If the file already exists, setting @b overwrite to @true will ensure If the file already exists, setting @b overwrite to @true will ensure
it is overwritten. it is overwritten.
@a access may be an OR combination of the file access values @a access may be an OR combination of the ::wxPosixPermissions enumeration
like ::wxS_IRUSR, ::wxS_IWUSR, etc, etc. values.
*/ */
bool Create(const wxString& filename, bool Create(const wxString& filename,
bool overwrite = false, bool overwrite = false,
@@ -343,9 +374,12 @@ public:
The filename. The filename.
@param mode @param mode
The mode in which to open the file. The mode in which to open the file.
@param access
An OR-combination of wxPosixPermissions enumeration values.
*/ */
bool Open(const wxString& filename, bool Open(const wxString& filename,
wxFile::OpenMode mode = wxFile::read); wxFile::OpenMode mode = wxFile::read,
int access = wxS_DEFAULT);
/** /**
Reads from the file into a memory buffer. Reads from the file into a memory buffer.

14
interface/wx/filename.h
View File

@@ -830,7 +830,8 @@ public:
Creates a directory. Creates a directory.
@param perm @param perm
The permissions for the newly created directory The permissions for the newly created directory.
See wxPosixPermissions enumeration for more info.
@param flags @param flags
If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each
directory in the path and also don't return an error if the target directory in the path and also don't return an error if the target
@@ -839,24 +840,25 @@ public:
@return Returns @true if the directory was successfully created, @false @return Returns @true if the directory was successfully created, @false
otherwise. otherwise.
*/ */
bool Mkdir(int perm = 0777, int flags = 0); bool Mkdir(int perm = wxS_DIR_DEFAULT, int flags = 0);
/** /**
Creates a directory. Creates a directory.
@param dir @param dir
the directory to create The directory to create
@param parm @param parm
the permissions for the newly created directory The permissions for the newly created directory.
See wxPosixPermissions enumeration for more info.
@param flags @param flags
if the flags contain @c wxPATH_MKDIR_FULL flag, try to create each If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each
directory in the path and also don't return an error if the target directory in the path and also don't return an error if the target
directory already exists. directory already exists.
@return Returns @true if the directory was successfully created, @false @return Returns @true if the directory was successfully created, @false
otherwise. otherwise.
*/ */
static bool Mkdir(const wxString& dir, int perm = 0777, static bool Mkdir(const wxString& dir, int perm = wxS_DIR_DEFAULT,
int flags = 0); int flags = 0);
/** /**

108
interface/wx/window.h
View File

@@ -399,7 +399,6 @@ public:
*/ */
void ClearBackground(); void ClearBackground();
//@{
/** /**
Converts to screen coordinates from coordinates relative to this window. Converts to screen coordinates from coordinates relative to this window.
@@ -409,8 +408,6 @@ public:
@param y @param y
A pointer to a integer value for the y coordinate. Pass the client A pointer to a integer value for the y coordinate. Pass the client
coordinate in, and a screen coordinate will be passed out. coordinate in, and a screen coordinate will be passed out.
@param pt
The client position for the second form of the function.
@beginWxPythonOnly @beginWxPythonOnly
In place of a single overloaded method name, wxPython implements the following methods: In place of a single overloaded method name, wxPython implements the following methods:
@@ -419,8 +416,14 @@ public:
@endWxPythonOnly @endWxPythonOnly
*/ */
void ClientToScreen(int* x, int* y) const; void ClientToScreen(int* x, int* y) const;
/**
Converts to screen coordinates from coordinates relative to this window.
@param pt
The client position for the second form of the function.
*/
wxPoint ClientToScreen(const wxPoint& pt) const; wxPoint ClientToScreen(const wxPoint& pt) const;
//@}
/** /**
Converts client area size @a size to corresponding window size. Converts client area size @a size to corresponding window size.
@@ -1083,7 +1086,6 @@ public:
*/ */
virtual wxWindow* GetParent() const; virtual wxWindow* GetParent() const;
//@{
/** /**
This function shows a popup menu at the given position in this window and This function shows a popup menu at the given position in this window and
returns the selected id. It can be more convenient than the general purpose returns the selected id. It can be more convenient than the general purpose
@@ -1094,19 +1096,19 @@ public:
The menu to show The menu to show
@param pos @param pos
The position at which to show the menu in client coordinates The position at which to show the menu in client coordinates
@param x
The horizontal position of the menu
@param y
The vertical position of the menu
@return The selected menu item id or wxID_NONE if none selected or an @return The selected menu item id or wxID_NONE if none selected or an
error occurred. error occurred.
*/ */
int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos); int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos);
int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y);
//@}
//@{ /**
See the GetPopupMenuSelectionFromUser(wxMenu&, const wxPoint&) overload.
This overload differs only because it takes two integers for the
menu position instead of a wxPoint.
*/
int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y);
/** /**
This gets the position of the window in pixels, relative to the parent window This gets the position of the window in pixels, relative to the parent window
for the child windows or relative to the display origin for the top level windows. for the child windows or relative to the display origin for the top level windows.
@@ -1119,8 +1121,14 @@ public:
@see GetScreenPosition() @see GetScreenPosition()
*/ */
void GetPosition(int* x, int* y) const; void GetPosition(int* x, int* y) const;
/**
This gets the position of the window in pixels, relative to the parent window
for the child windows or relative to the display origin for the top level windows.
@see GetScreenPosition()
*/
wxPoint GetPosition() const; wxPoint GetPosition() const;
//@}
/** /**
Returns the previous window before this one among the parent children or @c Returns the previous window before this one among the parent children or @c
@@ -1139,7 +1147,6 @@ public:
*/ */
wxRect GetRect() const; wxRect GetRect() const;
//@{
/** /**
Returns the window position in screen coordinates, whether the window is a Returns the window position in screen coordinates, whether the window is a
child window or a top level one. child window or a top level one.
@@ -1152,8 +1159,14 @@ public:
@see GetPosition() @see GetPosition()
*/ */
void GetScreenPosition(int* x, int* y) const; void GetScreenPosition(int* x, int* y) const;
/**
Returns the window position in screen coordinates, whether the window is a
child window or a top level one.
@see GetPosition()
*/
wxPoint GetScreenPosition() const; wxPoint GetScreenPosition() const;
//@}
/** /**
Returns the position and size of the window on the screen as a wxRect object. Returns the position and size of the window on the screen as a wxRect object.
@@ -1183,7 +1196,6 @@ public:
*/ */
virtual int GetScrollThumb(int orientation); virtual int GetScrollThumb(int orientation);
//@{
/** /**
Returns the size of the entire window in pixels, including title bar, border, Returns the size of the entire window in pixels, including title bar, border,
scrollbars, etc. scrollbars, etc.
@@ -1199,8 +1211,11 @@ public:
@see GetClientSize(), GetVirtualSize() @see GetClientSize(), GetVirtualSize()
*/ */
void GetSize(int* width, int* height) const; void GetSize(int* width, int* height) const;
/**
See the GetSize(int*,int*) overload for more info.
*/
wxSize GetSize() const; wxSize GetSize() const;
//@}
/** /**
Return the sizer associated with the window by a previous call to Return the sizer associated with the window by a previous call to
@@ -1208,7 +1223,6 @@ public:
*/ */
wxSizer* GetSizer() const; wxSizer* GetSizer() const;
//@{
/** /**
Gets the dimensions of the string as it would be drawn on the Gets the dimensions of the string as it would be drawn on the
window with the currently selected font. window with the currently selected font.
@@ -1241,7 +1255,6 @@ public:
window with the currently selected font. window with the currently selected font.
*/ */
wxSize GetTextExtent(const wxString& string) const; wxSize GetTextExtent(const wxString& string) const;
//@}
/** /**
Get the associated tooltip or @NULL if none. Get the associated tooltip or @NULL if none.
@@ -2379,31 +2392,29 @@ public:
@param refresh @param refresh
@true to redraw the scrollbar, @false otherwise. @true to redraw the scrollbar, @false otherwise.
@remarks Let's say you wish to display 50 lines of text, using the same @remarks
font. The window is sized so that you can only see 16 Let's say you wish to display 50 lines of text, using the same font.
lines at a time. The window is sized so that you can only see 16 lines at a time.
You would use: You would use:
@code @code
SetScrollbar(wxVERTICAL, 0, 16, 50); SetScrollbar(wxVERTICAL, 0, 16, 50);
@endcode @endcode
Note that with the window at this size, the thumb position can never Note that with the window at this size, the thumb position can never
go above 50 minus 16, or 34. You can determine how many lines are go above 50 minus 16, or 34. You can determine how many lines are
currently visible by dividing the current view size by the character currently visible by dividing the current view size by the character
height in pixels. height in pixels.
When defining your own scrollbar behaviour, you will always need When defining your own scrollbar behaviour, you will always need
to recalculate the scrollbar settings when the window size changes. to recalculate the scrollbar settings when the window size changes.
You could therefore put your scrollbar calculations and SetScrollbar You could therefore put your scrollbar calculations and SetScrollbar
call into a function named AdjustScrollbars, which can be called call into a function named AdjustScrollbars, which can be called
initially and also from your wxSizeEvent handler function. initially and also from your wxSizeEvent handler function.
@see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
*/ */
virtual void SetScrollbar(int orientation, int position, virtual void SetScrollbar(int orientation, int position,
int thumbSize, int thumbSize, int range,
int range,
bool refresh = true); bool refresh = true);
//@{
/** /**
Sets the size of the window in pixels. Sets the size of the window in pixels.
@@ -2419,10 +2430,6 @@ public:
@param height @param height
Required height position in pixels, or wxDefaultCoord to indicate that the Required height position in pixels, or wxDefaultCoord to indicate that the
existing value should be used. existing value should be used.
@param size
wxSize object for setting the size.
@param rect
wxRect object for setting the position and size.
@param sizeFlags @param sizeFlags
Indicates the interpretation of other parameters. Indicates the interpretation of other parameters.
It is a bit list of the following: It is a bit list of the following:
@@ -2444,10 +2451,7 @@ public:
later and only implemented for MSW and ignored elsewhere later and only implemented for MSW and ignored elsewhere
currently). currently).
@remarks The second form is a convenience for calling the first form with @remarks This overload sets the position and optionally size, of the window.
default x and y parameters, and must be used with
non-default width and height values.
The first form sets the position and optionally size, of the window.
Parameters may be wxDefaultCoord to indicate either that a default Parameters may be wxDefaultCoord to indicate either that a default
should be supplied by wxWidgets, or that the current value of the should be supplied by wxWidgets, or that the current value of the
dimension should be used. dimension should be used.
@@ -2456,9 +2460,19 @@ public:
*/ */
virtual void SetSize(int x, int y, int width, int height, virtual void SetSize(int x, int y, int width, int height,
int sizeFlags = wxSIZE_AUTO); int sizeFlags = wxSIZE_AUTO);
//@{
/**
Sets the size of the window in pixels.
The size is specified using a wxRect, wxSize or by a couple of @c int objects.
@remarks This form must be used with non-default width and height values.
@see Move()
*/
virtual void SetSize(const wxRect& rect); virtual void SetSize(const wxRect& rect);
virtual void SetSize(int width, int height);
virtual void SetSize(const wxSize& size); virtual void SetSize(const wxSize& size);
virtual void SetSize(int width, int height);
//@} //@}
/** /**

39
interface/wx/windowid.h
View File

@@ -9,27 +9,25 @@
/** /**
@class wxIdManager @class wxIdManager
wxIdManager is responsible for allocating and releasing window IDs. It wxIdManager is responsible for allocating and releasing window IDs.
is used by wxWindow::NewControlId and It is used by wxWindow::NewControlId() and wxWindow::UnreserveControlId(),
wxWindow::UnreserveControlId, and can also and can also be used be used directly.
be used be used directly.
@library{wxcore} @library{wxcore}
@category{FIXME} @category{misc}
@see wxWindow::NewControlId, wxWindow::UnreserveControlId, @ref @see wxWindow::NewControlId(), wxWindow::UnreserveControlId(),
overview_windowidsoverview "Window IDs overview" @ref overview_windowids
*/ */
class wxIdManager class wxIdManager
{ {
public: public:
/** /**
Called directly by wxWindow::NewControlId, Called directly by wxWindow::NewControlId(), this function will create
this function will create a new ID or range of IDs. The IDs will be a new ID or range of IDs.
reserved until assigned to a wxWindowIDRef() The IDs will be reserved until assigned to a wxWindowIDRef() or unreserved
or unreserved with UnreserveControlId(). with UnreserveControlId().
Only ID values that are not assigned to a wxWindowIDRef() Only ID values that are not assigned to a wxWindowIDRef() need to be unreserved.
need to be unreserved.
@param count @param count
The number of sequential IDs to reserve. The number of sequential IDs to reserve.
@@ -37,5 +35,20 @@ public:
@return The value of the first ID in the sequence, or wxID_NONE. @return The value of the first ID in the sequence, or wxID_NONE.
*/ */
static wxWindowID ReserveControlId(int count = 1); static wxWindowID ReserveControlId(int count = 1);
/**
Called directly by wxWindow::UnreserveControlId(), this function will
unreserve an ID or range of IDs that is currently reserved.
This should only be called for IDs returned by ReserveControlId() that
have NOT been assigned to a wxWindowIDRef (see @ref overview_windowids).
@param id
The first of the range of IDs to unreserve.
@param count
The number of sequential IDs to unreserve.
@return The value of the first ID in the sequence, or wxID_NONE.
*/
static wxWindowID UnreserveControlId(wxWindowID id, int count = 1);
}; };

379
interface/wx/wizard.h
View File

@@ -1,6 +1,6 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: wizard.h // Name: wizard.h
// Purpose: interface of wxWizardPage // Purpose: interface of wxWizardPage, wxWizardEvent,
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
// Licence: wxWindows license // Licence: wxWindows license
@@ -9,21 +9,29 @@
/** /**
@class wxWizardPage @class wxWizardPage
wxWizardPage is one of the screens in wxWizard: it must wxWizardPage is one of the screens in wxWizard: it must know what are the
know what are the following and preceding pages (which may be @NULL for the following and preceding pages (which may be @NULL for the first/last page).
first/last page). Except for this extra knowledge, wxWizardPage is just a Except for this extra knowledge, wxWizardPage is just a
panel, so the controls may be placed directly on it in the usual way. panel, so the controls may be placed directly on it in the usual way.
This class allows the programmer to decide the order of pages in the wizard This class allows the programmer to decide the order of pages in the wizard
dynamically (during run-time) and so provides maximal flexibility. Usually, dynamically (during run-time) and so provides maximal flexibility.
however, the order of pages is known in advance in which case Usually, however, the order of pages is known in advance in which case
wxWizardPageSimple class is enough and it is simpler wxWizardPageSimple class is enough and it is simpler to use.
to use.
@section wizardpage_virtuals Virtual functions to override
To use this class, you must override wxWizardPage::GetPrev() and
wxWizardPage::GetNext() pure virtual functions (or you may use
wxWizardPageSimple instead).
wxWizardPage::GetBitmap() can also be overridden, but this should be very
rarely needed.
@library{wxadv} @library{wxadv}
@category{miscwnd} @category{miscwnd}
@see wxWizard, @ref overview_samplewizard "wxWizard sample" @see wxWizard, @ref page_samples_wizard
*/ */
class wxWizardPage : public wxPanel class wxWizardPage : public wxPanel
{ {
@@ -43,11 +51,13 @@ public:
const wxBitmap& bitmap = wxNullBitmap); const wxBitmap& bitmap = wxNullBitmap);
/** /**
This method is called by wxWizard to get the bitmap to display alongside the This method is called by wxWizard to get the bitmap to display alongside the page.
page. By default, @c m_bitmap member variable which was set in the By default, @c m_bitmap member variable which was set in the
@ref wxwizardpage() constructor. @ref wxWizardPage() constructor.
If the bitmap was not explicitly set (i.e. if @c wxNullBitmap is returned),
If the bitmap was not explicitly set (i.e. if ::wxNullBitmap is returned),
the default bitmap for the wizard should be used. the default bitmap for the wizard should be used.
The only cases when you would want to override this function is if the page The only cases when you would want to override this function is if the page
bitmap depends dynamically on the user choices, i.e. almost never. bitmap depends dynamically on the user choices, i.e. almost never.
*/ */
@@ -55,9 +65,9 @@ public:
/** /**
Get the page which should be shown when the user chooses the @c "Next" Get the page which should be shown when the user chooses the @c "Next"
button: if @NULL is returned, this button will be disabled. The last button: if @NULL is returned, this button will be disabled.
page of the wizard will usually return @NULL from here, but the others The last page of the wizard will usually return @NULL from here, but
will not. the others will not.
@see GetPrev() @see GetPrev()
*/ */
@@ -65,9 +75,9 @@ public:
/** /**
Get the page which should be shown when the user chooses the @c "Back" Get the page which should be shown when the user chooses the @c "Back"
button: if @NULL is returned, this button will be disabled. The first button: if @NULL is returned, this button will be disabled.
page of the wizard will usually return @NULL from here, but the others The first page of the wizard will usually return @NULL from here, but
will not. the others will not.
@see GetNext() @see GetNext()
*/ */
@@ -79,37 +89,50 @@ public:
/** /**
@class wxWizardEvent @class wxWizardEvent
wxWizardEvent class represents an event generated by the wxWizardEvent class represents an event generated by the wxWizard: this event
wizard(): this event is first sent to the page itself and, is first sent to the page itself and, if not processed there, goes up the
if not processed there, goes up the window hierarchy as usual. window hierarchy as usual.
@beginEventTable{wxWizardEvent}
@event{EVT_WIZARD_PAGE_CHANGED(id, func)}
The page has been just changed (this event can not be vetoed).
@event{EVT_WIZARD_PAGE_CHANGING(id, func)}
The page is being changed (this event can be vetoed).
@event{EVT_WIZARD_CANCEL(id, func)}
The user attempted to cancel the wizard (this event may also be vetoed).
@event{EVT_WIZARD_HELP(id, func)}
The wizard help button was pressed.
@event{EVT_WIZARD_FINISHED(id, func)}
The wizard finished button was pressed.
@endEventTable
@library{wxadv} @library{wxadv}
@category{events} @category{events}
@see wxWizard, @ref overview_samplewizard "wxWizard sample" @see wxWizard, @ref page_samples_wizard
*/ */
class wxWizardEvent : public wxNotifyEvent class wxWizardEvent : public wxNotifyEvent
{ {
public: public:
/** /**
Constructor. It is not normally used by the user code as the objects of this Constructor.
It is not normally used by the user code as the objects of this
type are constructed by wxWizard. type are constructed by wxWizard.
*/ */
wxWizardEvent(wxEventType type = wxEVT_NULL, int id = -1, wxWizardEvent(wxEventType type = wxEVT_NULL, int id = -1,
bool direction = true); bool direction = true);
/** /**
Return the direction in which the page is changing: for @c Return the direction in which the page is changing: for
EVT_WIZARD_PAGE_CHANGING, return @true if we're going forward or @c EVT_WIZARD_PAGE_CHANGING, return @true if we're going forward or
@false otherwise and for @c EVT_WIZARD_PAGE_CHANGED return @true if @false otherwise and for @c EVT_WIZARD_PAGE_CHANGED return @true if we
we came from the previous page and @false if we returned from the next came from the previous page and @false if we returned from the next one.
one.
*/ */
bool GetDirection() const; bool GetDirection() const;
/** /**
Returns the wxWizardPage which was active when this Returns the wxWizardPage which was active when this event was generated.
event was generated.
*/ */
wxWizardPage* GetPage() const; wxWizardPage* GetPage() const;
}; };
@@ -119,27 +142,25 @@ public:
/** /**
@class wxWizardPageSimple @class wxWizardPageSimple
wxWizardPageSimple is the simplest possible wxWizardPageSimple is the simplest possible wxWizardPage implementation:
wxWizardPage implementation: it just returns the it just returns the pointers given to its constructor from wxWizardPage::GetNext()
pointers given to its constructor from GetNext() and GetPrev() functions. and wxWizardPage::GetPrev() functions.
This makes it very easy to use the objects of this class in the wizards where This makes it very easy to use the objects of this class in the wizards where
the pages order is known statically - on the other hand, if this is not the the pages order is known statically - on the other hand, if this is not the
case you must derive your own class from wxWizardPage case you must derive your own class from wxWizardPage instead.
instead.
@library{wxadv} @library{wxadv}
@category{miscwnd} @category{miscwnd}
@see wxWizard, @ref overview_samplewizard "wxWizard sample" @see wxWizard, @ref page_samples_wizard
*/ */
class wxWizardPageSimple : public wxWizardPage class wxWizardPageSimple : public wxWizardPage
{ {
public: public:
/** /**
Constructor takes the previous and next pages. They may be modified later by Constructor takes the previous and next pages.
SetPrev() or They may be modified later by SetPrev() or SetNext().
SetNext().
*/ */
wxWizardPageSimple(wxWizard* parent = NULL, wxWizardPageSimple(wxWizard* parent = NULL,
wxWizardPage* prev = NULL, wxWizardPage* prev = NULL,
@@ -149,6 +170,13 @@ public:
/** /**
A convenience function to make the pages follow each other. A convenience function to make the pages follow each other.
Example: Example:
@code
wxRadioboxPage *page3 = new wxRadioboxPage(wizard);
wxValidationPage *page4 = new wxValidationPage(wizard);
wxWizardPageSimple::Chain(page3, page4);
@endcode
*/ */
static void Chain(wxWizardPageSimple* first, static void Chain(wxWizardPageSimple* first,
wxWizardPageSimple* second); wxWizardPageSimple* second);
@@ -169,53 +197,85 @@ public:
/** /**
@class wxWizard @class wxWizard
wxWizard is the central class for implementing 'wizard-like' dialogs. These wxWizard is the central class for implementing 'wizard-like' dialogs.
dialogs are mostly familiar to Windows users and are nothing other than a These dialogs are mostly familiar to Windows users and are nothing other than a
sequence of 'pages', each displayed inside a dialog which has the sequence of 'pages', each displayed inside a dialog which has the buttons to
buttons to navigate to the next (and previous) pages. navigate to the next (and previous) pages.
The wizards are typically used to decompose a complex dialog into several The wizards are typically used to decompose a complex dialog into several
simple steps and are mainly useful to the novice users, hence it is important simple steps and are mainly useful to the novice users, hence it is important
to keep them as simple as possible. to keep them as simple as possible.
To show a wizard dialog, you must first create an instance of the wxWizard class To show a wizard dialog, you must first create an instance of the wxWizard class
using either the non-default constructor or a default one followed by call to using either the non-default constructor or a default one followed by call to the
the wxWizard::Create function. Then you should add all pages you want the wizard to
wxWizard::Create function. Then you should add all pages you show and call wxWizard::RunWizard().
want the wizard to show and call wxWizard::RunWizard. Finally, don't forget to call @c "wizard->Destroy()", otherwise your application
Finally, don't forget to call @c wizard-Destroy(), otherwise your application
will hang on exit due to an undestroyed window. will hang on exit due to an undestroyed window.
You can supply a bitmap to display on the left of the wizard, either for all You can supply a bitmap to display on the left of the wizard, either for all pages
pages
or for individual pages. If you need to have the bitmap resize to the height of or for individual pages. If you need to have the bitmap resize to the height of
the wizard, the wizard, call wxWizard::SetBitmapPlacement() and if necessary,
call wxWizard::SetBitmapPlacement and if necessary, wxWizard::SetBitmapBackgroundColour() and wxWizard::SetMinimumBitmapWidth().
wxWizard::SetBitmapBackgroundColour and wxWizard::SetMinimumBitmapWidth.
To make wizard pages scroll when the display is too small to fit the whole To make wizard pages scroll when the display is too small to fit the whole
dialog, you can switch dialog, you can switch layout adaptation on globally with
layout adaptation on globally with wxDialog::EnableLayoutAdaptation or wxDialog::EnableLayoutAdaptation() or per dialog with wxDialog::SetLayoutAdaptationMode().
per dialog with wxDialog::SetLayoutAdaptationMode. For more For more about layout adaptation, see @ref overview_dialog_autoscrolling.
about layout adaptation, see @ref overview_autoscrollingdialogs "Automatic
scrolling dialogs". @beginEventTable{wxWizardEvent}
For some events, Veto() can be called to prevent the event from happening.
@event{EVT_WIZARD_PAGE_CHANGED(id, func)}
The page has just been changed (this event cannot be vetoed).
@event{EVT_WIZARD_PAGE_CHANGING(id, func)}
The page is being changed (this event can be vetoed).
@event{EVT_WIZARD_CANCEL(id, func)}
The user attempted to cancel the wizard (this event may also be vetoed).
@event{EVT_WIZARD_HELP(id, func)}
The wizard help button was pressed.
@event{EVT_WIZARD_FINISHED(id, func)}
The wizard finished button was pressed.
@endEventTable
@section wizard_extstyles Extended styles
Use the wxWindow::SetExtraStyle() function to set the following style.
You will need to use two-step construction (use the default constructor,
call SetExtraStyle(), then call Create).
@beginExtraStyleTable
@style{wxWIZARD_EX_HELPBUTTON}
Shows a Help button using wxID_HELP.
@endExtraStyleTable
See also wxDialog for other extended styles.
@library{wxadv} @library{wxadv}
@category{cmndlg} @category{cmndlg}
@see wxWizardEvent, wxWizardPage, @ref overview_samplewizard "wxWizard sample" @see wxWizardEvent, wxWizardPage, @ref page_samples_wizard
*/ */
class wxWizard : public wxDialog class wxWizard : public wxDialog
{ {
public: public:
//@{ /**
Default constructor.
Use this if you wish to derive from wxWizard and then call Create(),
for example if you wish to set an extra style with wxWindow::SetExtraStyle()
between the two calls.
*/
wxWizard();
/** /**
Constructor which really creates the wizard -- if you use this constructor, you Constructor which really creates the wizard -- if you use this constructor, you
shouldn't call Create(). shouldn't call Create().
Notice that unlike almost all other wxWidgets classes, there is no @e size Notice that unlike almost all other wxWidgets classes, there is no @e size
parameter in the wxWizard constructor because the wizard will have a predefined parameter in the wxWizard constructor because the wizard will have a predefined
default size by default. If you want to change this, you should use the default size by default.
GetPageAreaSizer() function. If you want to change this, you should use the GetPageAreaSizer() function.
@param parent @param parent
The parent window, may be @NULL. The parent window, may be @NULL.
@@ -224,29 +284,26 @@ public:
@param title @param title
The title of the dialog. The title of the dialog.
@param bitmap @param bitmap
The default bitmap used in the left side of the wizard. See The default bitmap used in the left side of the wizard. See also GetBitmap().
also GetBitmap.
@param pos @param pos
The position of the dialog, it will be centered on the screen The position of the dialog, it will be centered on the screen by default.
by default.
@param style @param style
Window style is passed to wxDialog. Window style is passed to wxDialog.
*/ */
wxWizard();
wxWizard(wxWindow* parent, int id = -1, wxWizard(wxWindow* parent, int id = -1,
const wxString& title = wxEmptyString, const wxString& title = wxEmptyString,
const wxBitmap& bitmap = wxNullBitmap, const wxBitmap& bitmap = wxNullBitmap,
const wxPoint& pos = wxDefaultPosition, const wxPoint& pos = wxDefaultPosition,
long style = wxDEFAULT_DIALOG_STYLE); long style = wxDEFAULT_DIALOG_STYLE);
//@}
/** /**
Creates the wizard dialog. Must be called if the default constructor had been Creates the wizard dialog.
used to create the object. Must be called if the default constructor had been used to create the object.
Notice that unlike almost all other wxWidgets classes, there is no @e size Notice that unlike almost all other wxWidgets classes, there is no @e size
parameter in the wxWizard constructor because the wizard will have a predefined parameter in the wxWizard constructor because the wizard will have a predefined
default size by default. If you want to change this, you should use the default size by default.
GetPageAreaSizer() function. If you want to change this, you should use the GetPageAreaSizer() function.
@param parent @param parent
The parent window, may be @NULL. The parent window, may be @NULL.
@@ -255,11 +312,9 @@ public:
@param title @param title
The title of the dialog. The title of the dialog.
@param bitmap @param bitmap
The default bitmap used in the left side of the wizard. See The default bitmap used in the left side of the wizard. See also GetBitmap().
also GetBitmap.
@param pos @param pos
The position of the dialog, it will be centered on the screen The position of the dialog, it will be centered on the screen by default.
by default.
@param style @param style
Window style is passed to wxDialog. Window style is passed to wxDialog.
*/ */
@@ -270,10 +325,11 @@ public:
long style = wxDEFAULT_DIALOG_STYLE); long style = wxDEFAULT_DIALOG_STYLE);
/** /**
This method is obsolete, use This method is obsolete, use GetPageAreaSizer() instead.
GetPageAreaSizer() instead.
Sets the page size to be big enough for all the pages accessible via the Sets the page size to be big enough for all the pages accessible via the
given @e firstPage, i.e. this page, its next page and so on. given @e firstPage, i.e. this page, its next page and so on.
This method may be called more than once and it will only change the page size This method may be called more than once and it will only change the page size
if the size required by the new page is bigger than the previously set one. if the size required by the new page is bigger than the previously set one.
This is useful if the decision about which pages to show is taken during This is useful if the decision about which pages to show is taken during
@@ -285,34 +341,34 @@ public:
/** /**
Returns the bitmap used for the wizard. Returns the bitmap used for the wizard.
*/ */
const wxBitmap GetBitmap() const; const wxBitmap& GetBitmap() const;
/** /**
Returns the colour that should be used to fill the area not taken up by the Returns the colour that should be used to fill the area not taken up by the
wizard or page bitmap, wizard or page bitmap, if a non-zero bitmap placement flag has been set.
if a non-zero bitmap placement flag has been set.
See also SetBitmapPlacement(). See also SetBitmapPlacement().
*/ */
const wxColour GetBitmapBackgroundColour() const; const wxColour& GetBitmapBackgroundColour() const;
/** /**
Returns the flags indicating how the wizard or page bitmap should be expanded Returns the flags indicating how the wizard or page bitmap should be expanded
and positioned to fit the and positioned to fit the page height. By default, placement is 0 (no expansion is done).
page height. By default, placement is 0 (no expansion is done).
See also SetBitmapPlacement() for the possible values. See also SetBitmapPlacement() for the possible values.
*/ */
int GetBitmapPlacement(); int GetBitmapPlacement();
/** /**
Get the current page while the wizard is running. @NULL is returned if Get the current page while the wizard is running.
RunWizard() is not being executed now. @NULL is returned if RunWizard() is not being executed now.
*/ */
wxWizardPage* GetCurrentPage() const; wxWizardPage* GetCurrentPage() const;
/** /**
Returns the minimum width for the bitmap that will be constructed to contain Returns the minimum width for the bitmap that will be constructed to contain
the actual wizard or page bitmap the actual wizard or page bitmap if a non-zero bitmap placement flag has been set.
if a non-zero bitmap placement flag has been set.
See also SetBitmapPlacement(). See also SetBitmapPlacement().
*/ */
int GetMinimumBitmapWidth() const; int GetMinimumBitmapWidth() const;
@@ -320,28 +376,26 @@ public:
/** /**
Returns pointer to page area sizer. The wizard is laid out using sizers and Returns pointer to page area sizer. The wizard is laid out using sizers and
the page area sizer is the place-holder for the pages. All pages are resized the page area sizer is the place-holder for the pages. All pages are resized
before before being shown to match the wizard page area.
being shown to match the wizard page area.
Page area sizer has a minimal size that is the maximum of several values. First, Page area sizer has a minimal size that is the maximum of several values.
all pages (or other objects) added to the sizer. Second, all pages reachable First, all pages (or other objects) added to the sizer. Second, all pages reachable
by repeatedly applying by repeatedly applying wxWizardPage::GetNext() to any page inserted into the sizer.
wxWizardPage::GetNext to
any page inserted into the sizer. Third, Third, the minimal size specified using SetPageSize() and FitToPage().
the minimal size specified using SetPageSize() and Fourth, the total wizard height may be increased to accommodate the bitmap height.
FitToPage(). Fourth, the total wizard height may Fifth and finally, wizards are never smaller than some built-in minimal size to
be increased to accommodate the bitmap height. Fifth and finally, wizards are avoid wizards that are too small.
never smaller than some built-in minimal size to avoid wizards that are too
small. The caller can use wxSizer::SetMinSize to enlarge it beyond the minimal size.
The caller can use wxSizer::SetMinSize to enlarge it If @c wxRESIZE_BORDER was passed to constructor, user can resize wizard and
beyond the minimal size. If @c wxRESIZE_BORDER was passed to constructor, user consequently the page area (but not make it smaller than the minimal size).
can resize wizard and consequently the page area (but not make it smaller than
the It is recommended to add the first page to the page area sizer.
minimal size). For simple wizards, this will enlarge the wizard to fit the biggest page.
It is recommended to add the first page to the page area sizer. For simple
wizards, For non-linear wizards, the first page of every separate chain should be added.
this will enlarge the wizard to fit the biggest page. For non-linear wizards, Caller-specified size can be accomplished using wxSizer::SetMinSize().
the first page of every separate chain should be added. Caller-specified size
can be accomplished using wxSizer::SetMinSize.
Adding pages to the page area sizer affects the default border width around page Adding pages to the page area sizer affects the default border width around page
area that can be altered with SetBorder(). area that can be altered with SetBorder().
*/ */
@@ -353,20 +407,20 @@ public:
wxSize GetPageSize() const; wxSize GetPageSize() const;
/** /**
Return @true if this page is not the last one in the wizard. The base Return @true if this page is not the last one in the wizard.
class version implements this by calling The base class version implements this by calling
@ref wxWizardPage::getnext page-GetNext but this could be undesirable if, @ref wxWizardPage::GetNext "page->GetNext" but this could be
for example, the pages are created on demand only. undesirable if, for example, the pages are created on demand only.
@see HasPrevPage() @see HasPrevPage()
*/ */
virtual bool HasNextPage(wxWizardPage* page); virtual bool HasNextPage(wxWizardPage* page);
/** /**
Returns @true if this page is not the last one in the wizard. The base Returns @true if this page is not the last one in the wizard.
class version implements this by calling The base class version implements this by calling
@ref wxWizardPage::getprev page-GetPrev but this could be undesirable if, @ref wxWizardPage::GetPrev "page->GetPrev" but this could be
for example, the pages are created on demand only. undesirable if, for example, the pages are created on demand only.
@see HasNextPage() @see HasNextPage()
*/ */
@@ -374,8 +428,8 @@ public:
/** /**
Executes the wizard starting from the given page, returning @true if it was Executes the wizard starting from the given page, returning @true if it was
successfully finished or @false if user cancelled it. The @a firstPage successfully finished or @false if user cancelled it.
can not be @NULL. The @a firstPage can not be @NULL.
*/ */
bool RunWizard(wxWizardPage* firstPage); bool RunWizard(wxWizardPage* firstPage);
@@ -386,83 +440,64 @@ public:
/** /**
Sets the colour that should be used to fill the area not taken up by the wizard Sets the colour that should be used to fill the area not taken up by the wizard
or page bitmap, or page bitmap, if a non-zero bitmap placement flag has been set.
if a non-zero bitmap placement flag has been set.
See also SetBitmapPlacement(). See also SetBitmapPlacement().
*/ */
void SetBitmapBackgroundColour(const wxColour& colour); void SetBitmapBackgroundColour(const wxColour& colour);
/** /**
Sets the flags indicating how the wizard or page bitmap should be expanded and Sets the flags indicating how the wizard or page bitmap should be expanded and
positioned to fit the positioned to fit the page height.
page height. By default, placement is 0 (no expansion is done). @a placement is
a bitlist with the By default, placement is 0 (no expansion is done). @a placement is a bitlist with the
following possible values: following possible values:
@b wxWIZARD_VALIGN_TOP - @b wxWIZARD_VALIGN_TOP: Aligns the bitmap at the top.
- @b wxWIZARD_VALIGN_CENTRE: Centres the bitmap vertically.
Aligns the bitmap at the top. - @b wxWIZARD_VALIGN_BOTTOM: Aligns the bitmap at the bottom.
- @b wxWIZARD_HALIGN_LEFT: Left-aligns the bitmap.
@b wxWIZARD_VALIGN_CENTRE - @b wxWIZARD_HALIGN_CENTRE: Centres the bitmap horizontally.
- @b wxWIZARD_HALIGN_RIGHT: Right-aligns the bitmap.
Centres the bitmap vertically. - @b wxWIZARD_TILE: @todo describe this
@b wxWIZARD_VALIGN_BOTTOM
Aligns the bitmap at the bottom.
@b wxWIZARD_HALIGN_LEFT
Left-aligns the bitmap.
@b wxWIZARD_HALIGN_CENTRE
Centres the bitmap horizontally.
@b wxWIZARD_HALIGN_RIGHT
Right-aligns the bitmap.
@b wxWIZARD_TILE
See also SetMinimumBitmapWidth(). See also SetMinimumBitmapWidth().
*/ */
void SetBitmapPlacement(int placement); void SetBitmapPlacement(int placement);
/** /**
Sets width of border around page area. Default is zero. For backward Sets width of border around page area. Default is zero.
compatibility, if there are no pages in For backward compatibility, if there are no pages in GetPageAreaSizer(),
GetPageAreaSizer(), the default is 5 pixels. the default is 5 pixels.
If there is a five point border around all controls in a page and the border If there is a five point border around all controls in a page and the border
around around page area is left as zero, a five point white space along all dialog borders
page area is left as zero, a five point white space along all dialog borders
will be added to the control border in order to space page controls ten points will be added to the control border in order to space page controls ten points
from the dialog from the dialog border and non-page controls.
border and non-page controls.
*/ */
void SetBorder(int border); void SetBorder(int border);
/** /**
Sets the minimum width for the bitmap that will be constructed to contain the Sets the minimum width for the bitmap that will be constructed to contain the
actual wizard or page bitmap actual wizard or page bitmap if a non-zero bitmap placement flag has been set.
if a non-zero bitmap placement flag has been set. If this is not set when using If this is not set when using bitmap placement, the initial layout may be incorrect.
bitmap placement, the initial
layout may be incorrect.
See also SetBitmapPlacement(). See also SetBitmapPlacement().
*/ */
void SetMinimumBitmapWidth(int width); void SetMinimumBitmapWidth(int width);
/** /**
This method is obsolete, use Sets the minimal size to be made available for the wizard pages.
GetPageAreaSizer() instead. The wizard will take into account the size of the bitmap (if any) itself.
Sets the minimal size to be made available for the wizard pages. The wizard Also, the wizard will never be smaller than the default size.
will take into account the size of the bitmap (if any) itself. Also, the
wizard will never be smaller than the default size. The recommended way to use this function is to lay out all wizard pages
The recommended way to use this function is to lay out all wizard pages using using the sizers (even though the wizard is not resizeable) and then use
the sizers (even though the wizard is not resizeable) and then use wxSizer::CalcMin() in a loop to calculate the maximum of minimal sizes of
wxSizer::CalcMin in a loop to calculate the maximum the pages and pass it to SetPageSize().
of minimal sizes of the pages and pass it to SetPageSize().
@deprecated
This method is obsolete, use GetPageAreaSizer() instead.
*/ */
void SetPageSize(const wxSize& sizePage); void SetPageSize(const wxSize& sizePage);
}; };

33
interface/wx/wrapsizer.h
View File

@@ -10,9 +10,9 @@
@class wxWrapSizer @class wxWrapSizer
A wrap sizer lays out its items in a single line, like a box sizer -- as long A wrap sizer lays out its items in a single line, like a box sizer -- as long
as there is space available in that direction. Once all available space in as there is space available in that direction.
the primary direction has been used, a new line is added and items are added Once all available space in the primary direction has been used, a new line
there. is added and items are added there.
So a wrap sizer has a primary orientation for adding items, and adds lines So a wrap sizer has a primary orientation for adding items, and adds lines
as needed in the secondary direction. as needed in the secondary direction.
@@ -20,28 +20,33 @@
@library{wxcore} @library{wxcore}
@category{winlayout} @category{winlayout}
@see wxBoxSizer, wxSizer, @ref overview_sizeroverview "Sizer overview" @see wxBoxSizer, wxSizer, @ref overview_sizer
*/ */
class wxWrapSizer : public wxBoxSizer class wxWrapSizer : public wxBoxSizer
{ {
public: public:
/** /**
Constructor for a wxWrapSizer. @a orient determines the primary direction of Constructor for a wxWrapSizer.
the sizer (the most common case being @c wxHORIZONTAL). The flags
parameter can be a combination of the values @c @a orient determines the primary direction of the sizer (the most common
wxEXTEND_LAST_ON_EACH_LINE which will cause the last item on each line case being @c wxHORIZONTAL). The flags parameter can be a combination of
to use any remaining space on that line and @c wxREMOVE_LEADING_SPACES the values @c wxEXTEND_LAST_ON_EACH_LINE which will cause the last item
which removes any spacer elements from the beginning of a row. Both of on each line to use any remaining space on that line and @c wxREMOVE_LEADING_SPACES
these flags are on by default. which removes any spacer elements from the beginning of a row.
Both of these flags are on by default.
*/ */
wxWrapSizer(int orient = wxHORIZONTAL, wxWrapSizer(int orient = wxHORIZONTAL,
int flags = wxEXTEND_LAST_ON_EACH_LINE | int flags = wxEXTEND_LAST_ON_EACH_LINE |
wxREMOVE_LEADING_SPACES); wxREMOVE_LEADING_SPACES);
/** /**
Not used by an application. This is the mechanism by which sizers can inform Not used by an application.
sub-items of the first determined size component. The sub-item can then better
determine its size requirements. This is the mechanism by which sizers can inform sub-items of the first
determined size component.
The sub-item can then better determine its size requirements.
Returns @true if the information was used (and the sub-item min size was Returns @true if the information was used (and the sub-item min size was
updated). updated).
*/ */

21
interface/wx/wupdlock.h
View File

@@ -9,11 +9,11 @@
/** /**
@class wxWindowUpdateLocker @class wxWindowUpdateLocker
This tiny class prevents redrawing of a wxWindow during its This tiny class prevents redrawing of a wxWindow during its lifetime by using
lifetime by using wxWindow::Freeze and wxWindow::Freeze() and wxWindow::Thaw() methods.
wxWindow::Thaw methods. It is typically used for creating
automatic objects to temporarily suppress window updates before a batch of It is typically used for creating automatic objects to temporarily suppress
operations is performed: window updates before a batch of operations is performed:
@code @code
void MyFrame::Foo() void MyFrame::Foo()
@@ -27,19 +27,18 @@
} }
@endcode @endcode
Using this class is easier and safer than calling Using this class is easier and safer than calling wxWindow::Freeze() and
wxWindow::Freeze and wxWindow::Thaw because you wxWindow::Thaw() because you don't risk to forget calling the latter.
don't risk to forget calling the latter.
@library{wxbase} @library{wxbase}
@category{FIXME} @category{misc}
*/ */
class wxWindowUpdateLocker class wxWindowUpdateLocker
{ {
public: public:
/** /**
Creates an object preventing the updates of the specified @e win. The Creates an object preventing the updates of the specified @e win.
parameter must be non-@NULL and the window must exist for longer than The parameter must be non-@NULL and the window must exist for longer than
wxWindowUpdateLocker object itself. wxWindowUpdateLocker object itself.
*/ */
wxWindowUpdateLocker(wxWindow* win); wxWindowUpdateLocker(wxWindow* win);

314
interface/wx/xml/xml.h
View File

@@ -1,20 +1,41 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: xml/xml.h // Name: xml/xml.h
// Purpose: interface of wxXmlNode // Purpose: interface of wxXmlNode, wxXmlAttribute, wxXmlDocument
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
// Licence: wxWindows license // Licence: wxWindows license
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
/// Represents XML node type.
enum wxXmlNodeType
{
// note: values are synchronized with xmlElementType from libxml
wxXML_ELEMENT_NODE = 1,
wxXML_ATTRIBUTE_NODE = 2,
wxXML_TEXT_NODE = 3,
wxXML_CDATA_SECTION_NODE = 4,
wxXML_ENTITY_REF_NODE = 5,
wxXML_ENTITY_NODE = 6,
wxXML_PI_NODE = 7,
wxXML_COMMENT_NODE = 8,
wxXML_DOCUMENT_NODE = 9,
wxXML_DOCUMENT_TYPE_NODE = 10,
wxXML_DOCUMENT_FRAG_NODE = 11,
wxXML_NOTATION_NODE = 12,
wxXML_HTML_DOCUMENT_NODE = 13
};
/** /**
@class wxXmlNode @class wxXmlNode
Represents a node in an XML document. See wxXmlDocument. Represents a node in an XML document. See wxXmlDocument.
Node has a name and may have content and attributes. Most common node types are Node has a name and may have content and attributes.
@c wxXML_TEXT_NODE (name and attributes are irrelevant) and
@c wxXML_ELEMENT_NODE (e.g. in @c titlehi/title there is an element Most common node types are @c wxXML_TEXT_NODE (name and attributes are irrelevant)
with name="title", irrelevant content and one child (@c wxXML_TEXT_NODE and @c wxXML_ELEMENT_NODE (e.g. in @c \<title\>hi\</title\> there is an element
with name="title", irrelevant content and one child @c wxXML_TEXT_NODE
with content="hi"). with content="hi").
If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to
@@ -28,33 +49,76 @@
class wxXmlNode class wxXmlNode
{ {
public: public:
//@{
/** /**
A simplified version of the first constructor form, assuming a @NULL parent. Creates this XML node and eventually insert it into an existing XML tree.
@param parent
The parent node to which append this node instance.
If this argument is @NULL this new node will be floating and it can
be appended later to another one using the AddChild() or InsertChild()
functions. Otherwise the child is already added to the XML tree by
this constructor and it shouldn't be done again.
@param type
One of the ::wxXmlNodeType enumeration value.
@param name
The name of the node. This is the string which appears between angular brackets.
@param content
The content of the node.
Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE.
@param attrs
If not @NULL, this wxXmlAttribute object and its eventual siblings are attached to the node.
@param next
If not @NULL, this node and its eventual siblings are attached to the node.
@param lineNo
Number of line this node was present at in input file or -1.
*/ */
wxXmlNode(wxXmlNode* parent, wxXmlNodeType type, wxXmlNode(wxXmlNode* parent, wxXmlNodeType type,
const wxString& name, const wxString& name,
const wxString& content = wxEmptyString, const wxString& content = wxEmptyString,
wxXmlAttribute* attrs = NULL, wxXmlAttribute* attrs = NULL,
wxXmlNode* next = NULL, int lineNo = -1); wxXmlNode* next = NULL, int lineNo = -1);
wxXmlNode(const wxXmlNode& node);
/**
A simplified version of the first constructor form, assuming a @NULL parent.
@param type
One of the ::wxXmlNodeType enumeration value.
@param name
The name of the node. This is the string which appears between angular brackets.
@param content
The content of the node.
Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE.
@param lineNo
Number of line this node was present at in input file or -1.
*/
wxXmlNode(wxXmlNodeType type, const wxString& name, wxXmlNode(wxXmlNodeType type, const wxString& name,
const wxString& content = wxEmptyString, const wxString& content = wxEmptyString,
int lineNo = -1); int lineNo = -1);
//@}
/**
Copy constructor.
Note that this does NOT copy syblings and parent pointer, i.e. GetParent()
and GetNext() will return @NULL after using copy ctor and are never unmodified by operator=().
On the other hand, it DOES copy children and attributes.
*/
wxXmlNode(const wxXmlNode& node);
/** /**
The virtual destructor. Deletes attached children and attributes. The virtual destructor. Deletes attached children and attributes.
*/ */
~wxXmlNode(); ~wxXmlNode();
//@{ /**
Appends a attribute with given @a name and @a value to the list of
attributes for this node.
*/
void AddAttribute(const wxString& name, const wxString& value);
/** /**
Appends given attribute to the list of attributes for this node. Appends given attribute to the list of attributes for this node.
*/ */
void AddAttribute(const wxString& name, const wxString& value);
void AddAttribute(wxXmlAttribute* attr); void AddAttribute(wxXmlAttribute* attr);
//@}
/** /**
Adds node @a child as the last child of this node. Adds node @a child as the last child of this node.
@@ -76,15 +140,18 @@ public:
*/ */
bool DeleteAttribute(const wxString& name); bool DeleteAttribute(const wxString& name);
//@{ /**
Returns true if a attribute named attrName could be found.
The value of that attribute is saved in value (which must not be @NULL).
*/
bool GetAttribute(const wxString& attrName, wxString* value) const;
/** /**
Returns the value of the attribute named @a attrName if it does exist. Returns the value of the attribute named @a attrName if it does exist.
If it does not exist, the @a defaultVal is returned. If it does not exist, the @a defaultVal is returned.
*/ */
bool GetAttribute(const wxString& attrName, wxString* value) const; wxString GetAttribute(const wxString& attrName,
const wxString GetAttribute(const wxString& attrName, const wxString& defaultVal = wxEmptyString) const;
const wxString& defaultVal = wxEmptyString) const;
//@}
/** /**
Return a pointer to the first attribute of this node. Return a pointer to the first attribute of this node.
@@ -101,28 +168,28 @@ public:
/** /**
Returns the content of this node. Can be an empty string. Returns the content of this node. Can be an empty string.
Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type) Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type)
the the content is an empty string. See GetNodeContent() for more details.
content is an empty string. See GetNodeContent() for more details.
*/ */
wxString GetContent() const; wxString GetContent() const;
/** /**
Returns the number of nodes which separe this node from @c grandparent. Returns the number of nodes which separe this node from @c grandparent.
This function searches only the parents of this node until it finds @c
grandparent This function searches only the parents of this node until it finds
or the @NULL node (which is the parent of non-linked nodes or the parent of a @a grandparent or the @NULL node (which is the parent of non-linked
wxXmlDocument's root node). nodes or the parent of a wxXmlDocument's root node).
*/ */
int GetDepth(wxXmlNode* grandparent = NULL) const; int GetDepth(wxXmlNode* grandparent = NULL) const;
/** /**
Returns line number of the node in the input XML file or -1 if it is unknown. Returns line number of the node in the input XML file or @c -1 if it is unknown.
*/ */
int GetLineNumber() const; int GetLineNumber() const;
/** /**
Returns the name of this node. Can be an empty string (e.g. for nodes of type Returns the name of this node.
@c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE). Can be an empty string (e.g. for nodes of type @c wxXML_TEXT_NODE or
@c wxXML_CDATA_SECTION_NODE).
*/ */
wxString GetName() const; wxString GetName() const;
@@ -133,16 +200,26 @@ public:
wxXmlNode* GetNext() const; wxXmlNode* GetNext() const;
/** /**
Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c Returns the content of the first child node of type @c wxXML_TEXT_NODE
wxXML_CDATA_SECTION_NODE. or @c wxXML_CDATA_SECTION_NODE.
This function is very useful since the XML snippet @c This function is very useful since the XML snippet @c "tagnametagcontent/tagname"
"tagnametagcontent/tagname" is represented by is represented by expat with the following tag tree:
expat with the following tag tree:
@code
wxXML_ENTITY_NODE name="tagname", content=""
|-- wxXML_TEXT_NODE name="", content="tagcontent"
@endcode
or eventually: or eventually:
An empty string is returned if the node has no children of type @c @code
wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content of the first child of such types is empty. wxXML_ENTITY_NODE name="tagname", content=""
|-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"
@endcode
An empty string is returned if the node has no children of type
@c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content
of the first child of such types is empty.
*/ */
wxString GetNodeContent() const; wxString GetNodeContent() const;
@@ -158,7 +235,7 @@ public:
wxXmlNodeType GetType() const; wxXmlNodeType GetType() const;
/** /**
Returns @true if this node has a attribute named @e attrName. Returns @true if this node has a attribute named @a attrName.
*/ */
bool HasAttribute(const wxString& attrName) const; bool HasAttribute(const wxString& attrName) const;
@@ -199,34 +276,36 @@ public:
/** /**
Returns @true if the content of this node is a string containing only Returns @true if the content of this node is a string containing only
whitespaces (spaces, whitespaces (spaces, tabs, new lines, etc).
tabs, new lines, etc). Note that this function is locale-independent since the
parsing of XML Note that this function is locale-independent since the parsing of XML
documents must always produce the exact same tree regardless of the locale it documents must always produce the exact same tree regardless of the
runs under. locale it runs under.
*/ */
bool IsWhitespaceOnly() const; bool IsWhitespaceOnly() const;
/** /**
Removes the given node from the children list. Returns @true if the node was Removes the given node from the children list.
found and removed
or @false if the node could not be found. Returns @true if the node was found and removed or @false if the node
Note that the caller is reponsible for deleting the removed node in order to could not be found.
avoid memory leaks. Note that the caller is reponsible for deleting the removed node in order
to avoid memory leaks.
*/ */
bool RemoveChild(wxXmlNode* child); bool RemoveChild(wxXmlNode* child);
/** /**
Sets as first attribute the given wxXmlAttribute object. Sets as first attribute the given wxXmlAttribute object.
The caller is responsible to delete any previously present attributes attached
to this node. The caller is responsible to delete any previously present attributes
attached to this node.
*/ */
void SetAttributes(wxXmlAttribute* attr); void SetAttributes(wxXmlAttribute* attr);
/** /**
Sets as first child the given node. The caller is responsible to delete any Sets as first child the given node.
previously present
children node. The caller is responsible to delete any previously present children node.
*/ */
void SetChildren(wxXmlNode* child); void SetChildren(wxXmlNode* child);
@@ -241,16 +320,16 @@ public:
void SetName(const wxString& name); void SetName(const wxString& name);
/** /**
Sets as sibling the given node. The caller is responsible to delete any Sets as sibling the given node.
previously present
sibling node. The caller is responsible to delete any previously present sibling node.
*/ */
void SetNext(wxXmlNode* next); void SetNext(wxXmlNode* next);
/** /**
Sets as parent the given node. The caller is responsible to delete any Sets as parent the given node.
previously present
parent node. The caller is responsible to delete any previously present parent node.
*/ */
void SetParent(wxXmlNode* parent); void SetParent(wxXmlNode* parent);
@@ -262,7 +341,7 @@ public:
/** /**
See the copy constructor for more info. See the copy constructor for more info.
*/ */
wxXmlNode operator=(const wxXmlNode& node); wxXmlNode& operator=(const wxXmlNode& node);
}; };
@@ -272,7 +351,7 @@ public:
Represents a node attribute. Represents a node attribute.
Example: in @c img src="hello.gif" id="3"/, @c "src" is attribute with value Example: in @c "\<img src="hello.gif" id="3"/\>", @c "src" is attribute with value
@c "hello.gif" and @c "id" is a attribute with value @c "3". @c "hello.gif" and @c "id" is a attribute with value @c "3".
@library{wxxml} @library{wxxml}
@@ -283,15 +362,17 @@ public:
class wxXmlAttribute class wxXmlAttribute
{ {
public: public:
//@{
/** /**
Creates the attribute with given @a name and @e value. Default constructor.
If @a next is not @NULL, then sets it as sibling of this attribute.
*/ */
wxXmlAttribute(); wxXmlAttribute();
/**
Creates the attribute with given @a name and @a value.
If @a next is not @NULL, then sets it as sibling of this attribute.
*/
wxXmlAttribute(const wxString& name, const wxString& value, wxXmlAttribute(const wxString& name, const wxString& value,
wxXmlAttribute* next = NULL); wxXmlAttribute* next = NULL);
//@}
/** /**
The virtual destructor. The virtual destructor.
@@ -379,10 +460,9 @@ public:
} }
@endcode @endcode
@note if you want to preserve the original formatting of the loaded file Note that if you want to preserve the original formatting of the loaded file
including whitespaces including whitespaces and indentation, you need to turn off whitespace-only
and indentation, you need to turn off whitespace-only textnode removal and textnode removal and automatic indentation:
automatic indentation:
@code @code
wxXmlDocument doc; wxXmlDocument doc;
@@ -393,8 +473,7 @@ public:
@endcode @endcode
Using default parameters, you will get a reformatted document which in general Using default parameters, you will get a reformatted document which in general
is different from is different from the original loaded content:
the original loaded content:
@code @code
wxXmlDocument doc; wxXmlDocument doc;
@@ -410,15 +489,27 @@ public:
class wxXmlDocument : public wxObject class wxXmlDocument : public wxObject
{ {
public: public:
//@{ /**
Default constructor.
*/
wxXmlDocument();
/** /**
Copy constructor. Deep copies all the XML tree of the given document. Copy constructor. Deep copies all the XML tree of the given document.
*/ */
wxXmlDocument();
wxXmlDocument(const wxString& filename);
wxXmlDocument(wxInputStream& stream);
wxXmlDocument(const wxXmlDocument& doc); wxXmlDocument(const wxXmlDocument& doc);
//@}
/**
Loads the given filename using the given encoding. See Load().
*/
wxXmlDocument(const wxString& filename,
const wxString& encoding = wxT("UTF-8"));
/**
Loads the XML document from given stream using the given encoding. See Load().
*/
wxXmlDocument(wxInputStream& stream,
const wxString& encoding = wxT("UTF-8"));
/** /**
Virtual destructor. Frees the document root node. Virtual destructor. Frees the document root node.
@@ -426,25 +517,29 @@ public:
~wxXmlDocument(); ~wxXmlDocument();
/** /**
Detaches the document root node and returns it. The document root node will be Detaches the document root node and returns it.
set to @NULL
and thus IsOk() will return @false after calling this function. The document root node will be set to @NULL and thus IsOk() will
Note that the caller is reponsible for deleting the returned node in order to return @false after calling this function.
avoid memory leaks.
Note that the caller is reponsible for deleting the returned node in order
to avoid memory leaks.
*/ */
wxXmlNode* DetachRoot(); wxXmlNode* DetachRoot();
/** /**
Returns encoding of in-memory representation of the document Returns encoding of in-memory representation of the document
(same as passed to Load() or constructor, defaults to UTF-8). (same as passed to Load() or constructor, defaults to UTF-8).
@note this is meaningless in Unicode build where data are stored as @c wchar_t*. @note this is meaningless in Unicode build where data are stored as @c wchar_t*.
*/ */
wxString GetEncoding() const; wxString GetEncoding() const;
/** /**
Returns encoding of document (may be empty). Returns encoding of document (may be empty).
Note: this is the encoding original file was saved in, @b not the
encoding of in-memory representation! @note This is the encoding original file was saved in, @b not the
encoding of in-memory representation!
*/ */
wxString GetFileEncoding() const; wxString GetFileEncoding() const;
@@ -455,7 +550,8 @@ public:
/** /**
Returns the version of document. Returns the version of document.
This is the value in the @c ?xml version="1.0"? header of the XML document.
This is the value in the @c \<?xml version="1.0"?\> header of the XML document.
If the version attribute was not explicitely given in the header, this function If the version attribute was not explicitely given in the header, this function
returns an empty string. returns an empty string.
*/ */
@@ -466,23 +562,46 @@ public:
*/ */
bool IsOk() const; bool IsOk() const;
//@{
/**
, @b int@e flags = wxXMLDOC_NONE)
Like above but takes the data from given input stream.
*/
bool Load(const wxString& filename);
int bool Load(wxInputStream& stream);
//@}
//@{
/** /**
Saves XML tree in the given output stream. See other overload for a description Parses @a filename as an xml document and loads its data.
of @c indentstep.
If @a flags does not contain wxXMLDOC_KEEP_WHITESPACE_NODES, then, while loading,
all nodes of type @c wxXML_TEXT_NODE (see wxXmlNode) are automatically skipped
if they contain whitespaces only.
The removal of these nodes makes the load process slightly faster and requires
less memory however makes impossible to recreate exactly the loaded text with a
Save() call later. Read the initial description of this class for more info.
Returns true on success, false otherwise.
*/ */
bool Save(const wxString& filename, int indentstep = 1) const; virtual bool Load(const wxString& filename,
const bool Save(wxOutputStream& stream, int indentstep = 1) const; const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
//@}
/**
Like Load(const wxString&, const wxString&, int) but takes the data from
given input stream.
*/
virtual bool Load(wxInputStream& stream,
const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
/**
Saves XML tree creating a file named with given string.
If @a indentstep is greater than or equal to zero, then, while saving,
an automatic indentation is added with steps composed by indentstep spaces.
If @a indentstep is @c wxXML_NO_INDENTATION, then, automatic indentation
is turned off.
*/
virtual bool Save(const wxString& filename, int indentstep = 1) const;
/**
Saves XML tree in the given output stream.
See Save(const wxString&, int) for a description of @a indentstep.
*/
virtual bool Save(wxOutputStream& stream, int indentstep = 1) const;
/** /**
Sets the enconding of the document. Sets the enconding of the document.
@@ -496,9 +615,8 @@ public:
/** /**
Sets the root node of this document. Deletes previous root node. Sets the root node of this document. Deletes previous root node.
Use DetachRoot() and then Use DetachRoot() and then SetRoot() if you want to replace the root
SetRoot() if you want node without deleting the old document tree.
to replace the root node without deleting the old document tree.
*/ */
void SetRoot(wxXmlNode* node); void SetRoot(wxXmlNode* node);
@@ -510,6 +628,6 @@ public:
/** /**
Deep copies the given document. Deep copies the given document.
*/ */
wxXmlDocument& operator operator=(const wxXmlDocument& doc); wxXmlDocument& operator=(const wxXmlDocument& doc);
}; };

20
interface/wx/xrc/xmlres.h
View File

@@ -25,7 +25,7 @@ public:
//@{ //@{
/** /**
Constructor. Constructor.
@param flags @param flags
wxXRC_USE_LOCALE: translatable strings will be translated via _(). wxXRC_USE_LOCALE: translatable strings will be translated via _().
wxXRC_NO_SUBCLASSING: subclass property of object nodes will be ignored wxXRC_NO_SUBCLASSING: subclass property of object nodes will be ignored
@@ -237,7 +237,7 @@ public:
wxXmlResourceHandler is an abstract base class for resource handlers wxXmlResourceHandler is an abstract base class for resource handlers
capable of creating a control from an XML node. capable of creating a control from an XML node.
See @ref overview_xrcoverview "XML-based resource system overview" for details. See @ref overview_xrc for details.
@library{wxxrc} @library{wxxrc}
@category{xrc} @category{xrc}
@@ -291,9 +291,9 @@ public:
/** /**
Creates an object (menu, dialog, control, ...) from an XML node. Creates an object (menu, dialog, control, ...) from an XML node.
Should check for validity. @a parent is a higher-level object (usually window, Should check for validity. @a parent is a higher-level object
dialog or panel) (usually window, dialog or panel) that is often necessary to create the resource.
that is often necessary to create the resource.
If @b instance is non-@NULL it should not create a new instance via 'new' but If @b instance is non-@NULL it should not create a new instance via 'new' but
should rather use this one, and call its Create method. should rather use this one, and call its Create method.
*/ */
@@ -319,7 +319,7 @@ public:
wxBitmap GetBitmap(); wxBitmap GetBitmap();
/** /**
Gets a bool flag (1, t, yes, on, @true are @true, everything else is @false). Gets a bool flag (1, t, yes, on, true are @true, everything else is @false).
*/ */
bool GetBool(const wxString& param, bool defaultv = false); bool GetBool(const wxString& param, bool defaultv = false);
@@ -402,10 +402,10 @@ public:
/** /**
Gets text from param and does some conversions: Gets text from param and does some conversions:
replaces \\n, \\r, \\t by respective characters (according to C syntax) - replaces \\n, \\r, \\t by respective characters (according to C syntax)
replaces @c $ by @c and @c $$ by @c $ (needed for @c _File to @c File - replaces @c $ by @c and @c $$ by @c $ (needed for @c _File to @c File
translation because of XML syntax) translation because of XML syntax)
calls wxGetTranslations (unless disabled in wxXmlResource) - calls wxGetTranslations (unless disabled in wxXmlResource)
*/ */
wxString GetText(const wxString& param); wxString GetText(const wxString& param);

280
interface/wx/zipstrm.h
View File

@@ -6,33 +6,107 @@
// Licence: wxWindows license // Licence: wxWindows license
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
/// Compression Method, only 0 (store) and 8 (deflate) are supported here
enum wxZipMethod
{
wxZIP_METHOD_STORE,
wxZIP_METHOD_SHRINK,
wxZIP_METHOD_REDUCE1,
wxZIP_METHOD_REDUCE2,
wxZIP_METHOD_REDUCE3,
wxZIP_METHOD_REDUCE4,
wxZIP_METHOD_IMPLODE,
wxZIP_METHOD_TOKENIZE,
wxZIP_METHOD_DEFLATE,
wxZIP_METHOD_DEFLATE64,
wxZIP_METHOD_BZIP2 = 12,
wxZIP_METHOD_DEFAULT = 0xffff
};
/// Originating File-System.
///
/// These are Pkware's values. Note that Info-zip disagree on some of them,
/// most notably NTFS.
enum wxZipSystem
{
wxZIP_SYSTEM_MSDOS,
wxZIP_SYSTEM_AMIGA,
wxZIP_SYSTEM_OPENVMS,
wxZIP_SYSTEM_UNIX,
wxZIP_SYSTEM_VM_CMS,
wxZIP_SYSTEM_ATARI_ST,
wxZIP_SYSTEM_OS2_HPFS,
wxZIP_SYSTEM_MACINTOSH,
wxZIP_SYSTEM_Z_SYSTEM,
wxZIP_SYSTEM_CPM,
wxZIP_SYSTEM_WINDOWS_NTFS,
wxZIP_SYSTEM_MVS,
wxZIP_SYSTEM_VSE,
wxZIP_SYSTEM_ACORN_RISC,
wxZIP_SYSTEM_VFAT,
wxZIP_SYSTEM_ALTERNATE_MVS,
wxZIP_SYSTEM_BEOS,
wxZIP_SYSTEM_TANDEM,
wxZIP_SYSTEM_OS_400
};
/// Dos/Win file attributes
enum wxZipAttributes
{
wxZIP_A_RDONLY = 0x01,
wxZIP_A_HIDDEN = 0x02,
wxZIP_A_SYSTEM = 0x04,
wxZIP_A_SUBDIR = 0x10,
wxZIP_A_ARCH = 0x20,
wxZIP_A_MASK = 0x37
};
/// Values for the flags field in the zip headers
enum wxZipFlags
{
wxZIP_ENCRYPTED = 0x0001,
wxZIP_DEFLATE_NORMAL = 0x0000, // normal compression
wxZIP_DEFLATE_EXTRA = 0x0002, // extra compression
wxZIP_DEFLATE_FAST = 0x0004, // fast compression
wxZIP_DEFLATE_SUPERFAST = 0x0006, // superfast compression
wxZIP_DEFLATE_MASK = 0x0006,
wxZIP_SUMS_FOLLOW = 0x0008, // crc and sizes come after the data
wxZIP_ENHANCED = 0x0010,
wxZIP_PATCH = 0x0020,
wxZIP_STRONG_ENC = 0x0040,
wxZIP_UNUSED = 0x0F80,
wxZIP_RESERVED = 0xF000
};
/** /**
@class wxZipNotifier @class wxZipNotifier
If you need to know when a wxZipInputStream If you need to know when a wxZipInputStream updates a wxZipEntry,
updates a wxZipEntry,
you can create a notifier by deriving from this abstract base class, you can create a notifier by deriving from this abstract base class,
overriding wxZipNotifier::OnEntryUpdated. overriding wxZipNotifier::OnEntryUpdated().
An instance of your notifier class can then be assigned to wxZipEntry An instance of your notifier class can then be assigned to wxZipEntry
objects, using wxZipEntry::SetNotifier. objects, using wxZipEntry::SetNotifier().
Setting a notifier is not usually necessary. It is used to handle Setting a notifier is not usually necessary. It is used to handle
certain cases when modifying an zip in a pipeline (i.e. between certain cases when modifying an zip in a pipeline (i.e. between
non-seekable streams). non-seekable streams).
See '@ref overview_wxarcnoseek "Archives on non-seekable streams"'. See @ref overview_archive_noseek.
@library{wxbase} @library{wxbase}
@category{FIXME} @category{archive}
@see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipEntry, @see @ref overview_archive_noseek, wxZipEntry, wxZipInputStream, wxZipOutputStream
wxZipInputStream, wxZipOutputStream
*/ */
class wxZipNotifier class wxZipNotifier
{ {
public: public:
/** /**
Override this to receive notifications when Override this to receive notifications when an wxZipEntry object changes.
an wxZipEntry object changes.
*/ */
void OnEntryUpdated(wxZipEntry& entry); void OnEntryUpdated(wxZipEntry& entry);
}; };
@@ -44,22 +118,61 @@ public:
Holds the meta-data for an entry in a zip. Holds the meta-data for an entry in a zip.
@library{wxbase} @section zipentry_avail Field availability
@category{FIXME}
@see @ref overview_wxarc "Archive formats such as zip", wxZipInputStream, When reading a zip from a stream that is seekable, wxZipEntry::GetNextEntry()
wxZipOutputStream, wxZipNotifier returns a fully populated wxZipEntry object except for wxZipEntry::GetLocalExtra().
wxZipEntry::GetLocalExtra() becomes available when the entry is opened, either by
calling wxZipInputStream::OpenEntry() or by making an attempt to read the entry's data.
For zips on non-seekable streams, the following fields are always available
when wxZipEntry::GetNextEntry() returns:
- wxZipEntry::GetDateTime
- wxZipEntry::GetInternalFormat
- wxZipEntry::GetInternalName
- wxZipEntry::GetFlags
- wxZipEntry::GetLocalExtra
- wxZipEntry::GetMethod
- wxZipEntry::GetName
- wxZipEntry::GetOffset
- wxZipEntry::IsDir
The following fields are also usually available when GetNextEntry() returns,
however, if the zip was also written to a non-seekable stream the zipper is
permitted to store them after the entry's data. In that case they become
available when the entry's data has been read to Eof(), or CloseEntry()
has been called. (GetFlags() & wxZIP_SUMS_FOLLOW) != 0 indicates that
one or more of these come after the data:
- wxZipEntry::GetCompressedSize
- wxZipEntry::GetCrc
- wxZipEntry::GetSize
The following are stored at the end of the zip, and become available when the
end of the zip has been reached, i.e. after GetNextEntry() returns @NULL
and Eof() is true:
- wxZipEntry::GetComment
- wxZipEntry::GetExternalAttributes
- wxZipEntry::GetExtra
- wxZipEntry::GetMode
- wxZipEntry::GetSystemMadeBy
- wxZipEntry::IsReadOnly
- wxZipEntry::IsMadeByUnix
- wxZipEntry::IsText
@library{wxbase}
@category{archive}
@see @ref overview_archive, wxZipInputStream, wxZipOutputStream, wxZipNotifier
*/ */
class wxZipEntry : public wxArchiveEntry class wxZipEntry : public wxArchiveEntry
{ {
public: public:
//@{ wxZipEntry(const wxString& name = wxEmptyString);
/** /**
Copy constructor. Copy constructor.
*/ */
wxZipEntry(const wxString& name = wxEmptyString);
wxZipEntry(const wxZipEntry& entry); wxZipEntry(const wxZipEntry& entry);
//@}
/** /**
Make a copy of this entry. Make a copy of this entry.
@@ -68,91 +181,95 @@ public:
//@{ //@{
/** /**
A short comment for this entry. Gets and sets the short comment for this entry.
*/ */
wxString GetComment(); wxString GetComment() const;
const void SetComment(const wxString& comment); void SetComment(const wxString& comment);
//@} //@}
//@{ //@{
/** /**
The low 8 bits are always the DOS/Windows file attributes for this entry. The low 8 bits are always the DOS/Windows file attributes for this entry.
The values of these attributes are given in the The values of these attributes are given in the enumeration ::wxZipAttributes.
enumeration @c wxZipAttributes.
The remaining bits can store platform specific permission bits or The remaining bits can store platform specific permission bits or
attributes, and their meaning depends on the value attributes, and their meaning depends on the value of SetSystemMadeBy().
of @ref systemmadeby() SetSystemMadeBy. If IsMadeByUnix() is @true then the high 16 bits are unix mode bits.
If IsMadeByUnix() is @true then the
high 16 bits are unix mode bits.
The following other accessors access these bits: The following other accessors access these bits:
@ref wxArchiveEntry::isreadonly IsReadOnly/SetIsReadOnly - IsReadOnly() / SetIsReadOnly()
- IsDir() / SetIsDir()
@ref wxArchiveEntry::isdir IsDir/SetIsDir - GetMode() / SetMode()
@ref mode() Get/SetMode
*/ */
wxUint32 GetExternalAttributes(); wxUint32 GetExternalAttributes() const;
const void SetExternalAttributes(wxUint32 attr); void SetExternalAttributes(wxUint32 attr);
//@} //@}
//@{ //@{
/** /**
The extra field from the entry's central directory record. The extra field from the entry's central directory record.
The extra field is used to store platform or application specific The extra field is used to store platform or application specific
data. See Pkware's document 'appnote.txt' for information on its format. data. See Pkware's document 'appnote.txt' for information on its format.
*/ */
const char* GetExtra(); char* GetExtra() const;
const size_t GetExtraLen(); size_t GetExtraLen() const;
const void SetExtra(const char* extra, size_t len); void SetExtra(const char* extra, size_t len);
//@} //@}
//@{ //@{
/** /**
The extra field from the entry's local record. The extra field from the entry's local record.
The extra field is used to store platform or application specific The extra field is used to store platform or application specific
data. See Pkware's document 'appnote.txt' for information on its format. data. See Pkware's document 'appnote.txt' for information on its format.
*/ */
const char* GetLocalExtra(); char* GetLocalExtra() const;
const size_t GetLocalExtraLen(); size_t GetLocalExtraLen() const;
const void SetLocalExtra(const char* extra, size_t len); void SetLocalExtra(const char* extra, size_t len);
//@} //@}
//@{ //@{
/** /**
The compression method. The enumeration @c wxZipMethod lists the The compression method.
possible values. The enumeration ::wxZipMethod lists the possible values.
The default constructor sets this to wxZIP_METHOD_DEFAULT,
which allows wxZipOutputStream to The default constructor sets this to @c wxZIP_METHOD_DEFAULT,
choose the method when writing the entry. which allows wxZipOutputStream to choose the method when writing the entry.
*/ */
int GetMethod(); int GetMethod() const;
const void SetMethod(int method); void SetMethod(int method);
//@} //@}
//@{ //@{
/** /**
Sets the DOS attributes If IsMadeByUnix() is true then returns the unix permission bits stored
in @ref externalattributes() GetExternalAttributes in GetExternalAttributes(). Otherwise synthesises them from the DOS attributes.
to be consistent with the @c mode given. */
If IsMadeByUnix() is @true then also int GetMode() const;
stores @c mode in GetExternalAttributes().
Note that the default constructor /**
sets @ref systemmadeby() GetSystemMadeBy to Sets the DOS attributes in GetExternalAttributes() to be consistent with
wxZIP_SYSTEM_MSDOS by default. So to be able to store unix the @a mode given.
If IsMadeByUnix() is @true then also stores @a mode in GetExternalAttributes().
Note that the default constructor sets GetSystemMadeBy() to
@c wxZIP_SYSTEM_MSDOS by default. So to be able to store unix
permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX). permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX).
*/ */
int GetMode(); void SetMode(int mode);
const void SetMode(int mode);
//@} //@}
//@{ //@{
/** /**
The originating file-system. The default constructor sets this to The originating file-system.
wxZIP_SYSTEM_MSDOS. Set it to wxZIP_SYSTEM_UNIX in order to be
able to store unix permissions using @ref mode() SetMode. The default constructor sets this to @c wxZIP_SYSTEM_MSDOS.
Set it to @c wxZIP_SYSTEM_UNIX in order to be able to store unix
permissions using SetMode().
*/ */
int GetSystemMadeBy(); int GetSystemMadeBy() const;
const void SetSystemMadeBy(int system); void SetSystemMadeBy(int system);
//@} //@}
/** /**
@@ -177,17 +294,23 @@ public:
to is set to indicate whether the name looks like a directory name to is set to indicate whether the name looks like a directory name
(i.e. has a trailing path separator). (i.e. has a trailing path separator).
@see @ref overview_wxarcbyname "Looking up an archive entry by name" @see @ref overview_archive_byname
*/ */
wxString GetInternalName(); wxString GetInternalName(const wxString& name,
const wxString GetInternalName(const wxString& name, wxPathFormat format = wxPATH_NATIVE,
wxPathFormat format = wxPATH_NATIVE, bool* pIsDir = NULL);
bool* pIsDir = NULL); /**
Returns the entry's filename in the internal format used within the archive.
The name can include directory components, i.e. it can be a full path.
The names of directory entries are returned without any trailing path separator.
This gives a canonical name that can be used in comparisons.
*/
wxString GetInternalName() const;
//@} //@}
/** /**
Returns @true if @ref systemmadeby() GetSystemMadeBy Returns @true if GetSystemMadeBy() is a flavour of unix.
is a flavour of unix.
*/ */
bool IsMadeByUnix() const; bool IsMadeByUnix() const;
@@ -195,22 +318,21 @@ public:
/** /**
Indicates that this entry's data is text in an 8-bit encoding. Indicates that this entry's data is text in an 8-bit encoding.
*/ */
bool IsText(); bool IsText() const;
const void SetIsText(bool isText = true); void SetIsText(bool isText = true);
//@} //@}
//@{ //@{
/** /**
Sets the notifier() for this entry. Sets the notifier (see wxZipNotifier) for this entry.
Whenever the wxZipInputStream updates Whenever the wxZipInputStream updates this entry, it will then invoke
this entry, it will then invoke the associated the associated notifier's wxZipNotifier::OnEntryUpdated() method.
notifier's wxZipNotifier::OnEntryUpdated
method.
Setting a notifier is not usually necessary. It is used to handle Setting a notifier is not usually necessary. It is used to handle
certain cases when modifying an zip in a pipeline (i.e. between certain cases when modifying an zip in a pipeline (i.e. between
non-seekable streams). non-seekable streams).
@see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipNotifier @see @ref overview_archive_noseek, wxZipNotifier
*/ */
void SetNotifier(wxZipNotifier& notifier); void SetNotifier(wxZipNotifier& notifier);
void UnsetNotifier(); void UnsetNotifier();
@@ -219,11 +341,15 @@ public:
/** /**
Assignment operator. Assignment operator.
*/ */
wxZipEntry& operator operator=(const wxZipEntry& entry); wxZipEntry& operator=(const wxZipEntry& entry);
}; };
---
/** /**
@class wxZipInputStream @class wxZipInputStream