From 0c1fe6e947642e437ec1f05fe0f7af7c5559a4ba Mon Sep 17 00:00:00 2001 From: Bryan Petty Date: Tue, 22 Apr 2008 01:38:12 +0000 Subject: [PATCH] Finished initial reviews of the rest of the [d*] interface headers. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53300 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/mainpages/samples.h | 92 +-- interface/docmdi.h | 62 +- interface/docview.h | 1004 +++++++++++++++--------------- interface/dragimag.h | 270 +++++--- interface/dynarray.h | 970 +++++++++++++++++------------ interface/dynlib.h | 332 +++------- 6 files changed, 1395 insertions(+), 1335 deletions(-) diff --git a/docs/doxygen/mainpages/samples.h b/docs/doxygen/mainpages/samples.h index ae87007e7a..15ac048227 100644 --- a/docs/doxygen/mainpages/samples.h +++ b/docs/doxygen/mainpages/samples.h @@ -54,6 +54,8 @@ name. Most classes contained in wxWidgets occur in at least one of the samples. @li @ref page_samples_dialogs @li @ref page_samples_dialup @li @ref page_samples_dnd +@li @ref page_samples_docview +@li @ref page_samples_dragimag @li @ref page_samples_event @li @ref page_samples_except @@ -89,16 +91,13 @@ name. Most classes contained in wxWidgets occur in at least one of the samples. TODO: write descriptions for the samples: -aui caret collpane combo console dataview display -docview docvwmdi -dragimag drawing editlbox erase @@ -144,20 +143,20 @@ xrc
-@section page_samples_access Accessibility sample +@section page_samples_access Accessibility Sample The @c access sample shows how you can use the wxAccessible classes in a simple GUI program. -@section page_samples_animate Animate sample +@section page_samples_animate Animate Sample The @c animate sample shows how you can use wxAnimationCtrl control and shows concept of a platform-dependent animation encapsulated in wxAnimation. -@section page_samples_artprovider Art provider sample +@section page_samples_artprovider Art Provider Sample The @c artprov sample shows how you can customize the look of standard wxWidgets dialogs by replacing default bitmaps/icons with your own versions. @@ -165,14 +164,19 @@ It also shows how you can use wxArtProvider to get stock bitmaps for use in your application. -@section page_samples_calendar Calendar sample +@section page_samples_aui wxAUI Sample + +@todo Write sample description. + + +@section page_samples_calendar Calendar Sample This font shows the calendar control in action. It shows how to configure the control (see the different options in the calendar menu) and also how to process the notifications from it. -@section page_samples_config Config sample +@section page_samples_config Config Sample This sample demonstrates the wxConfig classes in a platform independent way, i.e. it uses text based files to store a given configuration under @@ -181,7 +185,7 @@ Unix and uses the Registry under Windows. See @ref overview_config for the descriptions of all features of this class. -@section page_samples_controls Controls sample +@section page_samples_controls Controls Sample The controls sample is the main test program for most simple controls used in wxWidgets. The sample tests their basic functionality, events, placement, @@ -211,7 +215,7 @@ The various controls tested are listed here: @li wxSlider -@section page_samples_debugrpt DebugRpt sample +@section page_samples_debugrpt DebugRpt Sample This sample shows how to use wxDebugReport class to generate a debug report in case of a program crash or otherwise. On start up, @@ -226,13 +230,13 @@ a Web server accepting form uploads, otherwise wxDebugReportUpload will report an error. -@section page_samples_dialogs Dialogs sample +@section page_samples_dialogs Dialogs Sample This sample shows how to use the common dialogs available from wxWidgets. These dialogs are described in detail in the @ref overview_cmndlg. -@section page_samples_dialup Dialup sample +@section page_samples_dialup Dialup Sample This sample shows the wxDialUpManager class. In the status bar, it displays the information gathered through its @@ -246,7 +250,7 @@ modem attached and (this only makes sense for Windows) list the available connections. -@section page_samples_dnd DnD sample +@section page_samples_dnd DnD Sample This sample shows both clipboard and drag and drop in action. It is quite non trivial and may be safely used as a basis for implementing the clipboard and @@ -285,7 +289,17 @@ Take a look at DnDShapeDataObject class to see how you may use wxDataObject to achieve this. -@section page_samples_event Event sample +@section page_samples_docview Document/View Sample + +@todo Write sample description. + + +@section page_samples_dragimag wxDragImage Sample + +@todo Write sample description. + + +@section page_samples_event Event Sample The event sample demonstrates various features of the wxWidgets events. It shows using dynamic events and connecting/disconnecting the event handlers @@ -294,7 +308,7 @@ PushEventHandler() and PopEventHandler(). -@section page_samples_except Except(ions) sample +@section page_samples_except Except(ions) Sample This very simple sample shows how to use C++ exceptions in wxWidgets programs, i.e. where to catch the exception which may be thrown by the program code. It @@ -306,7 +320,7 @@ and compile your code with C++ exceptions support to be able to build this sample. -@section page_samples_exec Exec sample +@section page_samples_exec Exec Sample The exec sample demonstrates the wxExecute and wxShell functions. Both of them are used to execute the @@ -319,7 +333,7 @@ wxProcess::Kill and test for their existence with wxProcess::Exists. -@section page_samples_font Font sample +@section page_samples_font Font Sample The font sample demonstrates wxFont, wxFontEnumerator and @@ -328,12 +342,12 @@ available (to wxWidgets) on the computer and shows all characters of the chosen font as well. -@section page_samples_grid Grid sample +@section page_samples_grid Grid Sample -@todo WRITE THIS DESCRIPTION. +@todo Write sample description. -@section page_samples_html HTML samples +@section page_samples_html HTML Sample Eight HTML samples (you can find them in directory @c samples/html) cover all features of the HTML sub-library. @@ -365,7 +379,7 @@ while @e Helpview is a simple tool that only pops up the help window and displays help books given at command line. -@section page_samples_image Image sample +@section page_samples_image Image Sample The image sample demonstrates use of the wxImage class and shows how to download images in a variety of formats, currently PNG, GIF, @@ -387,7 +401,7 @@ This sample also contains the code for testing the image rotation and resizing and using raw bitmap access, see the corresponding menu commands. -@section page_samples_internat Internat(ionalization) sample +@section page_samples_internat Internat(ionalization) Sample The not very clearly named internat sample demonstrates the wxWidgets internationalization (i18n for short from now on) features. To be more @@ -399,7 +413,7 @@ More information about this sample can be found in the @c readme.txt file in its directory. Please also see the @ref overview_i18n. -@section page_samples_layout Layout sample +@section page_samples_layout Layout Sample The layout sample demonstrates the two different layout systems offered by wxWidgets. When starting the program, you will see a frame with some @@ -416,7 +430,7 @@ showing how to use sizers in connection with a wxNotebook class. See also wxSizer. -@section page_samples_listctrl Listctrl sample +@section page_samples_listctrl Listctrl Sample This sample shows the wxListCtrl control. Different modes supported by the control (list, icons, small icons, report) may be chosen from @@ -426,7 +440,7 @@ The sample also provides some timings for adding/deleting/sorting a lot of (several thousands) items into the control. -@section page_samples_mediaplayer Mediaplayer sample +@section page_samples_mediaplayer Mediaplayer Sample This sample demonstrates how to use all the features of wxMediaCtrl and play various types of sound, video, @@ -435,7 +449,7 @@ and other files. It replaces the old dynamic sample. -@section page_samples_minimal Minimal sample +@section page_samples_minimal Minimal Sample The minimal sample is what most people will know under the term Hello World, i.e. a minimal program that doesn't demonstrate anything apart from what is @@ -443,7 +457,7 @@ needed to write a program that will display a "hello" dialog. This is usually a good starting point for learning how to use wxWidgets. -@section page_samples_notebook Notebook sample +@section page_samples_notebook Notebook Sample This samples shows wxBookCtrl family of controls. Although initially it was written to demonstrate wxNotebook @@ -453,14 +467,14 @@ Test each of the controls, their orientation, images and pages using commands through menu. -@section page_samples_render Render sample +@section page_samples_render Render Sample This sample shows how to replace the default wxWidgets renderer and also how to write a shared library (DLL) implementing a renderer and load and unload it during the run-time. -@section page_samples_scrollsub Scroll subwindow sample +@section page_samples_scrollsub Scroll Subwindow Sample This sample demonstrates use of the ::wxScrolledWindow class including placing subwindows into it and drawing simple graphics. It uses the @@ -473,7 +487,7 @@ the aim to prevent unnecessary drawing in the window and thus reducing or removi flicker on screen. -@section page_samples_sockets Sockets sample +@section page_samples_sockets Sockets Sample The sockets sample demonstrates how to use the communication facilities provided by wxSocket. There are two different @@ -524,13 +538,13 @@ The sockets sample is work in progress. Some things to do: @li New samples which actually do something useful (suggestions accepted). -@section page_samples_sound Sound sample +@section page_samples_sound Sound Sample The @c sound sample shows how to use wxSound for simple audio output (e.g. notifications). -@section page_samples_statbar Statbar sample +@section page_samples_statbar Statbar Sample This sample shows how to create and use wxStatusBar. Although most of the samples have a statusbar, they usually only create a default one and only @@ -541,7 +555,7 @@ of fields) and how to use it to show icons/bitmaps and/or put arbitrary controls into it. -@section page_samples_taborder Tab order sample +@section page_samples_taborder Tab Order Sample This sample allows to test keyboard navigation (mostly done using the @c TAB key, hence the sample name) between different controls. @@ -552,7 +566,7 @@ wxWindow::Navigate() for moving focus along this chain. -@section page_samples_text Text sample +@section page_samples_text Text Sample This sample demonstrates four features: firstly the use and many variants of the wxTextCtrl class (single line, multi line, read only, @@ -574,7 +588,7 @@ Last not least: some of the text controls have tooltips and the sample also show how tooltips can be centrally disabled and their latency controlled. -@section page_samples_thread Thread sample +@section page_samples_thread Thread Sample This sample demonstrates use of threads in connection with GUI programs. There are two fundamentally different ways to use threads in GUI programs and @@ -595,7 +609,7 @@ used and tested in the sample as well. See also @ref overview_thread and wxThread. -@section page_samples_toolbar Toolbar sample +@section page_samples_toolbar Toolbar Sample The toolbar sample shows the wxToolBar class in action. @@ -620,7 +634,7 @@ group, i.e. checking any of them automatically unchecks the previously checked one. -@section page_samples_treectrl Treectrl sample +@section page_samples_treectrl Treectrl Sample This sample demonstrates using the wxTreeCtrl class. Here you may see how to process various notification messages sent by this control @@ -632,7 +646,7 @@ sorting (in default alphabetical order as well as in custom one) is demonstrated here as well - try the corresponding menu entries. -@section page_samples_widgets Widgets sample +@section page_samples_widgets Widgets Sample The widgets sample is the main presentation program for most simple and advanced native controls and complex generic widgets provided by wxWidgets. @@ -642,7 +656,7 @@ the controls programmatically, such as adding an item to a list box etc. All widgets are categorized for easy browsing. -@section page_samples_wizard Wizard sample +@section page_samples_wizard Wizard Sample This sample shows the so-called wizard dialog (implemented using wxWizard and related classes). It shows almost all diff --git a/interface/docmdi.h b/interface/docmdi.h index fd31790829..758fba89b6 100644 --- a/interface/docmdi.h +++ b/interface/docmdi.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: docmdi.h -// Purpose: interface of wxDocMDIParentFrame +// Purpose: interface of wxDocMDIParentFrame and wxDocMDIChildFrame // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -11,18 +11,16 @@ @wxheader{docmdi.h} The wxDocMDIParentFrame class provides a default top-level frame for - applications using the document/view framework. This class can only be used for - MDI parent frames. + applications using the document/view framework. This class can only be used + for MDI parent frames. - It cooperates with the wxView, wxDocument, - wxDocManager and wxDocTemplates() classes. - - See the example application in @c samples/docview. + It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate + classes. @library{wxcore} - @category{FIXME} + @category{docview} - @see @ref overview_docviewoverview, wxMDIParentFrame + @see @ref overview_docview, @ref page_samples_docview, wxMDIParentFrame */ class wxDocMDIParentFrame : public wxMDIParentFrame { @@ -59,8 +57,21 @@ public: /** Deletes all views and documents. If no user input cancelled the operation, the frame will be destroyed and the application will exit. - Since understanding how document/view clean-up takes place can be difficult, - the implementation of this function is shown below. + + Since understanding how document/view clean-up takes place can be + difficult, the implementation of this function is shown below: + + @code + void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event) + { + if (m_docManager->Clear(!event.CanVeto())) + { + this->Destroy(); + } + else + event.Veto(); + } + @endcode */ void OnCloseWindow(wxCloseEvent& event); }; @@ -71,19 +82,18 @@ public: @class wxDocMDIChildFrame @wxheader{docmdi.h} - The wxDocMDIChildFrame class provides a default frame for displaying documents - on separate windows. This class can only be used for MDI child frames. + The wxDocMDIChildFrame class provides a default frame for displaying + documents on separate windows. This class can only be used for MDI child + frames. The class is part of the document/view framework supported by wxWidgets, - and cooperates with the wxView, wxDocument, - wxDocManager and wxDocTemplate classes. - - See the example application in @c samples/docview. + and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate + classes. @library{wxcore} - @category{FIXME} + @category{docview} - @see @ref overview_docviewoverview, wxMDIChildFrame + @see @ref overview_docview, @ref page_samples_docview, wxMDIChildFrame */ class wxDocMDIChildFrame : public wxMDIChildFrame { @@ -92,8 +102,7 @@ public: Constructor. */ wxDocMDIChildFrame(wxDocument* doc, wxView* view, - wxFrame* parent, - wxWindowID id, + wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -136,16 +145,5 @@ public: Sets the view for this frame. */ void SetView(wxView* view); - - /** - wxDocument* m_childDocument - The document associated with the frame. - */ - - - /** - wxView* m_childView - The view associated with the frame. - */ }; diff --git a/interface/docview.h b/interface/docview.h index 0cbe2a7e46..ccc13d4189 100644 --- a/interface/docview.h +++ b/interface/docview.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: docview.h -// Purpose: interface of wxDocTemplate +// Purpose: interface of various doc/view framework classes // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -14,69 +14,57 @@ document class and a view class. @library{wxcore} - @category{dvf} + @category{docview} - @see @ref overview_wxdoctemplateoverview "wxDocTemplate overview", wxDocument, - wxView + @see @ref overview_docview_wxdoctemplate, wxDocument, wxView */ class wxDocTemplate : public wxObject { public: /** - Constructor. Create instances dynamically near the start of your application - after creating - a wxDocManager instance, and before doing any document or view operations. - @a manager is the document manager object which manages this template. - @a descr is a short description of what the template is for. This string will - be displayed in the - file filter list of Windows file selectors. - @a filter is an appropriate file filter such as @c *.txt. - @a dir is the default directory to use for file selectors. - @a ext is the default file extension (such as txt). - @a docTypeName is a name that should be unique for a given type of document, - used for - gathering a list of views relevant to a particular document. - @a viewTypeName is a name that should be unique for a given view. - @a docClassInfo is a pointer to the run-time document class information as - returned - by the CLASSINFO macro, e.g. CLASSINFO(MyDocumentClass). If this is not - supplied, - you will need to derive a new wxDocTemplate class and override the - CreateDocument - member to return a new document instance on demand. - @a viewClassInfo is a pointer to the run-time view class information as returned - by the CLASSINFO macro, e.g. CLASSINFO(MyViewClass). If this is not supplied, - you will need to derive a new wxDocTemplate class and override the CreateView - member to return a new view instance on demand. - @a flags is a bit list of the following: - wxTEMPLATE_VISIBLE The template may be displayed to the user in dialogs. - wxTEMPLATE_INVISIBLE The template may not be displayed to the user in dialogs. - wxDEFAULT_TEMPLATE_FLAGS Defined as wxTEMPLATE_VISIBLE. - - - @b Wx::DocTemplate-new( docmgr, descr, filter, dir, - ext, docTypeName, viewTypeName, docClassInfo, viewClassInfo, flags - ) - - will construct document and view objects from the class information - - @b Wx::DocTemplate-new( docmgr, descr, filter, dir, - ext, docTypeName, viewTypeName, docClassName, viewClassName, flags - ) - - will construct document and view objects from perl packages - - @b Wx::DocTemplate-new( docmgr, descr, filter, dir, - ext, docTypeName, viewTypeName ) - - @c Wx::DocTemplate::CreateDocument() and - @c Wx::DocTemplate::CreateView() must be overridden + Constructor. Create instances dynamically near the start of your + application after creating a wxDocManager instance, and before doing + any document or view operations. + + @param manager + The document manager object which manages this template. + @param descr + A short description of what the template is for. This string will + be displayed in the file filter list of Windows file selectors. + @param filter + An appropriate file filter such as "*.txt". + @param dir + The default directory to use for file selectors. + @param ext + The default file extension (such as "txt"). + @param docTypeName + A name that should be unique for a given type of document, used for + gathering a list of views relevant to a particular document. + @param viewTypeName + A name that should be unique for a given view. + @param docClassInfo + A pointer to the run-time document class information as returned by + the CLASSINFO() macro, e.g. CLASSINFO(MyDocumentClass). If this is + not supplied, you will need to derive a new wxDocTemplate class and + override the CreateDocument() member to return a new document + instance on demand. + @param viewClassInfo + A pointer to the run-time view class information as returned by the + CLASSINFO() macro, e.g. CLASSINFO(MyViewClass). If this is not + supplied, you will need to derive a new wxDocTemplate class and + override the CreateView() member to return a new view instance on + demand. + @param flags + A bit list of the following: + - wxTEMPLATE_VISIBLE - The template may be displayed to the + user in dialogs. + - wxTEMPLATE_INVISIBLE - The template may not be displayed to + the user in dialogs. + - wxDEFAULT_TEMPLATE_FLAGS - Defined as wxTEMPLATE_VISIBLE. */ wxDocTemplate(wxDocManager* manager, const wxString& descr, - const wxString& filter, - const wxString& dir, - const wxString& ext, - const wxString& docTypeName, + const wxString& filter, const wxString& dir, + const wxString& ext, const wxString& docTypeName, const wxString& viewTypeName, wxClassInfo* docClassInfo = NULL, wxClassInfo* viewClassInfo = NULL, @@ -88,54 +76,56 @@ public: ~wxDocTemplate(); /** - Creates a new instance of the associated document class. If you have not - supplied - a wxClassInfo parameter to the template constructor, you will need to override - this - function to return an appropriate document instance. - This function calls InitDocument() which in turns - calls wxDocument::OnCreate. + Creates a new instance of the associated document class. If you have + not supplied a wxClassInfo parameter to the template constructor, you + will need to override this function to return an appropriate document + instance. + + This function calls InitDocument() which in turns calls + wxDocument::OnCreate(). */ wxDocument* CreateDocument(const wxString& path, long flags = 0); /** - Creates a new instance of the associated view class. If you have not supplied - a wxClassInfo parameter to the template constructor, you will need to override - this - function to return an appropriate view instance. + Creates a new instance of the associated view class. If you have not + supplied a wxClassInfo parameter to the template constructor, you will + need to override this function to return an appropriate view instance. */ wxView* CreateView(wxDocument* doc, long flags = 0); /** - Returns the default file extension for the document data, as passed to the - document template constructor. + Returns the default file extension for the document data, as passed to + the document template constructor. */ wxString GetDefaultExtension(); /** - Returns the text description of this template, as passed to the document - template constructor. + Returns the text description of this template, as passed to the + document template constructor. */ wxString GetDescription(); /** - Returns the default directory, as passed to the document template constructor. + Returns the default directory, as passed to the document template + constructor. */ wxString GetDirectory(); /** - Returns a pointer to the document manager instance for which this template was - created. + Returns a pointer to the document manager instance for which this + template was created. */ wxDocManager* GetDocumentManager(); /** - Returns the document type name, as passed to the document template constructor. + Returns the document type name, as passed to the document template + constructor. */ wxString GetDocumentName(); /** - Returns the file filter, as passed to the document template constructor. + Returns the file filter, as passed to the document template + constructor. */ wxString GetFileFilter(); @@ -145,20 +135,20 @@ public: long GetFlags(); /** - Returns the view type name, as passed to the document template constructor. + Returns the view type name, as passed to the document template + constructor. */ wxString GetViewName(); /** - Initialises the document, calling wxDocument::OnCreate. This is called from - CreateDocument(). + Initialises the document, calling wxDocument::OnCreate(). This is + called from CreateDocument(). */ - bool InitDocument(wxDocument* doc, const wxString& path, - long flags = 0); + bool InitDocument(wxDocument* doc, const wxString& path, long flags = 0); /** - Returns @true if the document template can be shown in user dialogs, @false - otherwise. + Returns @true if the document template can be shown in user dialogs, + @false otherwise. */ bool IsVisible(); @@ -178,9 +168,8 @@ public: void SetDirectory(const wxString& dir); /** - Sets the pointer to the document manager instance for which this template was - created. - Should not be called by the application. + Sets the pointer to the document manager instance for which this + template was created. Should not be called by the application. */ void SetDocumentManager(wxDocManager* manager); @@ -190,71 +179,62 @@ public: void SetFileFilter(const wxString& filter); /** - Sets the internal document template flags (see the constructor description for - more details). + Sets the internal document template flags (see the constructor + description for more details). */ void SetFlags(long flags); /** - wxString m_defaultExt The default extension for files of this type. */ - + wxString m_defaultExt; /** - wxString m_description A short description of this template. */ - + wxString m_description; /** - wxString m_directory The default directory for files of this type. */ - + wxString m_directory; /** - wxClassInfo* m_docClassInfo - Run-time class information that allows document instances to be constructed - dynamically. + Run-time class information that allows document instances to be + constructed dynamically. */ - + wxClassInfo* m_docClassInfo; /** - wxString m_docTypeName The named type of the document associated with this template. */ - + wxString m_docTypeName; /** - wxDocTemplate* m_documentManager A pointer to the document manager for which this template was created. */ - + wxDocTemplate* m_documentManager; /** - wxString m_fileFilter - The file filter (such as @c *.txt) to be used in file selector dialogs. + The file filter (such as "*.txt") to be used in file selector dialogs. */ - + wxString m_fileFilter; /** - long m_flags The flags passed to the constructor. */ - + long m_flags; /** - wxClassInfo* m_viewClassInfo Run-time class information that allows view instances to be constructed dynamically. */ - + wxClassInfo* m_viewClassInfo; /** - wxString m_viewTypeName The named type of the view associated with this template. */ + wxString m_viewTypeName; }; @@ -264,30 +244,29 @@ public: @wxheader{docview.h} The wxDocManager class is part of the document/view framework supported by - wxWidgets, - and cooperates with the wxView, wxDocument - and wxDocTemplate classes. + wxWidgets, and cooperates with the wxView, wxDocument and wxDocTemplate + classes. @library{wxcore} - @category{dvf} + @category{docview} - @see @ref overview_wxdocmanageroverview "wxDocManager overview", wxDocument, - wxView, wxDocTemplate, wxFileHistory + @see @ref overview_docview_wxdocmanager, wxDocument, wxView, wxDocTemplate, + wxFileHistory */ class wxDocManager : public wxEvtHandler { public: /** - Constructor. Create a document manager instance dynamically near the start of - your application - before doing any document or view operations. + Constructor. Create a document manager instance dynamically near the + start of your application before doing any document or view operations. + @a flags is currently unused. - If @a initialize is @true, the Initialize() function will be called - to create a default history list object. If you derive from wxDocManager, you - may wish to call the - base constructor with @false, and then call Initialize in your own constructor, - to allow - your own Initialize or OnCreateFileHistory functions to be called. + + If @a initialize is @true, the Initialize() function will be called to + create a default history list object. If you derive from wxDocManager, + you may wish to call the base constructor with @false, and then call + Initialize() in your own constructor, to allow your own Initialize() or + OnCreateFileHistory functions to be called. */ wxDocManager(long flags = wxDEFAULT_DOCMAN_FLAGS, bool initialize = true); @@ -308,8 +287,8 @@ public: void AddDocument(wxDocument* doc); /** - Adds a file to the file history list, if we have a pointer to an appropriate - file menu. + Adds a file to the file history list, if we have a pointer to an + appropriate file menu. */ void AddFileToHistory(const wxString& filename); @@ -324,31 +303,30 @@ public: bool CloseDocuments(bool force = true); /** - Creates a new document in a manner determined by the @a flags parameter, which - can be: - wxDOC_NEW Creates a fresh document. - wxDOC_SILENT Silently loads the given document file. - If wxDOC_NEW is present, a new document will be created and returned, possibly - after - asking the user for a template to use if there is more than one document - template. - If wxDOC_SILENT is present, a new document will be created and the given file - loaded - into it. If neither of these flags is present, the user will be presented with - a file selector for the file to load, and the template to use will be - determined by the - extension (Windows) or by popping up a template choice list (other platforms). - If the maximum number of documents has been reached, this function - will delete the oldest currently loaded document before creating a new one. + Creates a new document in a manner determined by the @a flags + parameter, which can be: + + - wxDOC_NEW - Creates a fresh document. + - wxDOC_SILENT - Silently loads the given document file. + + If wxDOC_NEW is present, a new document will be created and returned, + possibly after asking the user for a template to use if there is more + than one document template. If wxDOC_SILENT is present, a new document + will be created and the given file loaded into it. If neither of these + flags is present, the user will be presented with a file selector for + the file to load, and the template to use will be determined by the + extension (Windows) or by popping up a template choice list (other + platforms). + + If the maximum number of documents has been reached, this function will + delete the oldest currently loaded document before creating a new one. */ wxDocument* CreateDocument(const wxString& path, long flags); /** - Creates a new view for the given document. If more than one view is allowed for - the - document (by virtue of multiple templates mentioning the same document type), a - choice - of view is presented to the user. + Creates a new view for the given document. If more than one view is + allowed for the document (by virtue of multiple templates mentioning + the same document type), a choice of view is presented to the user. */ wxView* CreateView(wxDocument* doc, long flags); @@ -357,24 +335,26 @@ public: */ void DisassociateTemplate(wxDocTemplate* temp); - //@{ /** - Appends the files in the history list, to the given menu only. + Appends the files in the history list to all menus managed by the file + history object. */ void FileHistoryAddFilesToMenu(); + /** + Appends the files in the history list to the given @a menu only. + */ void FileHistoryAddFilesToMenu(wxMenu* menu); - //@} /** Loads the file history from a config object. - @see wxConfig() + @see wxConfigBase */ void FileHistoryLoad(wxConfigBase& config); /** - Removes the given menu from the list of menus managed by the file history - object. + Removes the given menu from the list of menus managed by the file + history object. */ void FileHistoryRemoveMenu(wxMenu* menu); @@ -382,27 +362,30 @@ public: Saves the file history into a config object. This must be called explicitly by the application. - @see wxConfig() + @see wxConfigBase */ void FileHistorySave(wxConfigBase& resourceFile); /** - Use this menu for appending recently-visited document filenames, for convenient - access. Calling this function with a valid menu pointer enables the history - list functionality. - Note that you can add multiple menus using this function, to be managed by the - file history object. + Use this menu for appending recently-visited document filenames, for + convenient access. Calling this function with a valid menu pointer + enables the history list functionality. + + @note You can add multiple menus using this function, to be managed by + the file history object. */ void FileHistoryUseMenu(wxMenu* menu); /** - Given a path, try to find template that matches the extension. This is only - an approximate method of finding a template for creating a document. + Given a path, try to find template that matches the extension. This is + only an approximate method of finding a template for creating a + document. */ wxDocTemplate* FindTemplateForPath(const wxString& path); /** - Returns the document associated with the currently active view (if any). + Returns the document associated with the currently active view (if + any). */ wxDocument* GetCurrentDocument(); @@ -427,8 +410,8 @@ public: size_t GetHistoryFilesCount(); /** - Returns the directory last selected by the user when opening a file. Initially - empty. + Returns the directory last selected by the user when opening a file. + Initially empty. */ wxString GetLastDirectory() const; @@ -443,32 +426,34 @@ public: wxList GetTemplates(); /** - Initializes data; currently just calls OnCreateFileHistory. Some data cannot - always be initialized in the constructor because the programmer must be given - the opportunity to override functionality. If OnCreateFileHistory was called - from the constructor, an overridden virtual OnCreateFileHistory would not be - called due to C++'s 'interesting' constructor semantics. In fact Initialize - @e is called from the wxDocManager constructor, but this can be - vetoed by passing @false to the second argument, allowing the derived class's - constructor to call Initialize, possibly calling a different OnCreateFileHistory - from the default. - The bottom line: if you're not deriving from Initialize, forget it and - construct wxDocManager with no arguments. + Initializes data; currently just calls OnCreateFileHistory(). + + Some data cannot always be initialized in the constructor because the + programmer must be given the opportunity to override functionality. If + OnCreateFileHistory() was called from the constructor, an overridden + virtual OnCreateFileHistory() would not be called due to C++'s + 'interesting' constructor semantics. In fact Initialize() @e is called + from the wxDocManager constructor, but this can be vetoed by passing + @false to the second argument, allowing the derived class's constructor + to call Initialize(), possibly calling a different + OnCreateFileHistory() from the default. + + The bottom line: if you're not deriving from Initialize(), forget it + and construct wxDocManager with no arguments. */ bool Initialize(); /** - Return a string containing a suitable default name for a new document. By - default this is implemented by appending an integer counter to the string - @b unnamed but can be overridden in the derived classes to do something more - appropriate. + Return a string containing a suitable default name for a new document. + By default this is implemented by appending an integer counter to the + string @b unnamed but can be overridden in the derived classes to do + something more appropriate. */ wxString MakeNewDocumentName(); /** - A hook to allow a derived class to create a different type of file history. - Called - from Initialize(). + A hook to allow a derived class to create a different type of file + history. Called from Initialize(). */ wxFileHistory* OnCreateFileHistory(); @@ -483,7 +468,8 @@ public: void OnFileCloseAll(wxCommandEvent& event); /** - Creates a document from a list of templates (if more than one template). + Creates a document from a list of templates (if more than one + template). */ void OnFileNew(wxCommandEvent& event); @@ -493,18 +479,19 @@ public: void OnFileOpen(wxCommandEvent& event); /** - Reverts the current document by calling wxDocument::Revert for the current - document. + Reverts the current document by calling wxDocument::Revert() for the + current document. */ void OnFileRevert(wxCommandEvent& event); /** - Saves the current document by calling wxDocument::Save for the current document. + Saves the current document by calling wxDocument::Save() for the + current document. */ void OnFileSave(wxCommandEvent& event); /** - Calls wxDocument::SaveAs for the current document. + Calls wxDocument::SaveAs() for the current document. */ void OnFileSaveAs(wxCommandEvent& event); @@ -514,122 +501,110 @@ public: void RemoveDocument(wxDocument* doc); /** - Under Windows, pops up a file selector with a list of filters corresponding to - document templates. - The wxDocTemplate corresponding to the selected file's extension is returned. - On other platforms, if there is more than one document template a choice list - is popped up, - followed by a file selector. + Under Windows, pops up a file selector with a list of filters + corresponding to document templates. The wxDocTemplate corresponding to + the selected file's extension is returned. + + On other platforms, if there is more than one document template a + choice list is popped up, followed by a file selector. + This function is used in CreateDocument(). - (doctemplate, path) = My::DocManager-SelectDocumentPath( ... ); */ wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates, - int noTemplates, - wxString& path, - long flags, - bool save); + int noTemplates, wxString& path, + long flags, bool save); /** - Returns a document template by asking the user (if there is more than one - template). - This function is used in CreateDocument(). + Returns a document template by asking the user (if there is more than + one template). This function is used in CreateDocument(). @param templates - Pointer to an array of templates from which to choose a desired template. + Pointer to an array of templates from which to choose a desired + template. @param noTemplates Number of templates being pointed to by the templates pointer. @param sort - If more than one template is passed in in templates, - then this parameter indicates whether the list of templates that the user - will have to choose from is sorted or not when shown the choice box dialog. - - Default is @false. + If more than one template is passed in in templates, then this + parameter indicates whether the list of templates that the user + will have to choose from is sorted or not when shown the choice box + dialog. Default is @false. */ wxDocTemplate* SelectDocumentType(wxDocTemplate** templates, - int noTemplates, - bool sort = false); + int noTemplates, bool sort = false); /** - Returns a document template by asking the user (if there is more than one - template), - displaying a list of valid views. This function is used in CreateView(). - The dialog normally will not appear because the array of templates only contains - those relevant to the document in question, and often there will only be one - such. + Returns a document template by asking the user (if there is more than + one template), displaying a list of valid views. This function is used + in CreateView(). The dialog normally will not appear because the array + of templates only contains those relevant to the document in question, + and often there will only be one such. @param templates - Pointer to an array of templates from which to choose a desired template. + Pointer to an array of templates from which to choose a desired + template. @param noTemplates Number of templates being pointed to by the templates pointer. @param sort - If more than one template is passed in in templates, - then this parameter indicates whether the list of templates that the user - will have to choose from is sorted or not when shown the choice box dialog. - - Default is @false. + If more than one template is passed in in templates, then this + parameter indicates whether the list of templates that the user + will have to choose from is sorted or not when shown the choice box + dialog. Default is @false. */ wxDocTemplate* SelectViewType(wxDocTemplate** templates, - int noTemplates, - bool sort = false); + int noTemplates, bool sort = false); /** - Sets the directory to be displayed to the user when opening a file. Initially - this is empty. + Sets the directory to be displayed to the user when opening a file. + Initially this is empty. */ void SetLastDirectory(const wxString& dir); /** - Sets the maximum number of documents that can be open at a time. By default, - this - is 10,000. If you set it to 1, existing documents will be saved and deleted - when the user tries to open or create a new one (similar to the behaviour - of Windows Write, for example). Allowing multiple documents gives behaviour - more akin to MS Word and other Multiple Document Interface applications. + Sets the maximum number of documents that can be open at a time. By + default, this is 10,000. If you set it to 1, existing documents will be + saved and deleted when the user tries to open or create a new one + (similar to the behaviour of Windows Write, for example). Allowing + multiple documents gives behaviour more akin to MS Word and other + Multiple Document Interface applications. */ void SetMaxDocsOpen(int n); /** - wxView* m_currentView The currently active view. */ - + wxView* m_currentView; /** - int m_defaultDocumentNameCounter Stores the integer to be used for the next default document name. */ - + int m_defaultDocumentNameCounter; /** - wxList m_docs A list of all documents. */ - + wxList m_docs; /** - wxFileHistory* m_fileHistory - A pointer to an instance of wxFileHistory, - which manages the history of recently-visited files on the File menu. + A pointer to an instance of wxFileHistory, which manages the history of + recently-visited files on the File menu. */ - + wxFileHistory* m_fileHistory; /** - long m_flags Stores the flags passed to the constructor. */ - + long m_flags; /** The directory last selected by the user when opening a file. - wxFileHistory* m_fileHistory */ - + wxFileHistory* m_fileHistory; /** - int m_maxDocsOpen Stores the maximum number of documents that can be opened before existing documents are closed. By default, this is 10,000. */ + int m_maxDocsOpen; }; @@ -640,23 +615,20 @@ public: The view class can be used to model the viewing and editing component of an application's file-based data. It is part of the document/view framework - supported by wxWidgets, - and cooperates with the wxDocument, wxDocTemplate + supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate and wxDocManager classes. @library{wxcore} - @category{dvf} + @category{docview} - @see @ref overview_wxviewoverview "wxView overview", wxDocument, wxDocTemplate, - wxDocManager + @see @ref overview_docview_wxview, wxDocument, wxDocTemplate, wxDocManager */ class wxView : public wxEvtHandler { public: /** Constructor. Define your own default constructor to initialize - application-specific - data. + application-specific data. */ wxView(); @@ -666,22 +638,22 @@ public: ~wxView(); /** - Call this from your view frame's OnActivate member to tell the framework which - view is - currently active. If your windowing system doesn't call OnActivate, you may - need to - call this function from any place where you know the view must - be active, and the framework will need to get the current view. - The prepackaged view frame wxDocChildFrame calls Activate() from its OnActivate - member. + Call this from your view frame's wxDocChildFrame::OnActivate() member + to tell the framework which view is currently active. If your windowing + system doesn't call wxDocChildFrame::OnActivate(), you may need to call + this function from any place where you know the view must be active, + and the framework will need to get the current view. + + The prepackaged view frame wxDocChildFrame calls Activate() from its + wxDocChildFrame::OnActivate() member. + This function calls OnActivateView(). */ virtual void Activate(bool activate); /** - Closes the view by calling OnClose. If @a deleteWindow is @true, this function - should - delete the window associated with the view. + Closes the view by calling OnClose(). If @a deleteWindow is @true, this + function should delete the window associated with the view. */ virtual bool Close(bool deleteWindow = true); @@ -691,74 +663,76 @@ public: wxDocument* GetDocument() const; /** - Returns a pointer to the document manager instance associated with this view. + Returns a pointer to the document manager instance associated with this + view. */ wxDocManager* GetDocumentManager() const; /** - Gets the frame associated with the view (if any). Note that this "frame" is - not a wxFrame at all in the generic MDI implementation which uses the notebook - pages instead of the frames and this is why this method returns a wxWindow and - not a wxFrame. + Gets the frame associated with the view (if any). Note that this + "frame" is not a wxFrame at all in the generic MDI implementation which + uses notebook pages instead of frames and this is why this method + returns a wxWindow and not a wxFrame. */ wxWindow* GetFrame(); /** Gets the name associated with the view (passed to the wxDocTemplate - constructor). - Not currently used by the framework. + constructor). Not currently used by the framework. */ wxString GetViewName() const; /** Called when a view is activated by means of Activate(). The default - implementation does - nothing. + implementation does nothing. */ virtual void OnActivateView(bool activate, wxView* activeView, wxView* deactiveView); /** - Called when the filename has changed. The default implementation constructs a - suitable title and sets the title of the view frame (if any). + Called when the filename has changed. The default implementation + constructs a suitable title and sets the title of the view frame (if + any). */ virtual void OnChangeFilename(); /** - Implements closing behaviour. The default implementation calls wxDocument::Close - to close the associated document. Does not delete the view. The application - may wish to do some cleaning up operations in this function, @e if a - call to wxDocument::Close succeeded. For example, if your views - all share the same window, you need to disassociate the window from the view - and perhaps clear the window. If @a deleteWindow is @true, delete the - frame associated with the view. + Implements closing behaviour. The default implementation calls + wxDocument::Close() to close the associated document. Does not delete + the view. The application may wish to do some cleaning up operations in + this function, @e if a call to wxDocument::Close() succeeded. For + example, if your views all share the same window, you need to + disassociate the window from the view and perhaps clear the window. If + @a deleteWindow is @true, delete the frame associated with the view. */ virtual bool OnClose(bool deleteWindow); /** - Override this to clean up the view when the document is being - closed. + Override this to clean up the view when the document is being closed. */ virtual void OnClosingDocument(); /** - wxDocManager or wxDocument creates a wxView via a wxDocTemplate. - Just after the wxDocTemplate creates the wxView, it calls - OnCreate(). In its OnCreate member function, the wxView can create a - wxDocChildFrame - or a derived class. This wxDocChildFrame provides user interface - elements to view and/or edit the contents of the wxDocument. + wxDocManager or wxDocument creates a wxView via a wxDocTemplate. Just + after the wxDocTemplate creates the wxView, it calls OnCreate(). The + wxView can create a wxDocChildFrame (or derived class) in its + wxView::OnCreate() member function. This wxDocChildFrame provides user + interface elements to view and/or edit the contents of the wxDocument. + By default, simply returns @true. If the function returns @false, the view will be deleted. */ virtual bool OnCreate(wxDocument* doc, long flags); /** - If the printing framework is enabled in the library, this function returns a - wxPrintout object for the purposes of printing. It should create a new object - every time it is called; the framework will delete objects it creates. - By default, this function returns an instance of wxDocPrintout, which prints - and previews one page by calling OnDraw(). + If the printing framework is enabled in the library, this function + returns a wxPrintout object for the purposes of printing. It should + create a new object every time it is called; the framework will delete + objects it creates. + + By default, this function returns an instance of wxDocPrintout, which + prints and previews one page by calling OnDraw(). + Override to return an instance of a class other than wxDocPrintout. */ virtual wxPrintout* OnCreatePrintout(); @@ -769,11 +743,16 @@ public: virtual void OnDraw(wxDC* dc); /** - Called when the view should be updated. @a sender is a pointer to the view - that sent the update request, or @NULL if no single view requested the update - (for instance, - when the document is opened). @a hint is as yet unused but may in future contain - application-specific information for making updating more efficient. + Called when the view should be updated. + + @param sender + A pointer to the wxView that sent the update request, or @NULL if + no single view requested the update (for instance, when the + document is opened). + @param hint + This is unused currently, but may in future contain + application-specific information for making updating more + efficient. */ virtual void OnUpdate(wxView* sender, wxObject* hint); @@ -784,10 +763,11 @@ public: void SetDocument(wxDocument* doc); /** - Sets the frame associated with this view. The application should call this - if possible, to tell the view about the frame. - See GetFrame() for the explanation about the mismatch - between the "Frame" in the method name and the type of its parameter. + Sets the frame associated with this view. The application should call + this if possible, to tell the view about the frame. + + See GetFrame() for the explanation about the mismatch between the + "Frame" in the method name and the type of its parameter. */ void SetFrame(wxWindow* frame); @@ -797,23 +777,23 @@ public: void SetViewName(const wxString& name); /** - wxDocument* m_viewDocument - The document associated with this view. There may be more than one view per - document, but there can never be more than one document for one view. + The document associated with this view. There may be more than one view + per document, but there can never be more than one document for one + view. */ - + wxDocument* m_viewDocument; /** - wxFrame* m_viewFrame Frame associated with the view, if any. */ - + wxFrame* m_viewFrame; /** - wxString m_viewTypeName - The view type name given to the wxDocTemplate constructor, copied to this - variable when the view is created. Not currently used by the framework. + The view type name given to the wxDocTemplate constructor, copied to + this variable when the view is created. Not currently used by the + framework. */ + wxString m_viewTypeName; }; @@ -823,18 +803,17 @@ public: @wxheader{docview.h} The wxDocChildFrame class provides a default frame for displaying documents - on separate windows. This class can only be used for SDI (not MDI) child frames. + on separate windows. This class can only be used for SDI (not MDI) child + frames. The class is part of the document/view framework supported by wxWidgets, - and cooperates with the wxView, wxDocument, - wxDocManager and wxDocTemplate classes. - - See the example application in @c samples/docview. + and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate + classes. @library{wxcore} - @category{dvf} + @category{docview} - @see @ref overview_docviewoverview, wxFrame + @see @ref overview_docview, @ref page_samples_docview, wxFrame */ class wxDocChildFrame : public wxFrame { @@ -843,8 +822,7 @@ public: Constructor. */ wxDocChildFrame(wxDocument* doc, wxView* view, wxFrame* parent, - wxWindowID id, - const wxString& title, + wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxDEFAULT_FRAME_STYLE, @@ -866,8 +844,8 @@ public: wxView* GetView() const; /** - Sets the currently active view to be the frame's view. You may need - to override (but still call) this function in order to set the keyboard + Sets the currently active view to be the frame's view. You may need to + override (but still call) this function in order to set the keyboard focus for your subwindow. */ void OnActivate(wxActivateEvent event); @@ -888,15 +866,14 @@ public: void SetView(wxView* view); /** - wxDocument* m_childDocument The document associated with the frame. */ - + wxDocument* m_childDocument; /** - wxView* m_childView The view associated with the frame. */ + wxView* m_childView; }; @@ -906,35 +883,33 @@ public: @wxheader{docview.h} The wxDocParentFrame class provides a default top-level frame for - applications using the document/view framework. This class can only be used for - SDI (not MDI) parent frames. + applications using the document/view framework. This class can only be used + for SDI (not MDI) parent frames. - It cooperates with the wxView, wxDocument, - wxDocManager and wxDocTemplates() classes. - - See the example application in @c samples/docview. + It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate + classes. @library{wxcore} - @category{dvf} + @category{docview} - @see @ref overview_docviewoverview, wxFrame + @see @ref overview_docview, @ref page_samples_docview, wxFrame */ class wxDocParentFrame : public wxFrame { public: - //@{ /** - Constructor. + Default constructor. */ wxDocParentFrame(); + /** + Constructor. + */ wxDocParentFrame(wxDocManager* manager, wxFrame* parent, - wxWindowID id, - const wxString& title, + wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxDEFAULT_FRAME_STYLE, const wxString& name = "frame"); - //@} /** Destructor. @@ -952,15 +927,27 @@ public: const wxString& name = "frame"); /** - Returns the associated @ref overview_wxdocmanager "document manager object". + Returns the associated document manager object. */ wxDocManager* GetDocumentManager() const; /** Deletes all views and documents. If no user input cancelled the operation, the frame will be destroyed and the application will exit. - Since understanding how document/view clean-up takes place can be difficult, - the implementation of this function is shown below. + Since understanding how document/view clean-up takes place can be + difficult, the implementation of this function is shown below: + + @code + void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event) + { + if (m_docManager->Clear(!event.CanVeto())) + { + this->Destroy(); + } + else + event.Veto(); + } + @endcode */ void OnCloseWindow(wxCloseEvent& event); }; @@ -971,24 +958,21 @@ public: @class wxDocument @wxheader{docview.h} - The document class can be used to model an application's file-based - data. It is part of the document/view framework supported by wxWidgets, - and cooperates with the wxView, wxDocTemplate - and wxDocManager classes. + The document class can be used to model an application's file-based data. + It is part of the document/view framework supported by wxWidgets, and + cooperates with the wxView, wxDocTemplate and wxDocManager classes. @library{wxcore} - @category{dvf} + @category{docview} - @see @ref overview_wxdocumentoverview "wxDocument overview", wxView, - wxDocTemplate, wxDocManager + @see @ref overview_docview, wxView, wxDocTemplate, wxDocManager */ class wxDocument : public wxEvtHandler { public: /** Constructor. Define your own default constructor to initialize - application-specific - data. + application-specific data. */ wxDocument(); @@ -998,31 +982,32 @@ public: ~wxDocument(); /** - If the view is not already in the list of views, adds the view and calls - OnChangedViewList. + If the view is not already in the list of views, adds the view and + calls OnChangedViewList(). */ virtual bool AddView(wxView* view); /** - Closes the document, by calling OnSaveModified and then (if this returned @true) - OnCloseDocument. - This does not normally delete the document object: use DeleteAllViews to do - this implicitly. + Closes the document, by calling OnSaveModified() and then (if this + returned @true) OnCloseDocument(). This does not normally delete the + document object, use DeleteAllViews() to do this implicitly. */ virtual bool Close(); /** - Calls wxView::Close and deletes each view. Deleting the final view will - implicitly - delete the document itself, because the wxView destructor calls RemoveView. This - in turns calls OnChangedViewList(), whose default implemention is to - save and delete the document if no views exist. + Calls wxView::Close() and deletes each view. Deleting the final view + will implicitly delete the document itself, because the wxView + destructor calls RemoveView(). This in turns calls OnChangedViewList(), + whose default implemention is to save and delete the document if no + views exist. */ virtual bool DeleteAllViews(); /** - Returns a pointer to the command processor associated with this document. - See wxCommandProcessor. + Returns a pointer to the command processor associated with this + document. + + @see wxCommandProcessor */ wxCommandProcessor* GetCommandProcessor() const; @@ -1033,7 +1018,7 @@ public: /** Gets the document type name for this document. See the comment for - documentTypeName(). + @ref m_documentTypeName. */ wxString GetDocumentName() const; @@ -1043,8 +1028,9 @@ public: wxDocTemplate* GetDocumentTemplate() const; /** - Intended to return a suitable window for using as a parent for document-related - dialog boxes. By default, uses the frame associated with the first view. + Intended to return a suitable window for using as a parent for + document-related dialog boxes. By default, uses the frame associated + with the first view. */ wxWindow* GetDocumentWindow() const; @@ -1055,16 +1041,17 @@ public: wxString GetFilename() const; /** - A convenience function to get the first view for a document, because - in many cases a document will only have a single view. - See also: GetViews() + A convenience function to get the first view for a document, because in + many cases a document will only have a single view. + + @see GetViews() */ wxView* GetFirstView() const; /** - Gets the title for this document. The document title is used for an associated - frame (if any), and is usually constructed by the framework from - the filename. + Gets the title for this document. The document title is used for an + associated frame (if any), and is usually constructed by the framework + from the filename. */ wxString GetTitle() const; @@ -1077,174 +1064,177 @@ public: /** Returns the list whose elements are the views on the document. - See also: GetFirstView() + + @see GetFirstView() */ wxList GetViews() const; /** - Returns @true if the document has been modified since the last save, @false - otherwise. - You may need to override this if your document view maintains its own - record of being modified (for example if using wxTextWindow to view and edit - the document). - See also Modify(). + Returns @true if the document has been modified since the last save, + @false otherwise. You may need to override this if your document view + maintains its own record of being modified. + + @see Modify() */ virtual bool IsModified() const; //@{ /** - Override this function and call it from your own LoadObject before - streaming your own data. LoadObject is called by the framework + Override this function and call it from your own LoadObject() before + streaming your own data. LoadObject() is called by the framework automatically when the document contents need to be loaded. - Note that only one of these forms exists, depending on how wxWidgets - was configured. + + @note This version of LoadObject() may not exist depending on how + wxWidgets was configured. */ - virtual istream LoadObject(istream& stream); - virtual wxInputStream LoadObject(wxInputStream& stream); + virtual istream& LoadObject(istream& stream); + virtual wxInputStream& LoadObject(wxInputStream& stream); //@} /** - Call with @true to mark the document as modified since the last save, @false - otherwise. - You may need to override this if your document view maintains its own - record of being modified (for example if using wxTextWindow to view and edit - the document). - See also IsModified(). + Call with @true to mark the document as modified since the last save, + @false otherwise. You may need to override this if your document view + maintains its own record of being modified. + + @see IsModified() */ virtual void Modify(bool modify); /** - Called when a view is added to or deleted from this document. The default - implementation saves and deletes the document if no views exist (the last - one has just been removed). + Called when a view is added to or deleted from this document. The + default implementation saves and deletes the document if no views exist + (the last one has just been removed). */ virtual void OnChangedViewList(); /** - The default implementation calls DeleteContents (an empty implementation) - sets the modified flag to @false. Override this to - supply additional behaviour when the document is closed with Close. + The default implementation calls DeleteContents() (an empty + implementation) and sets the modified flag to @false. Override this to + supply additional behaviour when the document is closed with Close(). */ virtual bool OnCloseDocument(); /** - Called just after the document object is created to give it a chance - to initialize itself. The default implementation uses the - template associated with the document to create an initial view. - If this function returns @false, the document is deleted. + Called just after the document object is created to give it a chance to + initialize itself. The default implementation uses the template + associated with the document to create an initial view. If this + function returns @false, the document is deleted. */ virtual bool OnCreate(const wxString& path, long flags); /** - Override this function if you want a different (or no) command processor - to be created when the document is created. By default, it returns - an instance of wxCommandProcessor. - See wxCommandProcessor. + Override this function if you want a different (or no) command + processor to be created when the document is created. By default, it + returns an instance of wxCommandProcessor. + + @see wxCommandProcessor */ virtual wxCommandProcessor* OnCreateCommandProcessor(); /** - The default implementation calls OnSaveModified and DeleteContents, makes a - default title for the - document, and notifies the views that the filename (in fact, the title) has - changed. + The default implementation calls OnSaveModified() and DeleteContents(), + makes a default title for the document, and notifies the views that the + filename (in fact, the title) has changed. */ virtual bool OnNewDocument(); /** - Constructs an input file stream for the given filename (which must not be - empty), - and calls LoadObject. If LoadObject returns @true, the document is set to - unmodified; otherwise, an error message box is displayed. The document's - views are notified that the filename has changed, to give windows an opportunity - to update their titles. All of the document's views are then updated. + Constructs an input file stream for the given filename (which must not + be empty), and calls LoadObject(). If LoadObject() returns @true, the + document is set to unmodified; otherwise, an error message box is + displayed. The document's views are notified that the filename has + changed, to give windows an opportunity to update their titles. All of + the document's views are then updated. */ virtual bool OnOpenDocument(const wxString& filename); /** - Constructs an output file stream for the given filename (which must not be - empty), - and calls SaveObject. If SaveObject returns @true, the document is set to - unmodified; otherwise, an error message box is displayed. + Constructs an output file stream for the given filename (which must not + be empty), and calls SaveObject(). If SaveObject() returns @true, the + document is set to unmodified; otherwise, an error message box is + displayed. */ virtual bool OnSaveDocument(const wxString& filename); /** - If the document has been modified, prompts the user to ask if the changes should - be changed. If the user replies Yes, the Save function is called. If No, the - document is marked as unmodified and the function succeeds. If Cancel, the - function fails. + If the document has been modified, prompts the user to ask if the + changes should be changed. If the user replies Yes, the Save() function + is called. If No, the document is marked as unmodified and the function + succeeds. If Cancel, the function fails. */ virtual bool OnSaveModified(); /** - Removes the view from the document's list of views, and calls OnChangedViewList. + Removes the view from the document's list of views, and calls + OnChangedViewList(). */ virtual bool RemoveView(wxView* view); /** - Saves the document by calling OnSaveDocument if there is an associated filename, - or SaveAs if there is no filename. + Saves the document by calling OnSaveDocument() if there is an + associated filename, or SaveAs() if there is no filename. */ virtual bool Save(); /** - Prompts the user for a file to save to, and then calls OnSaveDocument. + Prompts the user for a file to save to, and then calls + OnSaveDocument(). */ virtual bool SaveAs(); //@{ /** - Override this function and call it from your own SaveObject before - streaming your own data. SaveObject is called by the framework + Override this function and call it from your own SaveObject() before + streaming your own data. SaveObject() is called by the framework automatically when the document contents need to be saved. - Note that only one of these forms exists, depending on how wxWidgets - was configured. + + @note This version of SaveObject() may not exist depending on how + wxWidgets was configured. */ - virtual ostream SaveObject(ostream& stream); - virtual wxOutputStream SaveObject(wxOutputStream& stream); + virtual ostream& SaveObject(ostream& stream); + virtual wxOutputStream& SaveObject(wxOutputStream& stream); //@} /** - Sets the command processor to be used for this document. The document will then - be responsible - for its deletion. Normally you should not call this; override - OnCreateCommandProcessor - instead. - See wxCommandProcessor. + Sets the command processor to be used for this document. The document + will then be responsible for its deletion. Normally you should not call + this; override OnCreateCommandProcessor() instead. + + @see wxCommandProcessor */ virtual void SetCommandProcessor(wxCommandProcessor* processor); /** Sets the document type name for this document. See the comment for - documentTypeName(). + @ref m_documentTypeName. */ void SetDocumentName(const wxString& name); /** - Sets the pointer to the template that created the document. Should only be - called by the - framework. + Sets the pointer to the template that created the document. Should only + be called by the framework. */ void SetDocumentTemplate(wxDocTemplate* templ); /** Sets the filename for this document. Usually called by the framework. - If @a notifyViews is @true, wxView::OnChangeFilename is called for all views. + + If @a notifyViews is @true, wxView::OnChangeFilename() is called for + all views. */ - void SetFilename(const wxString& filename, - bool notifyViews = false); + void SetFilename(const wxString& filename, bool notifyViews = false); /** - Sets the title for this document. The document title is used for an associated - frame (if any), and is usually constructed by the framework from - the filename. + Sets the title for this document. The document title is used for an + associated frame (if any), and is usually constructed by the framework + from the filename. */ void SetTitle(const wxString& title); /** - Updates all views. If @a sender is non-@NULL, does not update this view. - @a hint represents optional information to allow a view to optimize its update. + Updates all views. If @a sender is non-@NULL, does not update this + view. @a hint represents optional information to allow a view to + optimize its update. */ void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL); @@ -1269,54 +1259,46 @@ protected: */ virtual bool DoOpenDocument(const wxString& file); - /** - wxCommandProcessor* m_commandProcessor A pointer to the command processor associated with this document. */ - + wxCommandProcessor* m_commandProcessor; /** - wxString m_documentFile Filename associated with this document ("" if none). */ - + wxString m_documentFile; /** - bool m_documentModified @true if the document has been modified, @false otherwise. */ - + bool m_documentModified; /** - wxDocTemplate * m_documentTemplate A pointer to the template from which this document was created. */ - + wxDocTemplate* m_documentTemplate; /** - wxString m_documentTitle - Document title. The document title is used for an associated - frame (if any), and is usually constructed by the framework from - the filename. + Document title. The document title is used for an associated frame (if + any), and is usually constructed by the framework from the filename. */ - + wxString m_documentTitle; /** - wxString m_documentTypeName - The document type name given to the wxDocTemplate constructor, copied to this - variable when the document is created. If several document templates are - created that use the same document type, this variable is used in - wxDocManager::CreateView - to collate a list of alternative view types that can be used on this kind of - document. Do not change the value of this variable. + The document type name given to the wxDocTemplate constructor, copied + to this variable when the document is created. If several document + templates are created that use the same document type, this variable is + used in wxDocManager::CreateView() to collate a list of alternative + view types that can be used on this kind of document. Do not change the + value of this variable. */ - + wxString m_documentTypeName; /** - wxList m_documentViews List of wxView instances associated with this document. */ + wxList m_documentViews; }; @@ -1325,19 +1307,17 @@ protected: @class wxFileHistory @wxheader{docview.h} - The wxFileHistory encapsulates a user interface convenience, the - list of most recently visited files as shown on a menu (usually the File menu). + The wxFileHistory encapsulates a user interface convenience, the list of + most recently visited files as shown on a menu (usually the File menu). wxFileHistory can manage one or more file menus. More than one menu may be - required - in an MDI application, where the file history should appear on each MDI child - menu - as well as the MDI parent frame. + required in an MDI application, where the file history should appear on + each MDI child menu as well as the MDI parent frame. @library{wxcore} - @category{FIXME} + @category{docview} - @see @ref overview_wxfilehistoryoverview "wxFileHistory overview", wxDocManager + @see @ref overview_docview, wxDocManager */ class wxFileHistory : public wxObject { @@ -1345,13 +1325,13 @@ public: /** Constructor. Pass the maximum number of files that should be stored and displayed. - @a idBase defaults to wxID_FILE1 and represents the id given to the first - history menu item. Since menu items can't share the same ID you should change - idBase (To one of your own defined IDs) when using more than one wxFileHistory - in your application. + + @a idBase defaults to wxID_FILE1 and represents the id given to the + first history menu item. Since menu items can't share the same ID you + should change @a idBase (to one of your own defined IDs) when using + more than one wxFileHistory in your application. */ - wxFileHistory(size_t maxFiles = 9, - wxWindowID idBase = wxID_FILE1); + wxFileHistory(size_t maxFiles = 9, wxWindowID idBase = wxID_FILE1); /** Destructor. @@ -1364,13 +1344,15 @@ public: */ void AddFileToHistory(const wxString& filename); - //@{ /** - Appends the files in the history list, to the given menu only. + Appends the files in the history list, to all menus managed by the file + history object. */ void AddFilesToMenu(); + /** + Appends the files in the history list, to the given menu only. + */ void AddFilesToMenu(wxMenu* menu); - //@} /** Returns the base identifier for the range used for appending items. @@ -1397,13 +1379,13 @@ public: @see UseMenu() */ - const wxList GetMenus() const; + const wxList& GetMenus() const; /** - Loads the file history from the given config object. This function should be - called explicitly by the application. + Loads the file history from the given config object. This function + should be called explicitly by the application. - @see wxConfig() + @see wxConfigBase */ void Load(wxConfigBase& config); @@ -1418,10 +1400,10 @@ public: void RemoveMenu(wxMenu* menu); /** - Saves the file history into the given config object. This must be called - explicitly by the application. + Saves the file history into the given config object. This must be + called explicitly by the application. - @see wxConfig() + @see wxConfigBase */ void Save(wxConfigBase& config); @@ -1431,37 +1413,33 @@ public: void SetBaseId(wxWindowID baseId); /** - Adds this menu to the list of those menus that are managed by this file history - object. - Also see AddFilesToMenu() for - initializing the menu with filenames that are already in the history when this - function is called, as this is not done automatically. + Adds this menu to the list of those menus that are managed by this file + history object. Also see AddFilesToMenu() for initializing the menu + with filenames that are already in the history when this function is + called, as this is not done automatically. */ void UseMenu(wxMenu* menu); /** - char** m_fileHistory A character array of strings corresponding to the most recently opened files. */ - + char** m_fileHistory; /** - size_t m_fileHistoryN The number of files stored in the history array. */ - + size_t m_fileHistoryN; /** - size_t m_fileMaxFiles The maximum number of files to be stored and displayed on the menu. */ - + size_t m_fileMaxFiles; /** - wxMenu* m_fileMenu The file menu used to display the file history list (if enabled). */ + wxMenu* m_fileMenu; }; diff --git a/interface/dragimag.h b/interface/dragimag.h index 5b2dd488cc..9de1317021 100644 --- a/interface/dragimag.h +++ b/interface/dragimag.h @@ -10,89 +10,138 @@ @class wxDragImage @wxheader{dragimag.h} - This class is used when you wish to drag an object on the screen, - and a simple cursor is not enough. + This class is used when you wish to drag an object on the screen, and a + simple cursor is not enough. On Windows, the Win32 API is used to achieve smooth dragging. On other - platforms, - wxGenericDragImage is used. Applications may also prefer to use + platforms, wxGenericDragImage is used. Applications may also prefer to use wxGenericDragImage on Windows, too. - @b wxPython note: wxPython uses wxGenericDragImage on all platforms, but - uses the wxDragImage name. + @beginWxPythonOnly + wxPython uses wxGenericDragImage on all platforms, but uses the wxDragImage + name. + @endWxPythonOnly To use this class, when you wish to start dragging an image, create a - wxDragImage - object and store it somewhere you can access it as the drag progresses. - Call BeginDrag to start, and EndDrag to stop the drag. To move the image, - initially call Show and then Move. If you wish to update the screen contents - during the drag (for example, highlight an item as in the dragimag sample), - first call Hide, - update the screen, call Move, and then call Show. + wxDragImage object and store it somewhere you can access it as the drag + progresses. Call BeginDrag() to start, and EndDrag() to stop the drag. To + move the image, initially call Show() and then Move(). If you wish to + update the screen contents during the drag (for example, highlight an item + as in the dragimag sample), first call Hide(), update the screen, call + Move(), and then call Show(). - You can drag within one window, or you can use full-screen dragging - either across the whole screen, or just restricted to one area - of the screen to save resources. If you want the user to drag between - two windows, then you will need to use full-screen dragging. + You can drag within one window, or you can use full-screen dragging either + across the whole screen, or just restricted to one area of the screen to + save resources. If you want the user to drag between two windows, then you + will need to use full-screen dragging. - If you wish to draw the image yourself, use wxGenericDragImage and - override wxDragImage::DoDrawImage and - wxDragImage::GetImageRect. - - Please see @c samples/dragimag for an example. + If you wish to draw the image yourself, use wxGenericDragImage and override + DoDrawImage() and GetImageRect(). @library{wxcore} - @category{FIXME} + @category{dnd} + + @see @ref page_samples_dragimag */ class wxDragImage : public wxObject { public: - //@{ /** - ) - Constructs a drag image an optional cursor. This constructor is only available - for - wxGenericDragImage, and can be used when the application - supplies DoDrawImage() and GetImageRect(). + Default constructor. + */ + wxDragImage(); + /** + Constructs a drag image from a bitmap and optional cursor. + + @param image + Bitmap to be used as the drag image. The bitmap can have a mask. + @param cursor + Optional cursor to combine with the image. + @param cursorHotspot + This parameter is deprecated. + */ + wxDragImage(const wxBitmap& image, const wxCursor& cursor = wxNullCursor, + const wxPoint& cursorHotspot = wxPoint(0, 0)); + /** + Constructs a drag image from an icon and optional cursor. @param image - Icon or bitmap to be used as the drag image. The bitmap can - have a mask. + Icon to be used as the drag image. + @param cursor + Optional cursor to combine with the image. + @param cursorHotspot + This parameter is deprecated. + + @beginWxPythonOnly + This constructor is called wxDragIcon in wxPython. + @endWxPythonOnly + */ + wxDragImage(const wxIcon& image, const wxCursor& cursor = wxNullCursor, + const wxPoint& cursorHotspot = wxPoint(0, 0)); + /** + Constructs a drag image from a text string and optional cursor. + @param text Text used to construct a drag image. @param cursor Optional cursor to combine with the image. - @param hotspot + @param cursorHotspot This parameter is deprecated. + + @beginWxPythonOnly + This constructor is called wxDragString in wxPython. + @endWxPythonOnly + */ + wxDragImage(const wxString& text, const wxCursor& cursor = wxNullCursor, + const wxPoint& cursorHotspot = wxPoint(0, 0)); + /** + Constructs a drag image from the text in the given tree control item, + and optional cursor. + @param treeCtrl Tree control for constructing a tree drag image. + @param id + Tree control item id. + + @beginWxPythonOnly + This constructor is called wxDragTreeItem in wxPython. + @endWxPythonOnly + */ + wxDragImage(const wxTreeCtrl& treeCtrl, wxTreeItemId& id); + /** + Constructs a drag image from the text in the given list control item, + and optional cursor. + @param listCtrl List control for constructing a list drag image. @param id - Tree or list control item id. + List control item id. + + @beginWxPythonOnly + This constructor is called wxDragListItem in wxPython. + @endWxPythonOnly */ - wxDragImage(); - wxDragImage(const wxBitmap& image, - const wxCursor& cursor = wxNullCursor); - wxDragImage(const wxIcon& image, - const wxCursor& cursor = wxNullCursor); - wxDragImage(const wxString& text, - const wxCursor& cursor = wxNullCursor); - wxDragImage(const wxTreeCtrl& treeCtrl, wxTreeItemId& id); - wxDragImage(const wxListCtrl& treeCtrl, long id); - wxDragImage(const wxCursor& cursor = wxNullCursor); - //@} + wxDragImage(const wxListCtrl& listCtrl, long id); + /** + Constructs a drag image an optional cursor. This constructor is only + available for wxGenericDragImage, and can be used when the application + supplies DoDrawImage() and GetImageRect(). + + @param cursor + Optional cursor to combine with the image. + @param cursorHotspot + This parameter is deprecated. + */ + wxDragImage(const wxCursor& cursor = wxNullCursor, + const wxPoint& cursorHotspot = wxPoint(0, 0)); - //@{ /** - Start dragging the image, using the first window to capture the mouse and the - second - to specify the bounding area. This form is equivalent to using the first form, - but more convenient than working out the bounding rectangle explicitly. - You need to then call Show() - and Move() to show the image on the screen. - Call EndDrag() when the drag has finished. - Note that this call automatically calls CaptureMouse. + Start dragging the image, in a window or full screen. + + You need to then call Show() and Move() to show the image on the + screen. Call EndDrag() when the drag has finished. + + Note that this call automatically calls CaptureMouse(). @param hotspot The location of the drag position relative to the upper-left corner @@ -100,72 +149,87 @@ public: @param window The window that captures the mouse, and within which the dragging is limited unless fullScreen is @true. - @param boundingWindow - In the second form of the function, specifies the - area within which the drag occurs. @param fullScreen If @true, specifies that the drag will be visible over the full - screen, or over as much of the screen as is specified by rect. Note that - the mouse will - still be captured in window. + screen, or over as much of the screen as is specified by rect. Note + that the mouse will still be captured in window. @param rect If non-@NULL, specifies the rectangle (in screen coordinates) that - bounds the dragging operation. Specifying this can make the operation more - efficient - by cutting down on the area under consideration, and it can also make a - visual difference - since the drag is clipped to this area. + bounds the dragging operation. Specifying this can make the + operation more efficient by cutting down on the area under + consideration, and it can also make a visual difference since the + drag is clipped to this area. */ bool BeginDrag(const wxPoint& hotspot, wxWindow* window, - bool fullScreen = false, - wxRect* rect = NULL); + bool fullScreen = false, wxRect* rect = NULL); + /** + Start dragging the image, using the first window to capture the mouse + and the second to specify the bounding area. This form is equivalent to + using the first form, but more convenient than working out the bounding + rectangle explicitly. + + You need to then call Show() and Move() to show the image on the + screen. Call EndDrag() when the drag has finished. + + Note that this call automatically calls CaptureMouse(). + + @param hotspot + The location of the drag position relative to the upper-left corner + of the image. + @param window + The window that captures the mouse, and within which the dragging + is limited. + @param boundingWindow + Specifies the area within which the drag occurs. + */ bool BeginDrag(const wxPoint& hotspot, wxWindow* window, wxWindow* boundingWindow); - //@} /** Draws the image on the device context with top-left corner at the given position. - This function is only available with wxGenericDragImage, to allow applications - to - draw their own image instead of using an actual bitmap. If you override this - function, - you must also override GetImageRect(). + + This function is only available with wxGenericDragImage, to allow + applications to draw their own image instead of using an actual bitmap. + If you override this function, you must also override GetImageRect(). */ virtual bool DoDrawImage(wxDC& dc, const wxPoint& pos); /** Call this when the drag has finished. - Note that this call automatically calls ReleaseMouse. + + @note This function automatically releases mouse capture. */ bool EndDrag(); /** - Returns the rectangle enclosing the image, assuming that the image is drawn - with its - top-left corner at the given point. - This function is available in wxGenericDragImage only, and may be overridden - (together with - wxDragImage::DoDrawImage) to provide a virtual drawing capability. + Returns the rectangle enclosing the image, assuming that the image is + drawn with its top-left corner at the given point. + + This function is available in wxGenericDragImage only, and may be + overridden (together with DoDrawImage()) to provide a virtual drawing + capability. */ virtual wxRect GetImageRect(const wxPoint& pos) const; /** Hides the image. You may wish to call this before updating the window - contents (perhaps highlighting an item). Then call Move() - and Show(). + contents (perhaps highlighting an item). Then call Move() and Show(). */ bool Hide(); /** - Call this to move the image to a new position. The image will only be shown if - Show() has been called previously (for example - at the start of the drag). - @a pt is the position in client coordinates (relative to the window specified - in BeginDrag). - You can move the image either when the image is hidden or shown, but in general - dragging - will be smoother if you move the image when it is shown. + Call this to move the image to a new position. The image will only be + shown if Show() has been called previously (for example at the start of + the drag). + + @param pt + The position in client coordinates (relative to the window + specified in BeginDrag()). + + You can move the image either when the image is hidden or shown, but in + general dragging will be smoother if you move the image when it is + shown. */ bool Move(const wxPoint& pt); @@ -175,20 +239,20 @@ public: bool Show(); /** - Override this if you wish to draw the window contents to the backing bitmap - yourself. This can be desirable if you wish to avoid flicker by not having to - redraw the updated window itself just before dragging, which can cause a - flicker just - as the drag starts. Instead, paint the drag image's backing bitmap to show the - appropriate - graphic @e minus the objects to be dragged, and leave the window itself to be - updated - by the drag image. This can provide eerily smooth, flicker-free drag behaviour. - The default implementation copies the window contents to the backing bitmap. A - new - implementation will normally copy information from another source, such as from - its - own backing bitmap if it has one, or directly from internal data structures. + Override this if you wish to draw the window contents to the backing + bitmap yourself. This can be desirable if you wish to avoid flicker by + not having to redraw the updated window itself just before dragging, + which can cause a flicker just as the drag starts. Instead, paint the + drag image's backing bitmap to show the appropriate graphic @e minus + the objects to be dragged, and leave the window itself to be updated by + the drag image. This can provide eerily smooth, flicker-free drag + behaviour. + + The default implementation copies the window contents to the backing + bitmap. A new implementation will normally copy information from + another source, such as from its own backing bitmap if it has one, or + directly from internal data structures. + This function is available in wxGenericDragImage only. */ bool UpdateBackingFromWindow(wxDC& windowDC, wxMemoryDC& destDC, diff --git a/interface/dynarray.h b/interface/dynarray.h index d5bc122cb9..d5d16b352c 100644 --- a/interface/dynarray.h +++ b/interface/dynarray.h @@ -9,315 +9,336 @@ /** @wxheader{dynarray.h} - This section describes the so called @e dynamic arrays. This is a C + This section describes the so called @e "dynamic arrays". This is a C array-like type safe data structure i.e. the member access time is constant - (and not - linear according to the number of container elements as for linked lists). - However, these - arrays are dynamic in the sense that they will automatically allocate more - memory if there is not enough of it for adding a new element. They also perform - range checking on the index values but in debug mode only, so please be sure to - compile your application in debug mode to use it (see @ref - overview_debuggingoverview "debugging overview" for - details). So, unlike the arrays in some other - languages, attempt to access an element beyond the arrays bound doesn't - automatically expand the array but provokes an assertion failure instead in - debug build and does nothing (except possibly crashing your program) in the - release build. - - The array classes were designed to be reasonably efficient, both in terms of - run-time speed and memory consumption and the executable size. The speed of - array item access is, of course, constant (independent of the number of - elements) - making them much more efficient than linked lists (wxList). - Adding items to the arrays is also implemented in more or less constant time - - but the price is preallocating the memory in advance. In the @ref - wxArray::memorymanagement "memory management" section - you may find some useful hints about optimizing wxArray memory usage. As for - executable size, all - wxArray functions are inline, so they do not take @e any space at all. + (and not linear according to the number of container elements as for linked + lists). However, these arrays are dynamic in the sense that they will + automatically allocate more memory if there is not enough of it for adding + a new element. They also perform range checking on the index values but in + debug mode only, so please be sure to compile your application in debug + mode to use it (see @ref overview_debugging for details). So, unlike the + arrays in some other languages, attempt to access an element beyond the + arrays bound doesn't automatically expand the array but provokes an + assertion failure instead in debug build and does nothing (except possibly + crashing your program) in the release build. + + The array classes were designed to be reasonably efficient, both in terms + of run-time speed and memory consumption and the executable size. The speed + of array item access is, of course, constant (independent of the number of + elements) making them much more efficient than linked lists (wxList). + Adding items to the arrays is also implemented in more or less constant + time, but the price is preallocating the memory in advance. In the + "memory management" function section, you may find some useful hints about + optimizing wxArray memory usage. As for executable size, all wxArray + functions are inline, so they do not take @e any space at all. wxWidgets has three different kinds of array. All of them derive from - wxBaseArray class which works with untyped data and can not be used directly. - The standard macros WX_DEFINE_ARRAY(), WX_DEFINE_SORTED_ARRAY() and - WX_DEFINE_OBJARRAY() are used to define a new class deriving from it. The - classes declared will be called in this documentation wxArray, wxSortedArray and - wxObjArray but you should keep in mind that no classes with such names actually - exist, each time you use one of WX_DEFINE_XXXARRAY macro you define a class - with a new name. In fact, these names are "template" names and each usage of one - of the macros mentioned above creates a template specialization for the given - element type. - - wxArray is suitable for storing integer types and pointers which it does not - treat as objects in any way, i.e. the element pointed to by the pointer is not - deleted when the element is removed from the array. It should be noted that - all of wxArray's functions are inline, so it costs strictly nothing to define as - many array types as you want (either in terms of the executable size or the - speed) as long as at least one of them is defined and this is always the case - because wxArrays are used by wxWidgets internally. This class has one serious - limitation: it can only be used for storing integral types (bool, char, short, - int, long and their unsigned variants) or pointers (of any kind). An attempt - to use with objects of sizeof() greater than sizeof(long) will provoke a - runtime assertion failure, however declaring a wxArray of floats will not (on - the machines where sizeof(float) = sizeof(long)), yet it will @b not work, - please use wxObjArray for storing floats and doubles. - - wxSortedArray is a wxArray variant which should be used when searching in the - array is a frequently used operation. It requires you to define an additional - function for comparing two elements of the array element type and always stores - its items in the sorted order (according to this function). Thus, it is - wxArray::Index function execution time is O(log(N)) instead of - O(N) for the usual arrays but the wxArray::Add method is - slower: it is O(log(N)) instead of constant time (neglecting time spent in - memory allocation routine). However, in a usual situation elements are added to - an array much less often than searched inside it, so wxSortedArray may lead to - huge performance improvements compared to wxArray. Finally, it should be - noticed that, as wxArray, wxSortedArray can be only used for storing integral - types or pointers. - - wxObjArray class treats its elements like "objects". It may delete them when - they are removed from the array (invoking the correct destructor) and copies - them using the objects copy constructor. In order to implement this behaviour - the definition of the wxObjArray arrays is split in two parts: first, you should - declare the new wxObjArray class using WX_DECLARE_OBJARRAY() macro and then - you must include the file defining the implementation of template type: - wx/arrimpl.cpp and define the array class with WX_DEFINE_OBJARRAY() macro - from a point where the full (as opposed to 'forward') declaration of the array - elements class is in scope. As it probably sounds very complicated here is an - example: + wxBaseArray class which works with untyped data and can not be used + directly. The standard macros WX_DEFINE_ARRAY(), WX_DEFINE_SORTED_ARRAY() + and WX_DEFINE_OBJARRAY() are used to define a new class deriving from it. + The classes declared will be called in this documentation wxArray, + wxSortedArray and wxObjArray but you should keep in mind that no classes + with such names actually exist, each time you use one of the + WX_DEFINE_XXXARRAY() macros, you define a class with a new name. In fact, + these names are "template" names and each usage of one of the macros + mentioned above creates a template specialization for the given element + type. + + wxArray is suitable for storing integer types and pointers which it does + not treat as objects in any way, i.e. the element pointed to by the pointer + is not deleted when the element is removed from the array. It should be + noted that all of wxArray's functions are inline, so it costs strictly + nothing to define as many array types as you want (either in terms of the + executable size or the speed) as long as at least one of them is defined + and this is always the case because wxArrays are used by wxWidgets + internally. This class has one serious limitation: it can only be used for + storing integral types (bool, char, short, int, long and their unsigned + variants) or pointers (of any kind). An attempt to use with objects of + @c sizeof() greater than @c sizeof(long) will provoke a runtime assertion + failure, however declaring a wxArray of floats will not (on the machines + where @c "sizeof(float) <= sizeof(long)"), yet it will @b not work, please + use wxObjArray for storing floats and doubles. + + wxSortedArray is a wxArray variant which should be used when searching in + the array is a frequently used operation. It requires you to define an + additional function for comparing two elements of the array element type + and always stores its items in the sorted order (according to this + function). Thus, its Index() function execution time is @c "O(log(N))" + instead of @c "O(N)" for the usual arrays but the Add() method is slower: + it is @c "O(log(N))" instead of constant time (neglecting time spent in + memory allocation routine). However, in a usual situation elements are + added to an array much less often than searched inside it, so wxSortedArray + may lead to huge performance improvements compared to wxArray. Finally, it + should be noticed that, as wxArray, wxSortedArray can be only used for + storing integral types or pointers. + + wxObjArray class treats its elements like "objects". It may delete them + when they are removed from the array (invoking the correct destructor) and + copies them using the objects copy constructor. In order to implement this + behaviour the definition of the wxObjArray arrays is split in two parts: + first, you should declare the new wxObjArray class using the + WX_DECLARE_OBJARRAY() macro and then you must include the file defining the + implementation of template type: @ and define the array + class with the WX_DEFINE_OBJARRAY() macro from a point where the full (as + opposed to 'forward') declaration of the array elements class is in scope. + As it probably sounds very complicated here is an example: @code - #include wx/dynarray.h + #include - // we must forward declare the array because it is used inside the class - // declaration + // We must forward declare the array because it is used + // inside the class declaration. class MyDirectory; class MyFile; - // this defines two new types: ArrayOfDirectories and ArrayOfFiles which can be - // now used as shown below + // This defines two new types: ArrayOfDirectories and ArrayOfFiles which + // can be now used as shown below. WX_DECLARE_OBJARRAY(MyDirectory, ArrayOfDirectories); WX_DECLARE_OBJARRAY(MyFile, ArrayOfFiles); class MyDirectory { - ... - ArrayOfDirectories m_subdirectories; // all subdirectories - ArrayOfFiles m_files; // all files in this directory + // ... + ArrayOfDirectories m_subdirectories; // All subdirectories + ArrayOfFiles m_files; // All files in this directory }; - ... + // ... - // now that we have MyDirectory declaration in scope we may finish the + // Now that we have MyDirectory declaration in scope we may finish the // definition of ArrayOfDirectories -- note that this expands into some C++ // code and so should only be compiled once (i.e., don't put this in the // header, but into a source file or you will get linking errors) - #include wx/arrimpl.cpp // this is a magic incantation which must be done! + #include // This is a magic incantation which must be done! WX_DEFINE_OBJARRAY(ArrayOfDirectories); // that's all! @endcode - It is not as elegant as writing + It is not as elegant as writing this: @code - typedef std::vectorMyDirectory ArrayOfDirectories; + typedef std::vector ArrayOfDirectories; @endcode - but is not that complicated and allows the code to be compiled with any, however - dumb, C++ compiler in the world. + But is not that complicated and allows the code to be compiled with any, + however dumb, C++ compiler in the world. - Remember to include wx/arrimpl.cpp just before each WX_DEFINE_OBJARRAY - ocurrence in your code, even if you have several in the same file. + Remember to include @ just before each + WX_DEFINE_OBJARRAY() ocurrence in your code, even if you have several in + the same file. Things are much simpler for wxArray and wxSortedArray however: it is enough - just to write + just to write: @code WX_DEFINE_ARRAY_INT(int, ArrayOfInts); WX_DEFINE_SORTED_ARRAY_INT(int, ArrayOfSortedInts); @endcode - i.e. there is only one @c DEFINE macro and no need for separate - @c DECLARE one. For the arrays of the primitive types, the macros + There is only one @c DEFINE macro and no need for separate @c DECLARE one. + For the arrays of the primitive types, the macros @c WX_DEFINE_ARRAY_CHAR/SHORT/INT/SIZE_T/LONG/DOUBLE should be used - depending on the sizeof of the values (notice that storing values of smaller - type, e.g. shorts, in an array of larger one, e.g. @c ARRAY_INT, does - not work on all architectures!). + depending on the sizeof of the values (notice that storing values of + smaller type, e.g. shorts, in an array of larger one, e.g. @c ARRAY_INT, + does not work on all architectures!). + + + @section array_macros Macros for Template Array Definition + + To use an array you must first define the array class. This is done with + the help of the macros in this section. The class of array elements must be + (at least) forward declared for WX_DEFINE_ARRAY(), WX_DEFINE_SORTED_ARRAY() + and WX_DECLARE_OBJARRAY() macros and must be fully declared before you use + WX_DEFINE_OBJARRAY() macro. + + - WX_DEFINE_ARRAY() + - WX_DEFINE_EXPORTED_ARRAY() + - WX_DEFINE_USER_EXPORTED_ARRAY() + - WX_DEFINE_SORTED_ARRAY() + - WX_DEFINE_SORTED_EXPORTED_ARRAY() + - WX_DEFINE_SORTED_USER_EXPORTED_ARRAY() + - WX_DECLARE_EXPORTED_OBJARRAY() + - WX_DECLARE_USER_EXPORTED_OBJARRAY() + - WX_DEFINE_OBJARRAY() + - WX_DEFINE_EXPORTED_OBJARRAY() + - WX_DEFINE_USER_EXPORTED_OBJARRAY() + + To slightly complicate the matters even further, the operator "->" defined + by default for the array iterators by these macros only makes sense if the + array element type is not a pointer itself and, although it still works, + this provokes warnings from some compilers and to avoid them you should use + the @c _PTR versions of the macros above. For example, to define an array + of pointers to @c double you should use: + + @code + WX_DEFINE_ARRAY_PTR(double *, MyArrayOfDoublePointers); + @endcode + + Note that the above macros are generally only useful for wxObject types. + There are separate macros for declaring an array of a simple type, such as + an int. + + The following simple types are supported: + - @c int + - @c long + - @c size_t + - @c double + + To create an array of a simple type, simply append the type you want in + CAPS to the array definition. + + For example, you'd use one of the following variants for an integer array: + + - WX_DEFINE_ARRAY_INT() + - WX_DEFINE_EXPORTED_ARRAY_INT() + - WX_DEFINE_USER_EXPORTED_ARRAY_INT() + - WX_DEFINE_SORTED_ARRAY_INT() + - WX_DEFINE_SORTED_EXPORTED_ARRAY_INT() + - WX_DEFINE_SORTED_USER_EXPORTED_ARRAY_INT() + @library{wxbase} - @category{FIXME} + @category{containers} @see @ref overview_container, wxList, wxVector */ class wxArray { public: - //@{ /** - Appends the given number of @a copies of the @a item to the array - consisting of the elements of type @e T. - The first version is used with wxArray. The second is used with wxSortedArray, - returning the index where @a item is stored. The third and the - fourth ones are used with wxObjArray. There is an important difference between - them: if you give a pointer to the array, it will take ownership of it, i.e. - will delete it when the item is deleted from the array. If you give a reference - to the array, however, the array will make a copy of the item and will not take - ownership of the original item. Once again, it only makes sense for wxObjArrays - because the other array types never take ownership of their elements. Also note - that you cannot append more than one pointer as reusing it would lead to - deleting it twice (or more) and hence to a crash. - You may also use WX_APPEND_ARRAY() macro to append all - elements of one array to another one but it is more efficient to use - @a copies parameter and modify the elements in place later if you plan to - append a lot of items. + @name Constructors and Destructors + + Array classes are 100% C++ objects and as such they have the + appropriate copy constructors and assignment operators. Copying wxArray + just copies the elements but copying wxObjArray copies the arrays + items. However, for memory-efficiency sake, neither of these classes + has virtual destructor. It is not very important for wxArray which has + trivial destructor anyhow, but it does mean that you should avoid + deleting wxObjArray through a wxBaseArray pointer (as you would never + use wxBaseArray anyhow it shouldn't be a problem) and that you should + not derive your own classes from the array classes. */ - void Add(T item, size_t copies = 1); - size_t Add(T item); - void Add(T* item); - void Add(T& item, size_t copies = 1); - //@} + //@{ /** - Inserts the given @a item into the array in the specified @e index - position. - Be aware that you will set out the order of the array if you give a wrong - position. - This function is useful in conjunction with - wxArray::IndexForInsert for a common operation - of "insert only if not found". + Default constructor. */ - void AddAt(T item, size_t index); - + wxArray(); /** - wxArray::Add - - wxArray::AddAt - - wxArray::Insert - - wxArray::SetCount - - WX_APPEND_ARRAY() - - WX_PREPEND_ARRAY() + Default constructor initializes an empty array object. */ - - + wxObjArray(); /** - Preallocates memory for a given number of array elements. It is worth calling - when the number of items which are going to be added to the array is known in - advance because it will save unneeded memory reallocation. If the array already - has enough memory for the given number of items, nothing happens. In any case, - the existing contents of the array is not modified. + There is no default constructor for wxSortedArray classes - you must + initialize it with a function to use for item comparison. It is a + function which is passed two arguments of type @c T where @c T is the + array element type and which should return a negative, zero or positive + value according to whether the first element passed to it is less than, + equal to or greater than the second one. */ - void Alloc(size_t count); + wxSortedArray(int (*)(T first, T second)compareFunction); /** - This function does the same as wxArray::Empty and additionally - frees the memory allocated to the array. + Performs a shallow array copy (i.e. doesn't copy the objects pointed to + even if the source array contains the items of pointer type). */ - void Clear(); - + wxArray(const wxArray& array); /** - Array classes are 100% C++ objects and as such they have the appropriate copy - constructors and assignment operators. Copying wxArray just copies the elements - but copying wxObjArray copies the arrays items. However, for memory-efficiency - sake, neither of these classes has virtual destructor. It is not very important - for wxArray which has trivial destructor anyhow, but it does mean that you - should avoid deleting wxObjArray through a wxBaseArray pointer (as you would - never use wxBaseArray anyhow it shouldn't be a problem) and that you should not - derive your own classes from the array classes. - @ref wxArray::ctordef "wxArray default constructor" - - @ref wxArray::ctorcopy "wxArray copy constructors and assignment operators" - - @ref wxArray::dtor ~wxArray + Performs a shallow array copy (i.e. doesn't copy the objects pointed to + even if the source array contains the items of pointer type). */ + wxSortedArray(const wxSortedArray& array); + /** + Performs a deep copy (i.e. the array element are copied too). + */ + wxObjArray(const wxObjArray& array); - - //@{ /** - (T first, T second)@e compareFunction) - There is no default constructor for wxSortedArray classes - you must initialize - it - with a function to use for item comparison. It is a function which is passed - two arguments of type @e T where @e T is the array element type and which - should return a negative, zero or positive value according to whether the first - element passed to it is less than, equal to or greater than the second one. + Performs a shallow array copy (i.e. doesn't copy the objects pointed to + even if the source array contains the items of pointer type). */ - wxArray(); - wxObjArray(); - wxSortedArray(); - //@} + wxArray& operator=(const wxArray& array); + /** + Performs a shallow array copy (i.e. doesn't copy the objects pointed to + even if the source array contains the items of pointer type). + */ + wxSortedArray& operator=(const wxSortedArray& array); + /** + Performs a deep copy (i.e. the array element are copied too). + */ + wxObjArray& operator=(const wxObjArray& array); /** - Removes the element from the array, but, unlike, - wxArray::Remove doesn't delete it. The function returns the - pointer to the removed element. + This destructor does not delete all the items owned by the array, you + may use the WX_CLEAR_ARRAY() macro for this. */ - T* Detach(size_t index); + ~wxArray(); + /** + This destructor does not delete all the items owned by the array, you + may use the WX_CLEAR_ARRAY() macro for this. + */ + ~wxSortedArray(); + /** + This destructor deletes all the items owned by the array. + */ + ~wxObjArray(); + + //@} + /** - Empties the array. For wxObjArray classes, this destroys all of the array - elements. For wxArray and wxSortedArray this does nothing except marking the - array of being empty - this function does not free the allocated memory, use - wxArray::Clear for this. + @name Memory Management + + Automatic array memory management is quite trivial: the array starts by + preallocating some minimal amount of memory (defined by + @c WX_ARRAY_DEFAULT_INITIAL_SIZE) and when further new items exhaust + already allocated memory it reallocates it adding 50% of the currently + allocated amount, but no more than some maximal number which is defined + by the @c ARRAY_MAXSIZE_INCREMENT constant. Of course, this may lead to + some memory being wasted (@c ARRAY_MAXSIZE_INCREMENT in the worst case, + i.e. 4Kb in the current implementation), so the Shrink() function is + provided to deallocate the extra memory. The Alloc() function can also + be quite useful if you know in advance how many items you are going to + put in the array and will prevent the array code from reallocating the + memory more times than needed. */ - void Empty(); + //@{ /** - Return the number of items in the array. + Preallocates memory for a given number of array elements. It is worth + calling when the number of items which are going to be added to the + array is known in advance because it will save unneeded memory + reallocation. If the array already has enough memory for the given + number of items, nothing happens. In any case, the existing contents of + the array is not modified. */ - size_t GetCount() const; + void Alloc(size_t count); - //@{ /** - The first version of the function is for wxArray and wxObjArray, the second is - for wxSortedArray only. - Searches the element in the array, starting from either beginning or the end - depending on the value of @a searchFromEnd parameter. @c wxNOT_FOUND is - returned if the element is not found, otherwise the index of the element is - returned. - Linear search is used for the wxArray and wxObjArray classes but binary search - in the sorted array is used for wxSortedArray (this is why searchFromEnd - parameter doesn't make sense for it). - @note even for wxObjArray classes, the operator==() of the elements in the - array is @b not used by this function. It searches exactly the given - element in the array and so will only succeed if this element had been - previously added to the array, but fail even if another, identical, element is - in the array. + Frees all memory unused by the array. If the program knows that no new + items will be added to the array it may call Shrink() to reduce its + memory usage. However, if a new item is added to the array, some extra + memory will be allocated again. */ - int Index(T& item, bool searchFromEnd = false) const; - const int Index(T& item) const; + void Shrink(); + //@} + /** - Search for a place to insert @a item into the sorted array (binary search). - The index returned is just before the first existing item that is greater or - equal - (according to the compare function) to the given @e item. - You have to do extra work to know if the @a item already exists in array. - This function is useful in conjunction with - wxArray::AddAt for a common operation - of "insert only if not found". - */ - size_t IndexForInsert(T item) const; + @name Number of Elements and Simple Item Access + Functions in this section return the total number of array elements and + allow to retrieve them - possibly using just the C array indexing [] + operator which does exactly the same as the Item() method. + */ //@{ + /** - Insert the given number of @a copies of the @a item into the array before - the existing item @a n - thus, @e Insert(something, 0u) will insert an - item in such way that it will become the first array element. - wxSortedArray doesn't have this function because inserting in wrong place - would break its sorted condition. - Please see wxArray::Add for explanation of the differences - between the overloaded versions of this function. + Return the number of items in the array. */ - void Insert(T item, size_t n, size_t copies = 1); - void Insert(T* item, size_t n); - void Insert(T& item, size_t n, size_t copies = 1); - //@} + size_t GetCount() const; /** Returns @true if the array is empty, @false otherwise. @@ -325,308 +346,427 @@ public: bool IsEmpty() const; /** - Returns the item at the given position in the array. If @a index is out of - bounds, an assert failure is raised in the debug builds but nothing special is - done in the release build. - The returned value is of type "reference to the array element type" for all of - the array classes. - */ - T Item(size_t index) const; + Returns the item at the given position in the array. If @a index is out + of bounds, an assert failure is raised in the debug builds but nothing + special is done in the release build. - /** - Returns the last element in the array, i.e. is the same as Item(GetCount() - 1). - An assert failure is raised in the debug mode if the array is empty. - The returned value is of type "reference to the array element type" for all of - the array classes. + The returned value is of type "reference to the array element type" for + all of the array classes. */ - T Last() const; + T& Item(size_t index) const; /** - To use an array you must first define the array class. This is done with the - help of the macros in this section. The class of array elements must be (at - least) forward declared for WX_DEFINE_ARRAY, WX_DEFINE_SORTED_ARRAY and - WX_DECLARE_OBJARRAY macros and must be fully declared before you use - WX_DEFINE_OBJARRAY macro. - WX_DEFINE_ARRAY() + Returns the last element in the array, i.e. is the same as calling + "Item(GetCount() - 1)". An assert failure is raised in the debug mode + if the array is empty. - WX_DEFINE_EXPORTED_ARRAY() + The returned value is of type "reference to the array element type" for + all of the array classes. + */ + T& Last() const; - WX_DEFINE_USER_EXPORTED_ARRAY() + //@} - WX_DEFINE_SORTED_ARRAY() - WX_DEFINE_SORTED_EXPORTED_ARRAY() + /** + @name Adding Items + */ + //@{ - WX_DEFINE_SORTED_USER_EXPORTED_ARRAY() + /** + Appends the given number of @a copies of the @a item to the array + consisting of the elements of type @c T. - WX_DECLARE_EXPORTED_OBJARRAY() + This version is used with wxArray. - WX_DECLARE_USER_EXPORTED_OBJARRAY() + You may also use WX_APPEND_ARRAY() macro to append all elements of one + array to another one but it is more efficient to use the @a copies + parameter and modify the elements in place later if you plan to append + a lot of items. + */ + void Add(T item, size_t copies = 1); + /** + Appends the @a item to the array consisting of the elements of type + @c T. - WX_DEFINE_OBJARRAY() + This version is used with wxSortedArray, returning the index where + @a item is stored. + */ + size_t Add(T item); + /** + Appends the @a item to the array consisting of the elements of type + @c T. + + This version is used with wxObjArray. The array will take ownership of + the @item, deleting it when the item is deleted from the array. Note + that you cannot append more than one pointer as reusing it would lead + to deleting it twice (or more) resulting in a crash. + + You may also use WX_APPEND_ARRAY() macro to append all elements of one + array to another one but it is more efficient to use the @a copies + parameter and modify the elements in place later if you plan to append + a lot of items. + */ + void Add(T* item); + /** + Appends the given number of @a copies of the @a item to the array + consisting of the elements of type @c T. - WX_DEFINE_EXPORTED_OBJARRAY() + This version is used with wxObjArray. The array will make a copy of the + item and will not take ownership of the original item. - WX_DEFINE_USER_EXPORTED_OBJARRAY() - To slightly complicate the matters even further, the operator - defined by - default for the array iterators by these macros only makes sense if the array - element type is not a pointer itself and, although it still works, this - provokes warnings from some compilers and to avoid them you should use the - @c _PTR versions of the macros above. For example, to define an array of - pointers to @c double you should use: + You may also use WX_APPEND_ARRAY() macro to append all elements of one + array to another one but it is more efficient to use the @a copies + parameter and modify the elements in place later if you plan to append + a lot of items. + */ + void Add(T& item, size_t copies = 1); - Note that the above macros are generally only useful for - wxObject types. There are separate macros for declaring an array of a simple - type, - such as an int. - The following simple types are supported: + /** + Inserts the given @a item into the array in the specified @e index + position. - int + Be aware that you will set out the order of the array if you give a + wrong position. - long + This function is useful in conjunction with IndexForInsert() for a + common operation of "insert only if not found". + */ + void AddAt(T item, size_t index); - size_t + /** + Insert the given number of @a copies of the @a item into the array + before the existing item @a n - thus, @e Insert(something, 0u) will + insert an item in such way that it will become the first array element. - double - To create an array of a simple type, simply append the type you want in CAPS to - the array definition. - For example, for an integer array, you'd use one of the following variants: - WX_DEFINE_ARRAY_INT() + wxSortedArray doesn't have this function because inserting in wrong + place would break its sorted condition. - WX_DEFINE_EXPORTED_ARRAY_INT() + Please see Add() for an explanation of the differences between the + overloaded versions of this function. + */ + void Insert(T item, size_t n, size_t copies = 1); + /** + Insert the @a item into the array before the existing item @a n - thus, + @e Insert(something, 0u) will insert an item in such way that it will + become the first array element. - WX_DEFINE_USER_EXPORTED_ARRAY_INT() + wxSortedArray doesn't have this function because inserting in wrong + place would break its sorted condition. - WX_DEFINE_SORTED_ARRAY_INT() + Please see Add() for an explanation of the differences between the + overloaded versions of this function. + */ + void Insert(T* item, size_t n); + /** + Insert the given number of @a copies of the @a item into the array + before the existing item @a n - thus, @e Insert(something, 0u) will + insert an item in such way that it will become the first array element. - WX_DEFINE_SORTED_EXPORTED_ARRAY_INT() + wxSortedArray doesn't have this function because inserting in wrong + place would break its sorted condition. - WX_DEFINE_SORTED_USER_EXPORTED_ARRAY_INT() + Please see Add() for an explanation of the differences between the + overloaded versions of this function. */ - + void Insert(T& item, size_t n, size_t copies = 1); /** - Automatic array memory management is quite trivial: the array starts by - preallocating some minimal amount of memory (defined by - WX_ARRAY_DEFAULT_INITIAL_SIZE) and when further new items exhaust already - allocated memory it reallocates it adding 50% of the currently allocated - amount, but no more than some maximal number which is defined by - ARRAY_MAXSIZE_INCREMENT constant. Of course, this may lead to some memory - being wasted (ARRAY_MAXSIZE_INCREMENT in the worst case, i.e. 4Kb in the - current implementation), so the wxArray::Shrink function is - provided to deallocate the extra memory. The wxArray::Alloc - function can also be quite useful if you know in advance how many items you are - going to put in the array and will prevent the array code from reallocating the - memory more times than needed. - wxArray::Alloc + This function ensures that the number of array elements is at least + @a count. If the array has already @a count or more items, nothing is + done. Otherwise, @a count - GetCount() elements are added and + initialized to the value @a defval. - wxArray::Shrink + @see GetCount() */ + void SetCount(size_t count, T defval = T(0)); + //@} - /** - Functions in this section return the total number of array elements and allow to - retrieve them - possibly using just the C array indexing [] operator which - does exactly the same as wxArray::Item method. - wxArray::GetCount - wxArray::IsEmpty + /** + @name Removing Items + */ + //@{ - wxArray::Item + /** + This function does the same as Empty() and additionally frees the + memory allocated to the array. + */ + void Clear(); - wxArray::Last + /** + Removes the element from the array, but unlike Remove(), it doesn't + delete it. The function returns the pointer to the removed element. */ + T* Detach(size_t index); + /** + Empties the array. For wxObjArray classes, this destroys all of the + array elements. For wxArray and wxSortedArray this does nothing except + marking the array of being empty - this function does not free the + allocated memory, use Clear() for this. + */ + void Empty(); /** - Removes an element from the array by value: the first item of the - array equal to @a item is removed, an assert failure will result from an + Removes an element from the array by value: the first item of the array + equal to @a item is removed, an assert failure will result from an attempt to remove an item which doesn't exist in the array. - When an element is removed from wxObjArray it is deleted by the array - use - Detach() if you don't want this to happen. On the - other hand, when an object is removed from a wxArray nothing happens - you - should delete it manually if required: - See also WX_CLEAR_ARRAY() macro which deletes all - elements of a wxArray (supposed to contain pointers). + When an element is removed from wxObjArray it is deleted by the array - + use Detach() if you don't want this to happen. On the other hand, when + an object is removed from a wxArray nothing happens - you should delete + it manually if required: + + @code + T *item = array[n]; + delete item; + array.Remove(n); + @endcode + + See also WX_CLEAR_ARRAY() macro which deletes all elements of a wxArray + (supposed to contain pointers). */ Remove(T item); /** Removes @a count elements starting at @a index from the array. When an element is removed from wxObjArray it is deleted by the array - use - Detach() if you don't want this to happen. On - the other hand, when an object is removed from a wxArray nothing happens - - you should delete it manually if required: - - See also WX_CLEAR_ARRAY() macro which deletes all - elements of a wxArray (supposed to contain pointers). + Detach() if you don't want this to happen. On the other hand, when an + object is removed from a wxArray nothing happens - you should delete it + manually if required: + + @code + T *item = array[n]; + delete item; + array.RemoveAt(n); + @endcode + + See also WX_CLEAR_ARRAY() macro which deletes all elements of a wxArray + (supposed to contain pointers). */ RemoveAt(size_t index, size_t count = 1); - /** - WX_CLEAR_ARRAY() - - wxArray::Empty + //@} - wxArray::Clear - wxArray::RemoveAt + /** + @name Searching and Sorting + */ + //@{ - wxArray::Remove + /** + This version of Index() is for wxArray and wxObjArray only. + + Searches the element in the array, starting from either beginning or + the end depending on the value of @a searchFromEnd parameter. + @c wxNOT_FOUND is returned if the element is not found, otherwise the + index of the element is returned. + + @note Even for wxObjArray classes, the operator "==" of the elements in + the array is @b not used by this function. It searches exactly + the given element in the array and so will only succeed if this + element had been previously added to the array, but fail even if + another, identical, element is in the array. */ + int Index(T& item, bool searchFromEnd = false) const; + /** + This version of Index() is for wxSortedArray only. + Searches the element in the array, starting from either beginning or + the end depending on the value of @a searchFromEnd parameter. + @c wxNOT_FOUND is returned if the element is not found, otherwise the + index of the element is returned. + */ + const int Index(T& item) const; /** - wxArray::Index + Search for a place to insert @a item into the sorted array (binary + search). The index returned is just before the first existing item that + is greater or equal (according to the compare function) to the given + @a item. - wxArray::IndexForInsert + You have to do extra work to know if the @a item already exists in + array. - wxArray::Sort + This function is useful in conjunction with AddAt() for a common + operation of "insert only if not found". */ - + size_t IndexForInsert(T item) const; /** - ) - This function ensures that the number of array elements is at least - @e count. If the array has already @a count or more items, nothing is - done. Otherwise, @c count - GetCount() elements are added and initialized to - the value @e defval. + The notation @c "CMPFUNCT" should be read as if we had the following + declaration: - @see wxArray::GetCount - */ - void SetCount(size_t count); + @code + template int CMPFUNC(T *first, T *second); + @endcode - /** - Frees all memory unused by the array. If the program knows that no new items - will be added to the array it may call Shrink() to reduce its memory usage. - However, if a new item is added to the array, some extra memory will be - allocated again. - */ - void Shrink(); + Where @e T is the type of the array elements. I.e. it is a function + returning @e int which is passed two arguments of type @e T*. - /** - The notation CMPFUNCT should be read as if we had the following declaration: + Sorts the array using the specified compare function: this function + should return a negative, zero or positive value according to whether + the first element passed to it is less than, equal to or greater than + the second one. - where @e T is the type of the array elements. I.e. it is a function returning - @e int which is passed two arguments of type @e T *. - Sorts the array using the specified compare function: this function should - return a negative, zero or positive value according to whether the first element - passed to it is less than, equal to or greater than the second one. wxSortedArray doesn't have this function because it is always sorted. */ void Sort(CMPFUNC compareFunction); - //@{ - /** - The copy constructors and assignment operators perform a shallow array copy - (i.e. they don't copy the objects pointed to even if the source array contains - the items of pointer type) for wxArray and wxSortedArray and a deep copy (i.e. - the array element are copied too) for wxObjArray. - */ - wxArray(const wxArray& array); - wxSortedArray(const wxSortedArray& array); - wxObjArray(const wxObjArray& array); - wxArray operator=(const wxArray& array); - wxSortedArray operator=(const wxSortedArray& array); - wxObjArray operator=(const wxObjArray& array); - //@} - - //@{ - /** - The wxObjArray destructor deletes all the items owned by the array. This is not - done by wxArray and wxSortedArray versions - you may use - WX_CLEAR_ARRAY() macro for this. - */ - ~wxArray(); - ~wxSortedArray(); - ~wxObjArray(); //@} }; /** This macro may be used to append all elements of the @a other array to the - @e array. The two arrays must be of the same type. + @a array. The two arrays must be of the same type. */ -#define WX_APPEND_ARRAY(wxArray& array, wxArray& other) /* implementation is private */ +#define WX_APPEND_ARRAY(wxArray& array, wxArray& other) /** - This macro may be used to delete all elements of the array before emptying it. - It can not be used with wxObjArrays - but they will delete their elements anyhow - when you call Empty(). + This macro may be used to delete all elements of the array before emptying + it. It can not be used with wxObjArrays - but they will delete their + elements anyway when you call Empty(). */ -#define WX_CLEAR_ARRAY(wxArray& array) /* implementation is private */ +#define WX_CLEAR_ARRAY(wxArray& array) //@{ /** This macro declares a new object array class named @a name and containing - the elements of type @e T. The second form is used when compiling wxWidgets as - a DLL under Windows and array needs to be visible outside the DLL. The third is + the elements of type @e T. + + An exported array is used when compiling wxWidgets as a DLL under Windows + and the array needs to be visible outside the DLL. An user exported array needed for exporting an array from a user DLL. + Example: - You must use WX_DEFINE_OBJARRAY() macro to define - the array class - otherwise you would get link errors. + @code + class MyClass; + WX_DECLARE_OBJARRAY(MyClass, wxArrayOfMyClass); // note: not "MyClass *"! + @endcode + + You must use WX_DEFINE_OBJARRAY() macro to define the array class, + otherwise you would get link errors. */ -#define WX_DECLARE_OBJARRAY(T, name) /* implementation is private */ -#define WX_DECLARE_EXPORTED_OBJARRAY(T, name) /* implementation is private */ -#define WX_DECLARE_USER_EXPORTED_OBJARRAY(T, name) /* implementation is private */ +#define WX_DECLARE_OBJARRAY(T, name) +#define WX_DECLARE_EXPORTED_OBJARRAY(T, name) +#define WX_DECLARE_USER_EXPORTED_OBJARRAY(T, name) //@} //@{ /** This macro defines a new array class named @a name and containing the - elements of type @e T. The second form is used when compiling wxWidgets as - a DLL under Windows and array needs to be visible outside the DLL. The third is + elements of type @a T. + + An exported array is used when compiling wxWidgets as a DLL under Windows + and the array needs to be visible outside the DLL. An user exported array needed for exporting an array from a user DLL. + Example: - Note that wxWidgets predefines the following standard array classes: @b - wxArrayInt, - @b wxArrayLong, @b wxArrayShort, @b wxArrayDouble, @b wxArrayPtrVoid. + @code + WX_DEFINE_ARRAY_INT(int, MyArrayInt); + + class MyClass; + WX_DEFINE_ARRAY(MyClass *, ArrayOfMyClass); + @endcode + + Note that wxWidgets predefines the following standard array classes: + @b wxArrayInt, @b wxArrayLong, @b wxArrayShort, @b wxArrayDouble, + @b wxArrayPtrVoid. */ -#define WX_DEFINE_ARRAY(T, name) /* implementation is private */ -#define WX_DEFINE_EXPORTED_ARRAY(T, name) /* implementation is private */ -#define WX_DEFINE_USER_EXPORTED_ARRAY(T, name, exportspec) /* implementation is private */ +#define WX_DEFINE_ARRAY(T, name) +#define WX_DEFINE_EXPORTED_ARRAY(T, name) +#define WX_DEFINE_USER_EXPORTED_ARRAY(T, name, exportspec) //@} //@{ /** - This macro defines the methods of the array class @a name not defined by the - WX_DECLARE_OBJARRAY() macro. You must include the - file wx/arrimpl.cpp before using this macro and you must have the full - declaration of the class of array elements in scope! If you forget to do the - first, the error will be caught by the compiler, but, unfortunately, many - compilers will not give any warnings if you forget to do the second - but the - objects of the class will not be copied correctly and their real destructor will - not be called. The latter two forms are merely aliases of the first to satisfy - some people's sense of symmetry when using the exported declarations. + This macro defines the methods of the array class @a name not defined by + the WX_DECLARE_OBJARRAY() macro. You must include the file + @ before using this macro and you must have the full + declaration of the class of array elements in scope! If you forget to do + the first, the error will be caught by the compiler, but, unfortunately, + many compilers will not give any warnings if you forget to do the second - + but the objects of the class will not be copied correctly and their real + destructor will not be called. + + An exported array is used when compiling wxWidgets as a DLL under Windows + and the array needs to be visible outside the DLL. An user exported array + needed for exporting an array from a user DLL. + Example of usage: + + @code + // first declare the class! + class MyClass + { + public: + MyClass(const MyClass&); + + // ... + + virtual ~MyClass(); + }; + + #include + WX_DEFINE_OBJARRAY(wxArrayOfMyClass); + @endcode */ -#define WX_DEFINE_OBJARRAY(name) /* implementation is private */ -#define WX_DEFINE_EXPORTED_OBJARRAY(name) /* implementation is private */ -#define WX_DEFINE_USER_EXPORTED_OBJARRAY(name) /* implementation is private */ +#define WX_DEFINE_OBJARRAY(name) +#define WX_DEFINE_EXPORTED_OBJARRAY(name) +#define WX_DEFINE_USER_EXPORTED_OBJARRAY(name) //@} //@{ /** This macro defines a new sorted array class named @a name and containing - the elements of type @e T. The second form is used when compiling wxWidgets as - a DLL under Windows and array needs to be visible outside the DLL. The third is + the elements of type @e T. + + An exported array is used when compiling wxWidgets as a DLL under Windows + and the array needs to be visible outside the DLL. An user exported array needed for exporting an array from a user DLL. + Example: - You will have to initialize the objects of this class by passing a comparison - function to the array object constructor like this: + @code + WX_DEFINE_SORTED_ARRAY_INT(int, MySortedArrayInt); + + class MyClass; + WX_DEFINE_SORTED_ARRAY(MyClass *, ArrayOfMyClass); + @endcode + + You will have to initialize the objects of this class by passing a + comparison function to the array object constructor like this: + + @code + int CompareInts(int n1, int n2) + { + return n1 - n2; + } + + MySortedArrayInt sorted(CompareInts); + + int CompareMyClassObjects(MyClass *item1, MyClass *item2) + { + // sort the items by their address... + return Stricmp(item1->GetAddress(), item2->GetAddress()); + } + + ArrayOfMyClass another(CompareMyClassObjects); + @endcode */ -#define WX_DEFINE_SORTED_ARRAY(T, name) /* implementation is private */ -#define WX_DEFINE_SORTED_EXPORTED_ARRAY(T, name) /* implementation is private */ -#define WX_DEFINE_SORTED_USER_EXPORTED_ARRAY(T, name) /* implementation is private */ +#define WX_DEFINE_SORTED_ARRAY(T, name) +#define WX_DEFINE_SORTED_EXPORTED_ARRAY(T, name) +#define WX_DEFINE_SORTED_USER_EXPORTED_ARRAY(T, name) //@} /** This macro may be used to prepend all elements of the @a other array to the - @e array. The two arrays must be of the same type. + @a array. The two arrays must be of the same type. */ -#define WX_PREPEND_ARRAY(wxArray& array, wxArray& other) /* implementation is private */ +#define WX_PREPEND_ARRAY(wxArray& array, wxArray& other) + diff --git a/interface/dynlib.h b/interface/dynlib.h index 2ca0305177..989cc9dd95 100644 --- a/interface/dynlib.h +++ b/interface/dynlib.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: dynlib.h -// Purpose: interface of wxDynamicLibraryDetails +// Purpose: interface of wxDynamicLibrary and wxDynamicLibraryDetails // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -10,14 +10,14 @@ @class wxDynamicLibraryDetails @wxheader{dynlib.h} - This class is used for the objects returned by - wxDynamicLibrary::ListLoaded method and - contains the information about a single module loaded into the address space of - the current process. A module in this context may be either a dynamic library - or the main program itself. + This class is used for the objects returned by the + wxDynamicLibrary::ListLoaded() method and contains the information about a + single module loaded into the address space of the current process. A + module in this context may be either a dynamic library or the main program + itself. @library{wxbase} - @category{FIXME} + @category{appmanagement} */ class wxDynamicLibraryDetails { @@ -26,33 +26,32 @@ public: Retrieves the load address and the size of this module. @param addr - the pointer to the location to return load address in, may be - @NULL + The pointer to the location to return load address in, may be + @NULL. @param len - pointer to the location to return the size of this module in - memory in, may be @NULL + Pointer to the location to return the size of this module in + memory in, may be @NULL. - @returns @true if the load address and module size were retrieved, @false - if this information is not available. + @returns @true if the load address and module size were retrieved, + @false if this information is not available. */ bool GetAddress(void** addr, size_t len) const; /** - Returns the base name of this module, e.g. @c kernel32.dll or - @c libc-2.3.2.so. + Returns the base name of this module, e.g. @c "kernel32.dll" or + @c "libc-2.3.2.so". */ wxString GetName() const; /** Returns the full path of this module if available, e.g. - @c c:\windows\system32\kernel32.dll or - @c /lib/libc-2.3.2.so. + @c "c:\windows\system32\kernel32.dll" or @c "/lib/libc-2.3.2.so". */ wxString GetPath() const; /** - Returns the version of this module, e.g. @c 5.2.3790.0 or - @c 2.3.2. The returned string is empty if the version information is not + Returns the version of this module, e.g. @c "5.2.3790.0" or @c "2.3.2". + The returned string is empty if the version information is not available. */ wxString GetVersion() const; @@ -61,131 +60,23 @@ public: /** - @class wxDllLoader - @wxheader{dynlib.h} - - @b Deprecation note: This class is deprecated since version 2.4 and is - not compiled in by default in version 2.6 and will be removed in 2.8. Please - use wxDynamicLibrary instead. - - wxDllLoader is a class providing an interface similar to Unix's @c dlopen(). It - is used by the wxLibrary framework and manages the actual - loading of shared libraries and the resolving of symbols in them. There are no - instances of this class, it simply serves as a namespace for its static member - functions. - - Please note that class wxDynamicLibrary provides - alternative, friendlier interface to wxDllLoader. - - The terms @e DLL and @e shared library/object will both be used in the - documentation to refer to the same thing: a @c .dll file under Windows or - @c .so or @c .sl one under Unix. - - Example of using this class to dynamically load the @c strlen() function: - - @code - #if defined(__WXMSW__) - static const wxChar *LIB_NAME = _T("kernel32"); - static const wxChar *FUNC_NAME = _T("lstrlenA"); - #elif defined(__UNIX__) - static const wxChar *LIB_NAME = _T("/lib/libc-2.0.7.so"); - static const wxChar *FUNC_NAME = _T("strlen"); - #endif - - wxDllType dllHandle = wxDllLoader::LoadLibrary(LIB_NAME); - if ( !dllHandle ) - { - ... error ... - } - else - { - typedef int (*strlenType)(char *); - strlenType pfnStrlen = (strlenType)wxDllLoader::GetSymbol(dllHandle, - FUNC_NAME); - if ( !pfnStrlen ) - { - ... error ... - } - else - { - if ( pfnStrlen("foo") != 3 ) - { - ... error ... - } - else - { - ... ok! ... - } - } - - wxDllLoader::UnloadLibrary(dllHandle); - } - @endcode - - @library{wxbase} - @category{appmanagement} + Dynamic library category used with wxDynamicLibrary::CanonicalizeName(). */ -class wxDllLoader +enum wxDynamicLibraryCategory { -public: - /** - Returns the string containing the usual extension for shared libraries for the - given systems (including the leading dot if not empty). - For example, this function will return @c ".dll" under Windows or (usually) - @c ".so" under Unix. - */ - static wxString GetDllExt(); - - /** - This function returns a valid handle for the main program itself. Notice that - the @NULL return value is valid for some systems (i.e. doesn't mean that - the function failed). - @note This function is Unix specific. It will always fail under Windows - or OS/2. - */ - wxDllType GetProgramHandle(); - - /** - This function resolves a symbol in a loaded DLL, such as a variable or - function name. - Returned value will be @NULL if the symbol was not found in the DLL or if - an error occurred. - - @param dllHandle - Valid handle previously returned by - LoadLibrary - @param name - Name of the symbol. - */ - void* GetSymbol(wxDllType dllHandle, const wxString& name); - - /** - This function loads a shared library into memory, with @a libname being the - name of the library: it may be either the full name including path and - (platform-dependent) extension, just the basename (no path and no extension) - or a basename with extension. In the last two cases, the library will be - searched in all standard locations. - Returns a handle to the loaded DLL. Use @a success parameter to test if it - is valid. If the handle is valid, the library must be unloaded later with - UnloadLibrary(). - - @param libname - Name of the shared object to load. - @param success - May point to a bool variable which will be set to @true or - @false; may also be @NULL. - */ - wxDllType LoadLibrary(const wxString& libname, - bool* success = NULL); - - /** - This function unloads the shared library. The handle @a dllhandle must have - been returned by LoadLibrary() previously. - */ - void UnloadLibrary(wxDllType dllhandle); + wxDL_LIBRARY, ///< Standard library. + wxDL_MODULE ///< Loadable module/plugin. }; - +/** + Dynamic library plugin category used with + wxDynamicLibrary::CanonicalizePluginName(). +*/ +enum wxPluginCategory +{ + wxDL_PLUGIN_GUI, ///< Plugin that uses GUI classes. + wxDL_PLUGIN_BASE ///< wxBase-only plugin. +}; /** @class wxDynamicLibrary @@ -193,40 +84,46 @@ public: wxDynamicLibrary is a class representing dynamically loadable library (Windows DLL, shared library under Unix etc.). Just create an object of - this class to load a library and don't worry about unloading it -- it will be - done in the objects destructor automatically. + this class to load a library and don't worry about unloading it -- it will + be done in the objects destructor automatically. + + The following flags can be used with wxDynamicLibrary() or Load(): + + @beginStyleTable + @style{wxDL_LAZY} + Equivalent of RTLD_LAZY under Unix, ignored elsewhere. + @style{wxDL_NOW} + Equivalent of RTLD_NOW under Unix, ignored elsewhere. + @style{wxDL_GLOBAL} + Equivalent of RTLD_GLOBAL under Unix, ignored elsewhere. + @style{wxDL_VERBATIM} + Don't try to append the appropriate extension to the library name + (this is done by default). + @style{wxDL_DEFAULT} + Default flags, same as wxDL_NOW currently. + @style{wxDL_QUIET} + Don't log an error message if the library couldn't be loaded. + @endStyleTable @library{wxbase} - @category{FIXME} - - @see wxDynamicLibrary::CanonicalizePluginName + @category{appmanagement} */ class wxDynamicLibrary { public: - //@{ /** - Constructor. Second form calls Load(). + Default constructor. */ wxDynamicLibrary(); - wxDynamicLibrary(const wxString& name, - int flags = wxDL_DEFAULT); - //@} - /** - Returns the platform-specific full name for the library called @e name. E.g. - it adds a @c ".dll" extension under Windows and @c "lib" prefix and - @c ".so", @c ".sl" or maybe @c ".dylib" extension under Unix. - The possible values for @a cat are: - - - wxDL_LIBRARY - - normal library - - wxDL_MODULE + Constructor. Calls Load() with the given @a name. + */ + wxDynamicLibrary(const wxString& name, int flags = wxDL_DEFAULT); - a loadable module or plugin + /** + Returns the platform-specific full name for the library called @a name. + E.g. it adds a @c ".dll" extension under Windows and @c "lib" prefix + and @c ".so", @c ".sl" or @c ".dylib" extension under Unix. @see CanonicalizePluginName() */ @@ -234,29 +131,18 @@ public: wxDynamicLibraryCategory cat = wxDL_LIBRARY); /** - This function does the same thing as - CanonicalizeName() but for wxWidgets - plugins. The only difference is that compiler and version information are added - to the name to ensure that the plugin which is going to be loaded will be - compatible with the main program. - The possible values for @a cat are: - - - wxDL_PLUGIN_GUI - - plugin which uses GUI classes (default) - - wxDL_PLUGIN_BASE - - plugin which only uses wxBase + This function does the same thing as CanonicalizeName() but for + wxWidgets plugins. The only difference is that compiler and version + information are added to the name to ensure that the plugin which is + going to be loaded will be compatible with the main program. */ static wxString CanonicalizePluginName(const wxString& name, wxPluginCategory cat = wxDL_PLUGIN_GUI); /** - Detaches this object from its library handle, i.e. the object will not unload - the library any longer in its destructor but it is now the callers - responsibility to do this using Unload(). + Detaches this object from its library handle, i.e. the object will not + unload the library any longer in its destructor but it is now the + callers responsibility to do this using Unload(). */ wxDllType Detach(); @@ -267,8 +153,8 @@ public: static wxDllType GetProgramHandle(); /** - Returns pointer to symbol @a name in the library or @NULL if the library - contains no such symbol. + Returns pointer to symbol @a name in the library or @NULL if the + library contains no such symbol. @see wxDYNLIB_FUNCTION() */ @@ -276,19 +162,19 @@ public: /** This function is available only under Windows as it is only useful when - dynamically loading symbols from standard Windows DLLs. Such functions have - either @c 'A' (in ANSI build) or @c 'W' (in Unicode, or wide - character build) suffix if they take string parameters. Using this function you - can use just the base name of the function and the correct suffix is appende - automatically depending on the current build. Otherwise, this method is - identical to GetSymbol(). + dynamically loading symbols from standard Windows DLLs. Such functions + have either @c 'A' (in ANSI build) or @c 'W' (in Unicode, or wide + character build) suffix if they take string parameters. Using this + function, you can use just the base name of the function and the + correct suffix is appended automatically depending on the current + build. Otherwise, this method is identical to GetSymbol(). */ void* GetSymbolAorW(const wxString& name) const; /** - Returns @true if the symbol with the given @a name is present in the dynamic - library, @false otherwise. Unlike GetSymbol(), - this function doesn't log an error message if the symbol is not found. + Returns @true if the symbol with the given @a name is present in the + dynamic library, @false otherwise. Unlike GetSymbol(), this function + doesn't log an error message if the symbol is not found. @since 2.5.4 */ @@ -300,61 +186,41 @@ public: bool IsLoaded() const; /** - This static method returns an array() containing the details - of all modules loaded into the address space of the current project, the array - elements are object of @c wxDynamicLibraryDetails class. The array will - be empty if an error occurred. - This method is currently implemented only under Win32 and Linux and is useful - mostly for diagnostics purposes. + This static method returns a wxArray containing the details of all + modules loaded into the address space of the current project. The array + elements are objects of the type: wxDynamicLibraryDetails. The array + will be empty if an error occurred. + + This method is currently implemented only under Win32 and Linux and is + useful mostly for diagnostics purposes. */ static wxDynamicLibraryDetailsArray ListLoaded(); /** Loads DLL with the given @a name into memory. The @a flags argument can - be a combination of the following bits: - - wxDL_LAZY - - equivalent of RTLD_LAZY under Unix, ignored elsewhere - - wxDL_NOW - - equivalent of RTLD_NOW under Unix, ignored elsewhere - - wxDL_GLOBAL - - equivalent of RTLD_GLOBAL under Unix, ignored elsewhere - - wxDL_VERBATIM - - don't try to append the appropriate extension to - the library name (this is done by default). - - wxDL_DEFAULT - - default flags, same as wxDL_NOW currently - - wxDL_QUIET - - don't log an error message if the library couldn't be - loaded. + be a combination of the styles outlined in the class description. Returns @true if the library was successfully loaded, @false otherwise. */ bool Load(const wxString& name, int flags = wxDL_DEFAULT); - //@{ /** - Unloads the library from memory. wxDynamicLibrary object automatically calls - this method from its destructor if it had been successfully loaded. - The second version is only used if you need to keep the library in memory - during a longer period of time than the scope of the wxDynamicLibrary object. - In this case you may call Detach() and store - the handle somewhere and call this static method later to unload it. + Unloads the library from memory. wxDynamicLibrary object automatically + calls this method from its destructor if it had been successfully + loaded. */ void Unload(); + /** + Unloads the library from memory. wxDynamicLibrary object automatically + calls this method from its destructor if it had been successfully + loaded. + + This version of Unload() is only used if you need to keep the library + in memory during a longer period of time than the scope of the + wxDynamicLibrary object. In this case you may call Detach() and store + the handle somewhere and call this static method later to unload it. + */ static void Unload(wxDllType handle); - //@} }; -- 2.47.2