diff --git a/interface/wx/file.h b/interface/wx/file.h index 0b41f1c4b8..2522be80e1 100644 --- a/interface/wx/file.h +++ b/interface/wx/file.h @@ -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 -#define wxS_IWUSR 00200 -#define wxS_IXUSR 00100 +enum wxPosixPermissions +{ + /// standard Posix names for these permission flags + //@{ + wxS_IRUSR = 00400, + wxS_IWUSR = 00200, + wxS_IXUSR = 00100, -#define wxS_IRGRP 00040 -#define wxS_IWGRP 00020 -#define wxS_IXGRP 00010 + wxS_IRGRP = 00040, + wxS_IWGRP = 00020, + wxS_IXGRP = 00010, -#define wxS_IROTH 00004 -#define wxS_IWOTH 00002 -#define wxS_IXOTH 00001 + wxS_IROTH = 00004, + wxS_IWOTH = 00002, + wxS_IXOTH = 00001, + //@} -/** Default mode for the new files: corresponds to umask 022 */ -#define wxS_DEFAULT (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH) -//@} + /// longer but more readable synonims for the constants above + //@{ + 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 it is overwritten. - @a access may be an OR combination of the file access values - like ::wxS_IRUSR, ::wxS_IWUSR, etc, etc. + @a access may be an OR combination of the ::wxPosixPermissions enumeration + values. */ bool Create(const wxString& filename, bool overwrite = false, @@ -343,9 +374,12 @@ public: The filename. @param mode The mode in which to open the file. + @param access + An OR-combination of wxPosixPermissions enumeration values. */ 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. diff --git a/interface/wx/filename.h b/interface/wx/filename.h index f44879b813..5280a24026 100644 --- a/interface/wx/filename.h +++ b/interface/wx/filename.h @@ -830,7 +830,8 @@ public: Creates a directory. @param perm - The permissions for the newly created directory + The permissions for the newly created directory. + See wxPosixPermissions enumeration for more info. @param flags 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 @@ -839,24 +840,25 @@ public: @return Returns @true if the directory was successfully created, @false otherwise. */ - bool Mkdir(int perm = 0777, int flags = 0); + bool Mkdir(int perm = wxS_DIR_DEFAULT, int flags = 0); /** Creates a directory. @param dir - the directory to create + The directory to create @param parm - the permissions for the newly created directory + The permissions for the newly created directory. + See wxPosixPermissions enumeration for more info. @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 already exists. @return Returns @true if the directory was successfully created, @false otherwise. */ - static bool Mkdir(const wxString& dir, int perm = 0777, + static bool Mkdir(const wxString& dir, int perm = wxS_DIR_DEFAULT, int flags = 0); /** diff --git a/interface/wx/window.h b/interface/wx/window.h index 62b402c0e1..63c45eb614 100644 --- a/interface/wx/window.h +++ b/interface/wx/window.h @@ -399,7 +399,6 @@ public: */ void ClearBackground(); - //@{ /** Converts to screen coordinates from coordinates relative to this window. @@ -409,8 +408,6 @@ public: @param y A pointer to a integer value for the y coordinate. Pass the client coordinate in, and a screen coordinate will be passed out. - @param pt - The client position for the second form of the function. @beginWxPythonOnly In place of a single overloaded method name, wxPython implements the following methods: @@ -419,8 +416,14 @@ public: @endWxPythonOnly */ 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; - //@} /** Converts client area size @a size to corresponding window size. @@ -1083,7 +1086,6 @@ public: */ virtual wxWindow* GetParent() const; - //@{ /** 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 @@ -1094,19 +1096,19 @@ public: The menu to show @param pos 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 error occurred. */ 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 for the child windows or relative to the display origin for the top level windows. @@ -1119,8 +1121,14 @@ public: @see GetScreenPosition() */ 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; - //@} /** Returns the previous window before this one among the parent children or @c @@ -1139,7 +1147,6 @@ public: */ wxRect GetRect() const; - //@{ /** Returns the window position in screen coordinates, whether the window is a child window or a top level one. @@ -1152,8 +1159,14 @@ public: @see GetPosition() */ 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; - //@} /** 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); - //@{ /** Returns the size of the entire window in pixels, including title bar, border, scrollbars, etc. @@ -1199,8 +1211,11 @@ public: @see GetClientSize(), GetVirtualSize() */ void GetSize(int* width, int* height) const; + + /** + See the GetSize(int*,int*) overload for more info. + */ wxSize GetSize() const; - //@} /** Return the sizer associated with the window by a previous call to @@ -1208,7 +1223,6 @@ public: */ wxSizer* GetSizer() const; - //@{ /** Gets the dimensions of the string as it would be drawn on the window with the currently selected font. @@ -1241,7 +1255,6 @@ public: window with the currently selected font. */ wxSize GetTextExtent(const wxString& string) const; - //@} /** Get the associated tooltip or @NULL if none. @@ -2379,31 +2392,29 @@ public: @param refresh @true to redraw the scrollbar, @false otherwise. - @remarks Let's say you wish to display 50 lines of text, using the same - font. The window is sized so that you can only see 16 - lines at a time. - You would use: - @code - SetScrollbar(wxVERTICAL, 0, 16, 50); - @endcode - 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 - currently visible by dividing the current view size by the character - height in pixels. - When defining your own scrollbar behaviour, you will always need - to recalculate the scrollbar settings when the window size changes. - You could therefore put your scrollbar calculations and SetScrollbar - call into a function named AdjustScrollbars, which can be called - initially and also from your wxSizeEvent handler function. + @remarks + Let's say you wish to display 50 lines of text, using the same font. + The window is sized so that you can only see 16 lines at a time. + You would use: + @code + SetScrollbar(wxVERTICAL, 0, 16, 50); + @endcode + 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 + currently visible by dividing the current view size by the character + height in pixels. + When defining your own scrollbar behaviour, you will always need + to recalculate the scrollbar settings when the window size changes. + You could therefore put your scrollbar calculations and SetScrollbar + call into a function named AdjustScrollbars, which can be called + initially and also from your wxSizeEvent handler function. @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent */ virtual void SetScrollbar(int orientation, int position, - int thumbSize, - int range, + int thumbSize, int range, bool refresh = true); - //@{ /** Sets the size of the window in pixels. @@ -2419,10 +2430,6 @@ public: @param height Required height position in pixels, or wxDefaultCoord to indicate that the 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 Indicates the interpretation of other parameters. It is a bit list of the following: @@ -2444,10 +2451,7 @@ public: later and only implemented for MSW and ignored elsewhere currently). - @remarks The second form is a convenience for calling the first form with - 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. + @remarks This overload sets the position and optionally size, of the window. Parameters may be wxDefaultCoord to indicate either that a default should be supplied by wxWidgets, or that the current value of the dimension should be used. @@ -2456,9 +2460,19 @@ public: */ virtual void SetSize(int x, int y, int width, int height, 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(int width, int height); virtual void SetSize(const wxSize& size); + virtual void SetSize(int width, int height); //@} /** diff --git a/interface/wx/windowid.h b/interface/wx/windowid.h index 031be36a8a..58d02cf627 100644 --- a/interface/wx/windowid.h +++ b/interface/wx/windowid.h @@ -9,27 +9,25 @@ /** @class wxIdManager - wxIdManager is responsible for allocating and releasing window IDs. It - is used by wxWindow::NewControlId and - wxWindow::UnreserveControlId, and can also - be used be used directly. + wxIdManager is responsible for allocating and releasing window IDs. + It is used by wxWindow::NewControlId() and wxWindow::UnreserveControlId(), + and can also be used be used directly. @library{wxcore} - @category{FIXME} + @category{misc} - @see wxWindow::NewControlId, wxWindow::UnreserveControlId, @ref - overview_windowidsoverview "Window IDs overview" + @see wxWindow::NewControlId(), wxWindow::UnreserveControlId(), + @ref overview_windowids */ class wxIdManager { public: /** - Called directly by wxWindow::NewControlId, - this function will create a new ID or range of IDs. The IDs will be - reserved until assigned to a wxWindowIDRef() - or unreserved with UnreserveControlId(). - Only ID values that are not assigned to a wxWindowIDRef() - need to be unreserved. + Called directly by wxWindow::NewControlId(), this function will create + a new ID or range of IDs. + The IDs will be reserved until assigned to a wxWindowIDRef() or unreserved + with UnreserveControlId(). + Only ID values that are not assigned to a wxWindowIDRef() need to be unreserved. @param count 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. */ 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); }; diff --git a/interface/wx/wizard.h b/interface/wx/wizard.h index 2ca1fef455..17a1f30944 100644 --- a/interface/wx/wizard.h +++ b/interface/wx/wizard.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: wizard.h -// Purpose: interface of wxWizardPage +// Purpose: interface of wxWizardPage, wxWizardEvent, // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -9,21 +9,29 @@ /** @class wxWizardPage - wxWizardPage is one of the screens in wxWizard: it must - know what are the following and preceding pages (which may be @NULL for the - first/last page). Except for this extra knowledge, wxWizardPage is just a + wxWizardPage is one of the screens in wxWizard: it must know what are the + following and preceding pages (which may be @NULL for the first/last page). + Except for this extra knowledge, wxWizardPage is just a 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 - dynamically (during run-time) and so provides maximal flexibility. Usually, - however, the order of pages is known in advance in which case - wxWizardPageSimple class is enough and it is simpler - to use. + dynamically (during run-time) and so provides maximal flexibility. + Usually, however, the order of pages is known in advance in which case + wxWizardPageSimple class is enough and it is simpler 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} @category{miscwnd} - @see wxWizard, @ref overview_samplewizard "wxWizard sample" + @see wxWizard, @ref page_samples_wizard */ class wxWizardPage : public wxPanel { @@ -43,11 +51,13 @@ public: const wxBitmap& bitmap = wxNullBitmap); /** - This method is called by wxWizard to get the bitmap to display alongside the - page. By default, @c m_bitmap member variable which was set in the - @ref wxwizardpage() constructor. - If the bitmap was not explicitly set (i.e. if @c wxNullBitmap is returned), + This method is called by wxWizard to get the bitmap to display alongside the page. + By default, @c m_bitmap member variable which was set in the + @ref wxWizardPage() constructor. + + If the bitmap was not explicitly set (i.e. if ::wxNullBitmap is returned), the default bitmap for the wizard should be used. + 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. */ @@ -55,9 +65,9 @@ public: /** 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 - page of the wizard will usually return @NULL from here, but the others - will not. + button: if @NULL is returned, this button will be disabled. + The last page of the wizard will usually return @NULL from here, but + the others will not. @see GetPrev() */ @@ -65,9 +75,9 @@ public: /** 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 - page of the wizard will usually return @NULL from here, but the others - will not. + button: if @NULL is returned, this button will be disabled. + The first page of the wizard will usually return @NULL from here, but + the others will not. @see GetNext() */ @@ -79,37 +89,50 @@ public: /** @class wxWizardEvent - wxWizardEvent class represents an event generated by the - wizard(): this event is first sent to the page itself and, - if not processed there, goes up the window hierarchy as usual. + wxWizardEvent class represents an event generated by the wxWizard: this event + is first sent to the page itself and, if not processed there, goes up the + 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} @category{events} - @see wxWizard, @ref overview_samplewizard "wxWizard sample" + @see wxWizard, @ref page_samples_wizard */ class wxWizardEvent : public wxNotifyEvent { 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. */ wxWizardEvent(wxEventType type = wxEVT_NULL, int id = -1, bool direction = true); /** - Return the direction in which the page is changing: for @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 - we came from the previous page and @false if we returned from the next - one. + Return the direction in which the page is changing: for + @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 we + came from the previous page and @false if we returned from the next one. */ bool GetDirection() const; /** - Returns the wxWizardPage which was active when this - event was generated. + Returns the wxWizardPage which was active when this event was generated. */ wxWizardPage* GetPage() const; }; @@ -119,27 +142,25 @@ public: /** @class wxWizardPageSimple - wxWizardPageSimple is the simplest possible - wxWizardPage implementation: it just returns the - pointers given to its constructor from GetNext() and GetPrev() functions. + wxWizardPageSimple is the simplest possible wxWizardPage implementation: + it just returns the pointers given to its constructor from wxWizardPage::GetNext() + and wxWizardPage::GetPrev() functions. 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 - case you must derive your own class from wxWizardPage - instead. + case you must derive your own class from wxWizardPage instead. @library{wxadv} @category{miscwnd} - @see wxWizard, @ref overview_samplewizard "wxWizard sample" + @see wxWizard, @ref page_samples_wizard */ class wxWizardPageSimple : public wxWizardPage { public: /** - Constructor takes the previous and next pages. They may be modified later by - SetPrev() or - SetNext(). + Constructor takes the previous and next pages. + They may be modified later by SetPrev() or SetNext(). */ wxWizardPageSimple(wxWizard* parent = NULL, wxWizardPage* prev = NULL, @@ -149,6 +170,13 @@ public: /** A convenience function to make the pages follow each other. Example: + + @code + wxRadioboxPage *page3 = new wxRadioboxPage(wizard); + wxValidationPage *page4 = new wxValidationPage(wizard); + + wxWizardPageSimple::Chain(page3, page4); + @endcode */ static void Chain(wxWizardPageSimple* first, wxWizardPageSimple* second); @@ -169,53 +197,85 @@ public: /** @class wxWizard - wxWizard is the central class for implementing 'wizard-like' dialogs. 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 - buttons to navigate to the next (and previous) pages. + wxWizard is the central class for implementing 'wizard-like' dialogs. + 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 buttons to + navigate to the next (and previous) pages. 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 to keep them as simple as possible. 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 - the - wxWizard::Create function. Then you should add all pages you - want the wizard to show and call wxWizard::RunWizard. - Finally, don't forget to call @c wizard-Destroy(), otherwise your application + using either the non-default constructor or a default one followed by call to the + wxWizard::Create function. Then you should add all pages you want the wizard to + show and call wxWizard::RunWizard(). + Finally, don't forget to call @c "wizard->Destroy()", otherwise your application 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 - pages + You can supply a bitmap to display on the left of the wizard, either for all pages or for individual pages. If you need to have the bitmap resize to the height of - the wizard, - call wxWizard::SetBitmapPlacement and if necessary, - wxWizard::SetBitmapBackgroundColour and wxWizard::SetMinimumBitmapWidth. + the wizard, call wxWizard::SetBitmapPlacement() and if necessary, + wxWizard::SetBitmapBackgroundColour() and wxWizard::SetMinimumBitmapWidth(). To make wizard pages scroll when the display is too small to fit the whole - dialog, you can switch - layout adaptation on globally with wxDialog::EnableLayoutAdaptation or - per dialog with wxDialog::SetLayoutAdaptationMode. For more - about layout adaptation, see @ref overview_autoscrollingdialogs "Automatic - scrolling dialogs". + dialog, you can switch layout adaptation on globally with + wxDialog::EnableLayoutAdaptation() or per dialog with wxDialog::SetLayoutAdaptationMode(). + For more about layout adaptation, see @ref overview_dialog_autoscrolling. + + @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} @category{cmndlg} - @see wxWizardEvent, wxWizardPage, @ref overview_samplewizard "wxWizard sample" + @see wxWizardEvent, wxWizardPage, @ref page_samples_wizard */ class wxWizard : public wxDialog { 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 shouldn't call Create(). + 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 - default size by default. If you want to change this, you should use the - GetPageAreaSizer() function. + default size by default. + If you want to change this, you should use the GetPageAreaSizer() function. @param parent The parent window, may be @NULL. @@ -224,29 +284,26 @@ public: @param title The title of the dialog. @param bitmap - The default bitmap used in the left side of the wizard. See - also GetBitmap. + The default bitmap used in the left side of the wizard. See also GetBitmap(). @param pos - The position of the dialog, it will be centered on the screen - by default. + The position of the dialog, it will be centered on the screen by default. @param style Window style is passed to wxDialog. */ - wxWizard(); wxWizard(wxWindow* parent, int id = -1, const wxString& title = wxEmptyString, const wxBitmap& bitmap = wxNullBitmap, const wxPoint& pos = wxDefaultPosition, long style = wxDEFAULT_DIALOG_STYLE); - //@} /** - Creates the wizard dialog. Must be called if the default constructor had been - used to create the object. + Creates the wizard dialog. + 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 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 - GetPageAreaSizer() function. + default size by default. + If you want to change this, you should use the GetPageAreaSizer() function. @param parent The parent window, may be @NULL. @@ -255,11 +312,9 @@ public: @param title The title of the dialog. @param bitmap - The default bitmap used in the left side of the wizard. See - also GetBitmap. + The default bitmap used in the left side of the wizard. See also GetBitmap(). @param pos - The position of the dialog, it will be centered on the screen - by default. + The position of the dialog, it will be centered on the screen by default. @param style Window style is passed to wxDialog. */ @@ -270,10 +325,11 @@ public: long style = wxDEFAULT_DIALOG_STYLE); /** - This method is obsolete, use - GetPageAreaSizer() instead. + This method is obsolete, use GetPageAreaSizer() instead. + 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. + 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. 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. */ - const wxBitmap GetBitmap() const; + const wxBitmap& GetBitmap() const; /** Returns the colour that should be used to fill the area not taken up by the - wizard or page bitmap, - if a non-zero bitmap placement flag has been set. + wizard or page bitmap, if a non-zero bitmap placement flag has been set. + See also SetBitmapPlacement(). */ - const wxColour GetBitmapBackgroundColour() const; + const wxColour& GetBitmapBackgroundColour() const; /** Returns the flags indicating how the wizard or page bitmap should be expanded - and positioned to fit the - page height. By default, placement is 0 (no expansion is done). + and positioned to fit the page height. By default, placement is 0 (no expansion is done). + See also SetBitmapPlacement() for the possible values. */ int GetBitmapPlacement(); /** - Get the current page while the wizard is running. @NULL is returned if - RunWizard() is not being executed now. + Get the current page while the wizard is running. + @NULL is returned if RunWizard() is not being executed now. */ wxWizardPage* GetCurrentPage() const; /** Returns the minimum width for the bitmap that will be constructed to contain - the actual wizard or page bitmap - if a non-zero bitmap placement flag has been set. + the actual wizard or page bitmap if a non-zero bitmap placement flag has been set. + See also SetBitmapPlacement(). */ int GetMinimumBitmapWidth() const; @@ -320,28 +376,26 @@ public: /** 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 - before - being shown to match the wizard page area. - Page area sizer has a minimal size that is the maximum of several values. First, - all pages (or other objects) added to the sizer. Second, all pages reachable - by repeatedly applying - wxWizardPage::GetNext to - any page inserted into the sizer. Third, - the minimal size specified using SetPageSize() and - FitToPage(). Fourth, the total wizard height may - be increased to accommodate the bitmap height. Fifth and finally, wizards are - 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. If @c wxRESIZE_BORDER was passed to constructor, user - can resize wizard and consequently the page area (but not make it smaller than - the - minimal size). - It is recommended to add the first page to the page area sizer. For simple - wizards, - this will enlarge the wizard to fit the biggest page. For non-linear wizards, - the first page of every separate chain should be added. Caller-specified size - can be accomplished using wxSizer::SetMinSize. + before being shown to match the wizard page area. + + Page area sizer has a minimal size that is the maximum of several values. + First, all pages (or other objects) added to the sizer. Second, all pages reachable + by repeatedly applying wxWizardPage::GetNext() to any page inserted into the sizer. + + Third, the minimal size specified using SetPageSize() and FitToPage(). + Fourth, the total wizard height may be increased to accommodate the bitmap height. + Fifth and finally, wizards are 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. + If @c wxRESIZE_BORDER was passed to constructor, user can resize wizard and + consequently the page area (but not make it smaller than the minimal size). + + It is recommended to add the first page to the page area sizer. + For simple wizards, this will enlarge the wizard to fit the biggest page. + + For non-linear wizards, 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 area that can be altered with SetBorder(). */ @@ -353,20 +407,20 @@ public: wxSize GetPageSize() const; /** - Return @true if this page is not the last one in the wizard. The base - class version implements this by calling - @ref wxWizardPage::getnext page-GetNext but this could be undesirable if, - for example, the pages are created on demand only. + Return @true if this page is not the last one in the wizard. + The base class version implements this by calling + @ref wxWizardPage::GetNext "page->GetNext" but this could be + undesirable if, for example, the pages are created on demand only. @see HasPrevPage() */ virtual bool HasNextPage(wxWizardPage* page); /** - Returns @true if this page is not the last one in the wizard. The base - class version implements this by calling - @ref wxWizardPage::getprev page-GetPrev but this could be undesirable if, - for example, the pages are created on demand only. + Returns @true if this page is not the last one in the wizard. + The base class version implements this by calling + @ref wxWizardPage::GetPrev "page->GetPrev" but this could be + undesirable if, for example, the pages are created on demand only. @see HasNextPage() */ @@ -374,8 +428,8 @@ public: /** Executes the wizard starting from the given page, returning @true if it was - successfully finished or @false if user cancelled it. The @a firstPage - can not be @NULL. + successfully finished or @false if user cancelled it. + The @a firstPage can not be @NULL. */ 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 - or page bitmap, - if a non-zero bitmap placement flag has been set. + or page bitmap, if a non-zero bitmap placement flag has been set. + See also SetBitmapPlacement(). */ void SetBitmapBackgroundColour(const wxColour& colour); /** Sets the flags indicating how the wizard or page bitmap should be expanded and - positioned to fit the - page height. By default, placement is 0 (no expansion is done). @a placement is - a bitlist with the + positioned to fit the page height. + + By default, placement is 0 (no expansion is done). @a placement is a bitlist with the following possible values: - @b wxWIZARD_VALIGN_TOP - - Aligns the bitmap at the top. - - @b wxWIZARD_VALIGN_CENTRE - - Centres the bitmap vertically. - - @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 - + - @b wxWIZARD_VALIGN_TOP: Aligns the bitmap at the top. + - @b wxWIZARD_VALIGN_CENTRE: Centres the bitmap vertically. + - @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: @todo describe this See also SetMinimumBitmapWidth(). */ void SetBitmapPlacement(int placement); /** - Sets width of border around page area. Default is zero. For backward - compatibility, if there are no pages in - GetPageAreaSizer(), the default is 5 pixels. + Sets width of border around page area. Default is zero. + For backward compatibility, if there are no pages in GetPageAreaSizer(), + the default is 5 pixels. + If there is a five point border around all controls in a page and the border - around - page area is left as zero, a five point white space along all dialog borders + around 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 - from the dialog - border and non-page controls. + from the dialog border and non-page controls. */ void SetBorder(int border); /** Sets the minimum width for the bitmap that will be constructed to contain the - actual wizard or page bitmap - if a non-zero bitmap placement flag has been set. If this is not set when using - bitmap placement, the initial - layout may be incorrect. + actual wizard or page bitmap if a non-zero bitmap placement flag has been set. + If this is not set when using bitmap placement, the initial layout may be incorrect. + See also SetBitmapPlacement(). */ void SetMinimumBitmapWidth(int width); /** - This method is obsolete, use - GetPageAreaSizer() instead. - Sets the minimal size to be made available for the wizard pages. The wizard - 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 using - 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 the pages and pass it to SetPageSize(). + Sets the minimal size to be made available for the wizard pages. + The wizard 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 + using 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 + the pages and pass it to SetPageSize(). + + @deprecated + This method is obsolete, use GetPageAreaSizer() instead. */ void SetPageSize(const wxSize& sizePage); }; diff --git a/interface/wx/wrapsizer.h b/interface/wx/wrapsizer.h index 748f784577..f48092e3fd 100644 --- a/interface/wx/wrapsizer.h +++ b/interface/wx/wrapsizer.h @@ -10,9 +10,9 @@ @class wxWrapSizer 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 - the primary direction has been used, a new line is added and items are added - there. + as there is space available in that direction. + Once all available space in the primary direction has been used, a new line + is added and items are added there. So a wrap sizer has a primary orientation for adding items, and adds lines as needed in the secondary direction. @@ -20,28 +20,33 @@ @library{wxcore} @category{winlayout} - @see wxBoxSizer, wxSizer, @ref overview_sizeroverview "Sizer overview" + @see wxBoxSizer, wxSizer, @ref overview_sizer */ class wxWrapSizer : public wxBoxSizer { public: /** - Constructor for a wxWrapSizer. @a orient determines the primary direction of - the sizer (the most common case being @c wxHORIZONTAL). The flags - parameter can be a combination of the values @c - wxEXTEND_LAST_ON_EACH_LINE which will cause the last item on each line - to use any remaining space on that line and @c wxREMOVE_LEADING_SPACES - which removes any spacer elements from the beginning of a row. Both of - these flags are on by default. + Constructor for a wxWrapSizer. + + @a orient determines the primary direction of the sizer (the most common + case being @c wxHORIZONTAL). The flags parameter can be a combination of + the values @c wxEXTEND_LAST_ON_EACH_LINE which will cause the last item + on each line to use any remaining space on that line and @c wxREMOVE_LEADING_SPACES + which removes any spacer elements from the beginning of a row. + + Both of these flags are on by default. */ wxWrapSizer(int orient = wxHORIZONTAL, int flags = wxEXTEND_LAST_ON_EACH_LINE | wxREMOVE_LEADING_SPACES); /** - Not used by an application. 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. + Not used by an application. + + 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 updated). */ diff --git a/interface/wx/wupdlock.h b/interface/wx/wupdlock.h index 802a6969f0..ae209ec814 100644 --- a/interface/wx/wupdlock.h +++ b/interface/wx/wupdlock.h @@ -9,11 +9,11 @@ /** @class wxWindowUpdateLocker - This tiny class prevents redrawing of a wxWindow during its - lifetime by using wxWindow::Freeze and - wxWindow::Thaw methods. It is typically used for creating - automatic objects to temporarily suppress window updates before a batch of - operations is performed: + This tiny class prevents redrawing of a wxWindow during its lifetime by using + wxWindow::Freeze() and wxWindow::Thaw() methods. + + It is typically used for creating automatic objects to temporarily suppress + window updates before a batch of operations is performed: @code void MyFrame::Foo() @@ -27,19 +27,18 @@ } @endcode - Using this class is easier and safer than calling - wxWindow::Freeze and wxWindow::Thaw because you - don't risk to forget calling the latter. + Using this class is easier and safer than calling wxWindow::Freeze() and + wxWindow::Thaw() because you don't risk to forget calling the latter. @library{wxbase} - @category{FIXME} + @category{misc} */ class wxWindowUpdateLocker { public: /** - Creates an object preventing the updates of the specified @e win. The - parameter must be non-@NULL and the window must exist for longer than + Creates an object preventing the updates of the specified @e win. + The parameter must be non-@NULL and the window must exist for longer than wxWindowUpdateLocker object itself. */ wxWindowUpdateLocker(wxWindow* win); diff --git a/interface/wx/xml/xml.h b/interface/wx/xml/xml.h index 71ac36a37b..794fdb8823 100644 --- a/interface/wx/xml/xml.h +++ b/interface/wx/xml/xml.h @@ -1,20 +1,41 @@ ///////////////////////////////////////////////////////////////////////////// // Name: xml/xml.h -// Purpose: interface of wxXmlNode +// Purpose: interface of wxXmlNode, wxXmlAttribute, wxXmlDocument // Author: wxWidgets team // RCS-ID: $Id$ // 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 Represents a node in an XML document. See wxXmlDocument. - Node has a name and may have content and attributes. Most common node types are - @c wxXML_TEXT_NODE (name and attributes are irrelevant) and - @c wxXML_ELEMENT_NODE (e.g. in @c titlehi/title there is an element - with name="title", irrelevant content and one child (@c wxXML_TEXT_NODE + Node has a name and may have content and attributes. + + Most common node types are @c wxXML_TEXT_NODE (name and attributes are irrelevant) + and @c wxXML_ELEMENT_NODE (e.g. in @c \hi\ there is an element + with name="title", irrelevant content and one child @c wxXML_TEXT_NODE with content="hi"). If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to @@ -28,33 +49,76 @@ class wxXmlNode { 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, const wxString& name, const wxString& content = wxEmptyString, wxXmlAttribute* attrs = NULL, 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, const wxString& content = wxEmptyString, 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. */ ~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. */ - void AddAttribute(const wxString& name, const wxString& value); void AddAttribute(wxXmlAttribute* attr); - //@} /** Adds node @a child as the last child of this node. @@ -76,15 +140,18 @@ public: */ 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. If it does not exist, the @a defaultVal is returned. */ - bool GetAttribute(const wxString& attrName, wxString* value) const; - const wxString GetAttribute(const wxString& attrName, - const wxString& defaultVal = wxEmptyString) const; - //@} + wxString GetAttribute(const wxString& attrName, + const wxString& defaultVal = wxEmptyString) const; /** 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. Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type) - the - content is an empty string. See GetNodeContent() for more details. + the content is an empty string. See GetNodeContent() for more details. */ wxString GetContent() const; /** 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 - or the @NULL node (which is the parent of non-linked nodes or the parent of a - wxXmlDocument's root node). + + This function searches only the parents of this node until it finds + @a grandparent or the @NULL node (which is the parent of non-linked + nodes or the parent of a wxXmlDocument's root node). */ 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; /** - Returns the name of this node. Can be an empty string (e.g. for nodes of type - @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE). + Returns the name of this 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; @@ -133,16 +200,26 @@ public: wxXmlNode* GetNext() const; /** - Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c - wxXML_CDATA_SECTION_NODE. - This function is very useful since the XML snippet @c - "tagnametagcontent/tagname" is represented by - expat with the following tag tree: + Returns the content of the first child node of type @c wxXML_TEXT_NODE + or @c wxXML_CDATA_SECTION_NODE. + This function is very useful since the XML snippet @c "tagnametagcontent/tagname" + is represented by expat with the following tag tree: + + @code + wxXML_ENTITY_NODE name="tagname", content="" + |-- wxXML_TEXT_NODE name="", content="tagcontent" + @endcode or eventually: - 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. + @code + 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; @@ -158,7 +235,7 @@ public: 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; @@ -199,34 +276,36 @@ public: /** Returns @true if the content of this node is a string containing only - whitespaces (spaces, - tabs, new lines, etc). 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 - runs under. + whitespaces (spaces, tabs, new lines, etc). + + 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 runs under. */ bool IsWhitespaceOnly() const; /** - Removes the given node from the children list. Returns @true if the node was - found and removed - or @false if the node could not be found. - Note that the caller is reponsible for deleting the removed node in order to - avoid memory leaks. + Removes the given node from the children list. + + Returns @true if the node was found and removed or @false if the node + could not be found. + Note that the caller is reponsible for deleting the removed node in order + to avoid memory leaks. */ bool RemoveChild(wxXmlNode* child); /** 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); /** - Sets as first child the given node. The caller is responsible to delete any - previously present - children node. + Sets as first child the given node. + + The caller is responsible to delete any previously present children node. */ void SetChildren(wxXmlNode* child); @@ -241,16 +320,16 @@ public: void SetName(const wxString& name); /** - Sets as sibling the given node. The caller is responsible to delete any - previously present - sibling node. + Sets as sibling the given node. + + The caller is responsible to delete any previously present sibling node. */ void SetNext(wxXmlNode* next); /** - Sets as parent the given node. The caller is responsible to delete any - previously present - parent node. + Sets as parent the given node. + + The caller is responsible to delete any previously present parent node. */ void SetParent(wxXmlNode* parent); @@ -262,7 +341,7 @@ public: /** 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. - Example: in @c img src="hello.gif" id="3"/, @c "src" is attribute with value + Example: in @c "\", @c "src" is attribute with value @c "hello.gif" and @c "id" is a attribute with value @c "3". @library{wxxml} @@ -283,15 +362,17 @@ public: class wxXmlAttribute { public: - //@{ /** - Creates the attribute with given @a name and @e value. - If @a next is not @NULL, then sets it as sibling of this attribute. + Default constructor. */ 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* next = NULL); - //@} /** The virtual destructor. @@ -379,10 +460,9 @@ public: } @endcode - @note if you want to preserve the original formatting of the loaded file - including whitespaces - and indentation, you need to turn off whitespace-only textnode removal and - automatic indentation: + Note that if you want to preserve the original formatting of the loaded file + including whitespaces and indentation, you need to turn off whitespace-only + textnode removal and automatic indentation: @code wxXmlDocument doc; @@ -393,8 +473,7 @@ public: @endcode Using default parameters, you will get a reformatted document which in general - is different from - the original loaded content: + is different from the original loaded content: @code wxXmlDocument doc; @@ -410,15 +489,27 @@ public: class wxXmlDocument : public wxObject { public: - //@{ + /** + Default constructor. + */ + wxXmlDocument(); + /** Copy constructor. Deep copies all the XML tree of the given document. */ - wxXmlDocument(); - wxXmlDocument(const wxString& filename); - wxXmlDocument(wxInputStream& stream); 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. @@ -426,25 +517,29 @@ public: ~wxXmlDocument(); /** - Detaches the document root node and returns it. The document root node will be - set to @NULL - and thus IsOk() will return @false after calling this function. - Note that the caller is reponsible for deleting the returned node in order to - avoid memory leaks. + Detaches the document root node and returns it. + + The document root node will be set to @NULL and thus IsOk() will + return @false after calling this function. + + Note that the caller is reponsible for deleting the returned node in order + to avoid memory leaks. */ wxXmlNode* DetachRoot(); /** Returns encoding of in-memory representation of the document (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*. */ wxString GetEncoding() const; /** 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; @@ -455,7 +550,8 @@ public: /** 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 \ header of the XML document. If the version attribute was not explicitely given in the header, this function returns an empty string. */ @@ -466,23 +562,46 @@ public: */ 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 - of @c indentstep. + Parses @a filename as an xml document and loads its data. + + 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; - const bool Save(wxOutputStream& stream, int indentstep = 1) const; - //@} + virtual bool Load(const wxString& filename, + 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. @@ -496,9 +615,8 @@ public: /** Sets the root node of this document. Deletes previous root node. - Use DetachRoot() and then - SetRoot() if you want - to replace the root node without deleting the old document tree. + Use DetachRoot() and then SetRoot() if you want to replace the root + node without deleting the old document tree. */ void SetRoot(wxXmlNode* node); @@ -510,6 +628,6 @@ public: /** Deep copies the given document. */ - wxXmlDocument& operator operator=(const wxXmlDocument& doc); + wxXmlDocument& operator=(const wxXmlDocument& doc); }; diff --git a/interface/wx/xrc/xmlres.h b/interface/wx/xrc/xmlres.h index b78f925e71..49a3409cae 100644 --- a/interface/wx/xrc/xmlres.h +++ b/interface/wx/xrc/xmlres.h @@ -25,7 +25,7 @@ public: //@{ /** Constructor. - + @param flags wxXRC_USE_LOCALE: translatable strings will be translated via _(). 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 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} @category{xrc} @@ -291,9 +291,9 @@ public: /** Creates an object (menu, dialog, control, ...) from an XML node. - Should check for validity. @a parent is a higher-level object (usually window, - dialog or panel) - that is often necessary to create the resource. + Should check for validity. @a parent is a higher-level object + (usually window, dialog or panel) that is often necessary to create the resource. + 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. */ @@ -319,7 +319,7 @@ public: 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); @@ -402,10 +402,10 @@ public: /** Gets text from param and does some conversions: - 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 - translation because of XML syntax) - calls wxGetTranslations (unless disabled in wxXmlResource) + - 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 + translation because of XML syntax) + - calls wxGetTranslations (unless disabled in wxXmlResource) */ wxString GetText(const wxString& param); diff --git a/interface/wx/zipstrm.h b/interface/wx/zipstrm.h index 13415333c1..5e6561f2e5 100644 --- a/interface/wx/zipstrm.h +++ b/interface/wx/zipstrm.h @@ -6,33 +6,107 @@ // 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 - If you need to know when a wxZipInputStream - updates a wxZipEntry, + If you need to know when a wxZipInputStream updates a wxZipEntry, 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 - objects, using wxZipEntry::SetNotifier. + objects, using wxZipEntry::SetNotifier(). Setting a notifier is not usually necessary. It is used to handle certain cases when modifying an zip in a pipeline (i.e. between non-seekable streams). - See '@ref overview_wxarcnoseek "Archives on non-seekable streams"'. + See @ref overview_archive_noseek. @library{wxbase} - @category{FIXME} + @category{archive} - @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipEntry, - wxZipInputStream, wxZipOutputStream + @see @ref overview_archive_noseek, wxZipEntry, wxZipInputStream, wxZipOutputStream */ class wxZipNotifier { public: /** - Override this to receive notifications when - an wxZipEntry object changes. + Override this to receive notifications when an wxZipEntry object changes. */ void OnEntryUpdated(wxZipEntry& entry); }; @@ -44,22 +118,61 @@ public: Holds the meta-data for an entry in a zip. - @library{wxbase} - @category{FIXME} + @section zipentry_avail Field availability - @see @ref overview_wxarc "Archive formats such as zip", wxZipInputStream, - wxZipOutputStream, wxZipNotifier + When reading a zip from a stream that is seekable, wxZipEntry::GetNextEntry() + 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 { public: - //@{ + wxZipEntry(const wxString& name = wxEmptyString); + /** Copy constructor. */ - wxZipEntry(const wxString& name = wxEmptyString); wxZipEntry(const wxZipEntry& 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(); - const void SetComment(const wxString& comment); + wxString GetComment() const; + void SetComment(const wxString& comment); //@} //@{ /** The low 8 bits are always the DOS/Windows file attributes for this entry. - The values of these attributes are given in the - enumeration @c wxZipAttributes. + The values of these attributes are given in the enumeration ::wxZipAttributes. + The remaining bits can store platform specific permission bits or - attributes, and their meaning depends on the value - of @ref systemmadeby() SetSystemMadeBy. - If IsMadeByUnix() is @true then the - high 16 bits are unix mode bits. + attributes, and their meaning depends on the value of SetSystemMadeBy(). + If IsMadeByUnix() is @true then the high 16 bits are unix mode bits. + The following other accessors access these bits: - @ref wxArchiveEntry::isreadonly IsReadOnly/SetIsReadOnly - - @ref wxArchiveEntry::isdir IsDir/SetIsDir - - @ref mode() Get/SetMode + - IsReadOnly() / SetIsReadOnly() + - IsDir() / SetIsDir() + - GetMode() / SetMode() */ - wxUint32 GetExternalAttributes(); - const void SetExternalAttributes(wxUint32 attr); + wxUint32 GetExternalAttributes() const; + void SetExternalAttributes(wxUint32 attr); //@} //@{ /** The extra field from the entry's central directory record. + The extra field is used to store platform or application specific data. See Pkware's document 'appnote.txt' for information on its format. */ - const char* GetExtra(); - const size_t GetExtraLen(); - const void SetExtra(const char* extra, size_t len); + char* GetExtra() const; + size_t GetExtraLen() const; + void SetExtra(const char* extra, size_t len); //@} //@{ /** The extra field from the entry's local record. + The extra field is used to store platform or application specific data. See Pkware's document 'appnote.txt' for information on its format. */ - const char* GetLocalExtra(); - const size_t GetLocalExtraLen(); - const void SetLocalExtra(const char* extra, size_t len); + char* GetLocalExtra() const; + size_t GetLocalExtraLen() const; + void SetLocalExtra(const char* extra, size_t len); //@} //@{ /** - The compression method. The enumeration @c wxZipMethod lists the - possible values. - The default constructor sets this to wxZIP_METHOD_DEFAULT, - which allows wxZipOutputStream to - choose the method when writing the entry. + The compression method. + The enumeration ::wxZipMethod lists the possible values. + + The default constructor sets this to @c wxZIP_METHOD_DEFAULT, + which allows wxZipOutputStream to choose the method when writing the entry. */ - int GetMethod(); - const void SetMethod(int method); + int GetMethod() const; + void SetMethod(int method); //@} //@{ /** - Sets the DOS attributes - in @ref externalattributes() GetExternalAttributes - to be consistent with the @c mode given. - If IsMadeByUnix() is @true then also - stores @c mode in GetExternalAttributes(). - Note that the default constructor - sets @ref systemmadeby() GetSystemMadeBy to - wxZIP_SYSTEM_MSDOS by default. So to be able to store unix + If IsMadeByUnix() is true then returns the unix permission bits stored + in GetExternalAttributes(). Otherwise synthesises them from the DOS attributes. + */ + int GetMode() const; + + /** + Sets the DOS attributes in GetExternalAttributes() to be consistent with + 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). */ - int GetMode(); - const void SetMode(int mode); + void SetMode(int mode); //@} //@{ /** - The originating file-system. The default constructor sets this to - wxZIP_SYSTEM_MSDOS. Set it to wxZIP_SYSTEM_UNIX in order to be - able to store unix permissions using @ref mode() SetMode. + The originating file-system. + + 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(); - const void SetSystemMadeBy(int system); + int GetSystemMadeBy() const; + void SetSystemMadeBy(int system); //@} /** @@ -177,17 +294,23 @@ public: to is set to indicate whether the name looks like a directory name (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(); - const wxString GetInternalName(const wxString& name, - wxPathFormat format = wxPATH_NATIVE, - bool* pIsDir = NULL); + wxString GetInternalName(const wxString& name, + wxPathFormat format = wxPATH_NATIVE, + 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 - is a flavour of unix. + Returns @true if GetSystemMadeBy() is a flavour of unix. */ bool IsMadeByUnix() const; @@ -195,22 +318,21 @@ public: /** Indicates that this entry's data is text in an 8-bit encoding. */ - bool IsText(); - const void SetIsText(bool isText = true); + bool IsText() const; + void SetIsText(bool isText = true); //@} //@{ /** - Sets the notifier() for this entry. - Whenever the wxZipInputStream updates - this entry, it will then invoke the associated - notifier's wxZipNotifier::OnEntryUpdated - method. + Sets the notifier (see wxZipNotifier) for this entry. + Whenever the wxZipInputStream updates this entry, it will then invoke + the associated notifier's wxZipNotifier::OnEntryUpdated() method. + Setting a notifier is not usually necessary. It is used to handle certain cases when modifying an zip in a pipeline (i.e. between non-seekable streams). - @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipNotifier + @see @ref overview_archive_noseek, wxZipNotifier */ void SetNotifier(wxZipNotifier& notifier); void UnsetNotifier(); @@ -219,11 +341,15 @@ public: /** Assignment operator. */ - wxZipEntry& operator operator=(const wxZipEntry& entry); + wxZipEntry& operator=(const wxZipEntry& entry); }; +--- + + + /** @class wxZipInputStream