From: Francesco Montorsi Date: Mon, 3 Nov 2008 14:37:14 +0000 (+0000) Subject: remaining h* interface header revision X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/9cc56d1fc0b8eec41fbe2b961965e67c598d9406?ds=inline remaining h* interface header revision git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56662 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/interface/wx/hash.h b/interface/wx/hash.h index 5563b15945..b14e32f539 100644 --- a/interface/wx/hash.h +++ b/interface/wx/hash.h @@ -9,12 +9,38 @@ /** @class wxHashTable - @b Please note that this class is retained for backward compatibility + @deprecated + Please note that this class is retained for backward compatibility reasons; you should use wxHashMap. This class provides hash table functionality for wxWidgets, and for an - application if it wishes. Data can be hashed on an integer or string - key. + application if it wishes. Data can be hashed on an integer or string key. + + Example: + @code + wxHashTable table(wxKEY_STRING); + + wxPoint *point = new wxPoint(100, 200); + table.Put("point 1", point); + + .... + + wxPoint *found_point = (wxPoint *)table.Get("point 1"); + @endcode + + A hash table is implemented as an array of pointers to lists. + When no data has been stored, the hash table takes only a little more space + than this array (default size is 1000). When a data item is added, an integer + is constructed from the integer or string key that is within the bounds of the array. + If the array element is @NULL, a new (keyed) list is created for the element. + Then the data object is appended to the list, storing the key in case other + data objects need to be stored in the list also (when a 'collision' occurs). + + Retrieval involves recalculating the array index from the key, and searching + along the keyed list for the data object whose stored key matches the passed key. + Obviously this is quicker when there are fewer collisions, so hashing will + become inefficient if the number of items to be stored greatly exceeds the + size of the hash table. @library{wxbase} @category{containers} @@ -36,9 +62,9 @@ public: virtual ~wxHashTable(); /** - The counterpart of @e Next. If the application wishes to iterate - through all the data in the hash table, it can call @e BeginFind and - then loop on @e Next. + The counterpart of Next(). If the application wishes to iterate + through all the data in the hash table, it can call BeginFind() and + then loop on Next(). */ void BeginFind(); @@ -56,16 +82,15 @@ public: //@} /** - If set to @true data stored in hash table will be deleted when hash table object - is destroyed. + If set to @true data stored in hash table will be deleted when hash table + object is destroyed. */ void DeleteContents(bool flag); //@{ /** - Gets data from the hash table, using an integer or string key (depending on - which - has table constructor was used). + Gets data from the hash table, using an integer or string key + (depending on which has table constructor was used). */ wxObject* Get(long key); wxObject* Get(const char* key); @@ -84,20 +109,20 @@ public: /** If the application wishes to iterate through all the data in the hash - table, it can call @e BeginFind and then loop on @e Next. This function - returns a @b Node() pointer (or @NULL if there are no more nodes). + table, it can call BeginFind() and then loop on Next(). This function + returns a @b wxHashTable::Node pointer (or @NULL if there are no more nodes). + The return value is functionally equivalent to @b wxNode but might not be implemented as a @b wxNode. The user will probably only wish to use the - @b GetData method to retrieve the data; the node may also be deleted. + wxNode::GetData() method to retrieve the data; the node may also be deleted. */ wxHashTable::Node* Next(); //@{ /** Inserts data into the hash table, using an integer or string key (depending on - which - has table constructor was used). The key string is copied and stored by the hash - table implementation. + which has table constructor was used). + The key string is copied and stored by the hash table implementation. */ void Put(long key, wxObject* object); void Put(const char* key, wxObject* object); diff --git a/interface/wx/hashmap.h b/interface/wx/hashmap.h index 08f5adf9ff..6a61c80520 100644 --- a/interface/wx/hashmap.h +++ b/interface/wx/hashmap.h @@ -10,31 +10,171 @@ @class wxHashMap This is a simple, type-safe, and reasonably efficient hash map class, - whose interface is a subset of the interface of STL containers. In - particular, the interface is modeled after std::map, and the various, + whose interface is a subset of the interface of STL containers. + In particular, the interface is modeled after std::map, and the various, non-standard, std::hash_map. + Example: + @code + class MyClass { ... }; + + // declare a hash map with string keys and int values + WX_DECLARE_STRING_HASH_MAP( int, MyHash5 ); + // same, with int keys and MyClass* values + WX_DECLARE_HASH_MAP( int, MyClass*, wxIntegerHash, wxIntegerEqual, MyHash1 ); + // same, with wxString keys and int values + WX_DECLARE_STRING_HASH_MAP( int, MyHash3 ); + // same, with wxString keys and values + WX_DECLARE_STRING_HASH_MAP( wxString, MyHash2 ); + + MyHash1 h1; + MyHash2 h2; + + // store and retrieve values + h1[1] = new MyClass( 1 ); + h1[10000000] = NULL; + h1[50000] = new MyClass( 2 ); + h2["Bill"] = "ABC"; + wxString tmp = h2["Bill"]; + // since element with key "Joe" is not present, this will return + // the default value, which is an empty string in the case of wxString + MyClass tmp2 = h2["Joe"]; + + // iterate over all the elements in the class + MyHash2::iterator it; + for( it = h2.begin(); it != h2.end(); ++it ) + { + wxString key = it->first, value = it->second; + // do something useful with key and value + } + @endcode + + + @section hashmap_declaringnew Declaring new hash table types + + @code + WX_DECLARE_STRING_HASH_MAP( VALUE_T, // type of the values + CLASSNAME ); // name of the class + @endcode + Declares a hash map class named CLASSNAME, with wxString keys and VALUE_T values. + + @code + WX_DECLARE_VOIDPTR_HASH_MAP( VALUE_T, // type of the values + CLASSNAME ); // name of the class + @endcode + Declares a hash map class named CLASSNAME, with void* keys and VALUE_T values. + + @code + WX_DECLARE_HASH_MAP( KEY_T, // type of the keys + VALUE_T, // type of the values + HASH_T, // hasher + KEY_EQ_T, // key equality predicate + CLASSNAME); // name of the class + @endcode + The HASH_T and KEY_EQ_T are the types used for the hashing function and + key comparison. wxWidgets provides three predefined hashing functions: + wxIntegerHash for integer types ( int, long, short, and their unsigned counterparts ), + wxStringHash for strings ( wxString, wxChar*, char* ), and wxPointerHash for + any kind of pointer. + Similarly three equality predicates: wxIntegerEqual, wxStringEqual, + wxPointerEqual are provided. + Using this you could declare a hash map mapping int values to wxString like this: + + @code + WX_DECLARE_HASH_MAP( int, + wxString, + wxIntegerHash, + wxIntegerEqual, + MyHash ); + + // using an user-defined class for keys + class MyKey { ... }; + + // hashing function + class MyKeyHash + { + public: + MyKeyHash() { } + + unsigned long operator()( const MyKey& k ) const + { + // compute the hash + } + + MyKeyHash& operator=(const MyKeyHash&) { return *this; } + }; + + // comparison operator + class MyKeyEqual + { + public: + MyKeyEqual() { } + bool operator()( const MyKey& a, const MyKey& b ) const + { + // compare for equality + } + + MyKeyEqual& operator=(const MyKeyEqual&) { return *this; } + }; + + WX_DECLARE_HASH_MAP( MyKey, // type of the keys + SOME_TYPE, // any type you like + MyKeyHash, // hasher + MyKeyEqual, // key equality predicate + CLASSNAME); // name of the class + @endcode + + + @section hashmap_types Types + + In the documentation below you should replace wxHashMap with the name you used + in the class declaration. + + - wxHashMap::key_type: Type of the hash keys. + - wxHashMap::mapped_type: Type of the values stored in the hash map. + - wxHashMap::value_type: Equivalent to struct { key_type first; mapped_type second }. + - wxHashMap::iterator: Used to enumerate all the elements in a hash map; + it is similar to a value_type*. + - wxHashMap::const_iterator: Used to enumerate all the elements in a constant + hash map; it is similar to a const value_type*. + - wxHashMap::size_type: Used for sizes. + - wxHashMap::Insert_Result: The return value for insert(). + + + @section hashmap_iter Iterators + + An iterator is similar to a pointer, and so you can use the usual pointer operations: + ++it ( and it++ ) to move to the next element, *it to access the element pointed to, + it->first ( it->second ) to access the key ( value ) of the element pointed to. + + Hash maps provide forward only iterators, this means that you can't use --it, + it + 3, it1 - it2. + + @library{wxbase} - @category{FIXME} + @category{containers} */ class wxHashMap { public: - //@{ /** - Copy constructor. + The size parameter is just a hint, the table will resize automatically + to preserve performance. */ wxHashMap(size_type size = 10); + + /** + Copy constructor. + */ wxHashMap(const wxHashMap& map); - //@} //@{ /** Returns an iterator pointing at the first element of the hash map. Please remember that hash maps do not guarantee ordering. */ - const_iterator begin(); - const iterator begin(); + const_iterator begin() const; + iterator begin(); //@} /** @@ -58,42 +198,51 @@ public: Returns an iterator pointing at the one-after-the-last element of the hash map. Please remember that hash maps do not guarantee ordering. */ - const_iterator end(); - const iterator end(); + const_iterator end() const; + iterator end(); //@} //@{ + /** + Erases the element with the given key, and returns the number of elements + erased (either 0 or 1). + */ + size_type erase(const key_type& key); + /** Erases the element pointed to by the iterator. After the deletion the iterator is no longer valid and must not be used. */ - size_type erase(const key_type& key); void erase(iterator it); void erase(const_iterator it); //@} //@{ /** - If an element with the given key is present, the functions returns - an iterator pointing at that element, otherwise an invalid iterator - is returned (i.e. hashmap.find( non_existent_key ) == hashmap.end()). + If an element with the given key is present, the functions returns an + iterator pointing at that element, otherwise an invalid iterator is + returned; i.e. + @code + hashmap.find( non_existent_key ) == hashmap.end() + @endcode */ iterator find(const key_type& key) const; const_iterator find(const key_type& key) const; //@} /** - Inserts the given value in the hash map. The return value is - equivalent to a @c std::pairiterator(), bool; - the iterator points to the inserted element, the boolean value - is @true if @c v was actually inserted. + Inserts the given value in the hash map. + The return value is equivalent to a + @code std::pair @endcode + The iterator points to the inserted element, the boolean value is @true + if @a v was actually inserted. */ Insert_Result insert(const value_type& v); /** - Use the key as an array subscript. The only difference is that if the - given key is not present in the hash map, an element with the - default @c value_type() is inserted in the table. + Use the key as an array subscript. + The only difference is that if the given key is not present in the hash map, + an element with the default @c value_type() is inserted in the table. */ mapped_type operator[](const key_type& key); diff --git a/interface/wx/hashset.h b/interface/wx/hashset.h index 8ca4fc1535..fe3800446b 100644 --- a/interface/wx/hashset.h +++ b/interface/wx/hashset.h @@ -10,31 +10,154 @@ @class wxHashSet This is a simple, type-safe, and reasonably efficient hash set class, - whose interface is a subset of the interface of STL containers. In - particular, the interface is modeled after std::set, and the various, + whose interface is a subset of the interface of STL containers. + In particular, the interface is modeled after std::set, and the various, non-standard, std::hash_map. + Example: + @code + class MyClass { ... }; + + // same, with MyClass* keys (only uses pointer equality!) + WX_DECLARE_HASH_SET( MyClass*, wxPointerHash, wxPointerEqual, MySet1 ); + // same, with int keys + WX_DECLARE_HASH_SET( int, wxIntegerHash, wxIntegerEqual, MySet2 ); + // declare a hash set with string keys + WX_DECLARE_HASH_SET( wxString, wxStringHash, wxStringEqual, MySet3 ); + + MySet1 h1; + MySet2 h1; + MySet3 h3; + + // store and retrieve values + h1.insert( new MyClass( 1 ) ); + + h3.insert( "foo" ); + h3.insert( "bar" ); + h3.insert( "baz" ); + + int size = h3.size(); // now is three + bool has_foo = h3.find( "foo" ) != h3.end(); + + h3.insert( "bar" ); // still has size three + + // iterate over all the elements in the class + MySet3::iterator it; + for( it = h3.begin(); it != h3.end(); ++it ) + { + wxString key = *it; + // do something useful with key + } + @endcode + + + @section hashset_declaringnew Declaring new hash set types + + @code + WX_DECLARE_HASH_SET( KEY_T, // type of the keys + HASH_T, // hasher + KEY_EQ_T, // key equality predicate + CLASSNAME); // name of the class + @endcode + The HASH_T and KEY_EQ_T are the types used for the hashing function and key + comparison. wxWidgets provides three predefined hashing functions: + wxIntegerHash for integer types ( int, long, short, and their unsigned counterparts ), + wxStringHash for strings ( wxString, wxChar*, char* ), and wxPointerHash for + any kind of pointer. + Similarly three equality predicates: wxIntegerEqual, wxStringEqual, wxPointerEqual + are provided. Using this you could declare a hash set using int values like this: + + @code + WX_DECLARE_HASH_SET( int, + wxIntegerHash, + wxIntegerEqual, + MySet ); + + // using an user-defined class for keys + class MyKey { ... }; + + // hashing function + class MyKeyHash + { + public: + MyKeyHash() { } + + unsigned long operator()( const MyKey& k ) const + { + // compute the hash + } + + MyKeyHash& operator=(const MyKeyHash&) { return *this; } + }; + + // comparison operator + class MyKeyEqual + { + public: + MyKeyEqual() { } + bool operator()( const MyKey& a, const MyKey& b ) const + { + // compare for equality + } + + MyKeyEqual& operator=(const MyKeyEqual&) { return *this; } + }; + + WX_DECLARE_HASH_SET( MyKey, // type of the keys + MyKeyHash, // hasher + MyKeyEqual, // key equality predicate + CLASSNAME); // name of the class + @endcode + + + @section hashset_types Types + + In the documentation below you should replace wxHashSet with the name you + used in the class declaration. + + - wxHashSet::key_type: Type of the hash keys + - wxHashSet::mapped_type: Type of hash keys + - wxHashSet::value_type: Type of hash keys + - wxHashSet::iterator: Used to enumerate all the elements in a hash set; + it is similar to a value_type* + - wxHashSet::const_iterator: Used to enumerate all the elements in a constant + hash set; it is similar to a const value_type* + - wxHashSet::size_type: Used for sizes + - wxHashSet::Insert_Result: The return value for insert() + + + @section hashset_iter Iterators + + An iterator is similar to a pointer, and so you can use the usual pointer + operations: ++it ( and it++ ) to move to the next element, *it to access the + element pointed to, *it to access the value of the element pointed to. + Hash sets provide forward only iterators, this means that you can't use --it, + it + 3, it1 - it2. + @library{wxbase} - @category{FIXME} + @category{containers} */ class wxHashSet { public: - //@{ /** - Copy constructor. + The size parameter is just a hint, the table will resize automatically + to preserve performance. */ wxHashSet(size_type size = 10); + + /** + Copy constructor. + */ wxHashSet(const wxHashSet& set); - //@} //@{ /** Returns an iterator pointing at the first element of the hash set. Please remember that hash sets do not guarantee ordering. */ - const_iterator begin(); - const iterator begin(); + const_iterator begin() const; + iterator begin(); //@} /** @@ -58,16 +181,21 @@ public: Returns an iterator pointing at the one-after-the-last element of the hash set. Please remember that hash sets do not guarantee ordering. */ - const_iterator end(); - const iterator end(); + const_iterator end() const; + iterator end(); //@} + /** + Erases the element with the given key, and returns the number of elements + erased (either 0 or 1). + */ + size_type erase(const key_type& key); + //@{ /** Erases the element pointed to by the iterator. After the deletion the iterator is no longer valid and must not be used. */ - size_type erase(const key_type& key); void erase(iterator it); void erase(const_iterator it); //@} @@ -76,17 +204,21 @@ public: /** If an element with the given key is present, the functions returns an iterator pointing at that element, otherwise an invalid iterator - is returned (i.e. hashset.find( non_existent_key ) == hashset.end()). + is returned; i.e. + @code + hashset.find( non_existent_key ) == hashset.end() + @endcode */ iterator find(const key_type& key) const; const_iterator find(const key_type& key) const; //@} /** - Inserts the given value in the hash set. The return value is - equivalent to a @c std::pairwxHashMap::iterator, bool; - the iterator points to the inserted element, the boolean value - is @true if @c v was actually inserted. + Inserts the given value in the hash set. + The return value is equivalent to a + @code std::pair @endcode + The iterator points to the inserted element, the boolean value is @true + if @a v was actually inserted. */ Insert_Result insert(const value_type& v); diff --git a/interface/wx/help.h b/interface/wx/help.h index d32556b447..c250878f82 100644 --- a/interface/wx/help.h +++ b/interface/wx/help.h @@ -9,81 +9,71 @@ /** @class wxHelpController - This is a family of classes by which - applications may invoke a help viewer to provide on-line help. + This is a family of classes by which applications may invoke a help viewer + to provide on-line help. A help controller allows an application to display help, at the contents or at a particular topic, and shut the help program down on termination. This avoids proliferation of many instances of the help viewer whenever the user requests a different topic via the application's menus or buttons. - Typically, an application will create a help controller instance - when it starts, and immediately call @b Initialize - to associate a filename with it. The help viewer will only get run, however, - just before the first call to display something. + Typically, an application will create a help controller instance when it starts, + and immediately call wxHelpController::Initialize to associate a filename with it. + The help viewer will only get run, however, just before the first call to + display something. Most help controller classes actually derive from wxHelpControllerBase and have - names of the form wxXXXHelpController or wxHelpControllerXXX. An - appropriate class is aliased to the name wxHelpController for each platform, as + names of the form wxXXXHelpController or wxHelpControllerXXX. + An appropriate class is aliased to the name wxHelpController for each platform, as follows: + - On desktop Windows, wxCHMHelpController is used (MS HTML Help). + - On Windows CE, wxWinceHelpController is used. + - On all other platforms, wxHtmlHelpController is used if wxHTML is compiled + into wxWidgets; otherwise wxExtHelpController is used (for invoking an + external browser). - On desktop Windows, wxCHMHelpController is used (MS HTML Help). - On Windows CE, wxWinceHelpController is used. - On all other platforms, wxHtmlHelpController is used if wxHTML is - compiled into wxWidgets; otherwise wxExtHelpController is used (for invoking an - external - browser). - - The remaining help controller classes need to be named - explicitly by an application that wishes to make use of them. + The remaining help controller classes need to be named explicitly by an + application that wishes to make use of them. There are currently the following help controller classes defined: - - wxWinHelpController, for controlling Windows Help. - wxCHMHelpController, for controlling MS HTML Help. To use this, you need to - set wxUSE_MS_HTML_HELP - to 1 in setup.h and have htmlhelp.h header from Microsoft's HTML Help kit (you - don't need - VC++ specific htmlhelp.lib because wxWidgets loads necessary DLL at runtime and - so it - works with all compilers). - wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime - is - not available, wxHtmlHelpController. You need to provide - @b both CHM and HTB versions of the help file. For 32bit Windows only. - wxExtHelpController, for controlling external browsers under Unix. - The default browser is Netscape Navigator. The 'help' sample shows its use. - wxWinceHelpController, for controlling a simple @c .htm help controller for - Windows CE applications. - wxHtmlHelpController, a sophisticated help controller using wxHTML(), in - a similar style to the Microsoft HTML Help viewer and using some of the same - files. - Although it has an API compatible with other help controllers, it has more - advanced features, so it is - recommended that you use the specific API for this class instead. Note that if - you - use .zip or .htb formats for your books, you - must add this line to your application initialization: @c - wxFileSystem::AddHandler(new wxArchiveFSHandler); - or nothing will be shown in your help window. - + - wxWinHelpController, for controlling Windows Help. + - wxCHMHelpController, for controlling MS HTML Help. To use this, you need to + set wxUSE_MS_HTML_HELP to 1 in setup.h and have htmlhelp.h header from + Microsoft's HTML Help kit (you don't need VC++ specific htmlhelp.lib + because wxWidgets loads necessary DLL at runtime and so it works with all + compilers). + - wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime + is not available, wxHtmlHelpController. You need to provide @b both CHM and + HTB versions of the help file. For 32bit Windows only. + - wxExtHelpController, for controlling external browsers under Unix. + The default browser is Netscape Navigator. The 'help' sample shows its use. + - wxWinceHelpController, for controlling a simple @c .htm help controller for + Windows CE applications. + - wxHtmlHelpController, a sophisticated help controller using wxHTML(), in a + similar style to the Microsoft HTML Help viewer and using some of the same + files. Although it has an API compatible with other help controllers, it has + more advanced features, so it is recommended that you use the specific API + for this class instead. Note that if you use .zip or .htb formats for your + books, you must add this line to your application initialization: + @code wxFileSystem::AddHandler(new wxArchiveFSHandler); @endcode + or nothing will be shown in your help window. @library{wxbase} @category{help} - @see wxHtmlHelpController, wxHTML() + @see wxHtmlHelpController, @ref overview_html */ -class wxHelpController : public wxObject +class wxHelpController : public wxHelpControllerBase { public: /** Constructs a help instance object, but does not invoke the help viewer. - If you provide a window, it will be used by some help controller classes, such - as + + If you provide a window, it will be used by some help controller classes, such as wxCHMHelpController, wxWinHelpController and wxHtmlHelpController, as the - parent for the help window instead of the value of wxApp::GetTopWindow. You can - also change the parent window later with - SetParentWindow(). + parent for the help window instead of the value of wxApp::GetTopWindow. + + You can also change the parent window later with SetParentWindow(). */ wxHelpController(wxWindow* parentWindow = NULL); @@ -95,19 +85,21 @@ public: /** If the help viewer is not running, runs it and displays the file at the given block number. - @e WinHelp: Refers to the context number. - @e MS HTML Help: Refers to the context number. - @e External HTML help: the same as for DisplaySection(). - @e wxHtmlHelpController: @e sectionNo is an identifier as specified in the @c - .hhc file. See @ref overview_helpformat "Help files format". - This function is for backward compatibility only, and applications should use - @ref displaysection() wxHelpController instead. + + - @e WinHelp: Refers to the context number. + - @e MS HTML Help: Refers to the context number. + - @e External HTML help: the same as for DisplaySection(). + - @e wxHtmlHelpController: @e sectionNo is an identifier as specified in + the @c .hhc file. See @ref overview_html_helpformats. + + @deprecated + This function is for backward compatibility only, and applications + should use DisplaySection() instead. */ virtual bool DisplayBlock(long blockNo); /** - If the help viewer is not running, runs it and displays the - contents. + If the help viewer is not running, runs it and displays the contents. */ virtual bool DisplayContents(); @@ -117,24 +109,33 @@ public: */ virtual bool DisplayContextPopup(int contextId); - //@{ /** If the help viewer is not running, runs it and displays the given section. - @e WinHelp, MS HTML Help @a sectionNo is a context id. - @e External HTML help: wxExtHelpController implements @a sectionNo as an id in - a map file, which is of the form: - @e wxHtmlHelpController: @a sectionNo is an identifier as specified in the @c - .hhc file. See @ref overview_helpformat "Help files format". - See also the help sample for notes on how to specify section numbers for - various help file formats. + The interpretation of section differs between help viewers. + For most viewers, this call is equivalent to KeywordSearch. + For MS HTML Help, wxHTML help and external HTML help, if section has a + .htm or .html extension, that HTML file will be displayed; otherwise a + keyword search is done. */ virtual bool DisplaySection(const wxString& section); + + /** + If the help viewer is not running, runs it and displays the given section. + + - @e WinHelp, MS HTML Help @a sectionNo is a context id. + - @e External HTML help: wxExtHelpController implements @a sectionNo as + an id in a map file, which is of the form: + - @e wxHtmlHelpController: @a sectionNo is an identifier as specified in + the @c .hhc file. See @ref overview_html_helpformats. + See also the help sample for notes on how to specify section numbers for + various help file formats. + */ virtual bool DisplaySection(int sectionNo); - //@} /** Displays the text in a popup window, if possible. + Returns @false if unsuccessful or not implemented. */ virtual bool DisplayTextPopup(const wxString& text, @@ -142,38 +143,30 @@ public: /** wxHtmlHelpController returns the frame, size and position. - For all other help controllers, this function does nothing - and just returns @NULL. - - @param viewer - This defaults to "netscape" for wxExtHelpController. - @param flags - This defaults to wxHELP_NETSCAPE for wxExtHelpController, indicating - that the viewer is a variant of Netscape Navigator. + For all other help controllers, this function does nothing and just + returns @NULL. */ virtual wxFrame* GetFrameParameters(const wxSize* size = NULL, const wxPoint* pos = NULL, bool* newFrameEachTime = NULL); /** - Returns the window to be used as the parent for the help window. This window is - used - by wxCHMHelpController, wxWinHelpController and wxHtmlHelpController. + Returns the window to be used as the parent for the help window. + This window is used by wxCHMHelpController, wxWinHelpController and + wxHtmlHelpController. */ virtual wxWindow* GetParentWindow() const; //@{ /** Initializes the help instance with a help filename, and optionally a server - socket - number if using wxHelp (now obsolete). Does not invoke the help viewer. + socket number if using wxHelp (now obsolete). Does not invoke the help viewer. This must be called directly after the help instance object is created and - before - any attempts to communicate with the viewer. - You may omit the file extension and a suitable one will be chosen. For - wxHtmlHelpController, the extensions zip, htb and hhp will be appended while - searching for - a suitable file. For WinHelp, the hlp extension is appended. + before any attempts to communicate with the viewer. + + You may omit the file extension and a suitable one will be chosen. + For wxHtmlHelpController, the extensions zip, htb and hhp will be appended + while searching for a suitable file. For WinHelp, the hlp extension is appended. */ virtual bool Initialize(const wxString& file); virtual bool Initialize(const wxString& file, int server); @@ -181,26 +174,28 @@ public: /** If the help viewer is not running, runs it, and searches for sections matching - the given keyword. If one match is found, the file is displayed at this - section. The optional parameter allows the search the index - (wxHELP_SEARCH_INDEX) but this currently only supported by the - wxHtmlHelpController. - @e WinHelp, MS HTML Help: If more than one match is found, - the first topic is displayed. - @e External HTML help, simple wxHTML help: If more than one match is found, - a choice of topics is displayed. - @e wxHtmlHelpController: see wxHtmlHelpController::KeywordSearch. + the given keyword. If one match is found, the file is displayed at this section. + The optional parameter allows the search the index (wxHELP_SEARCH_INDEX) + but this currently only supported by the wxHtmlHelpController. + + - @e WinHelp, MS HTML Help: + If more than one match is found, the first topic is displayed. + - @e External HTML help, simple wxHTML help: + If more than one match is found, a choice of topics is displayed. + - @e wxHtmlHelpController: see wxHtmlHelpController::KeywordSearch. */ virtual bool KeywordSearch(const wxString& keyWord, wxHelpSearchMode mode = wxHELP_SEARCH_ALL); /** If the help viewer is not running, runs it and loads the given file. - If the filename is not supplied or is - empty, the file specified in @b Initialize is used. If the viewer is - already displaying the specified file, it will not be reloaded. This - member function may be used before each display call in case the user - has opened another file. + If the filename is not supplied or is empty, the file specified in + Initialize() is used. + + If the viewer is already displaying the specified file, it will not be + reloaded. This member function may be used before each display call in + case the user has opened another file. + wxHtmlHelpController ignores this call. */ virtual bool LoadFile(const wxString& file = ""); @@ -213,15 +208,15 @@ public: /** If the viewer is running, quits it by disconnecting. - For Windows Help, the viewer will only close if no other application is using - it. + For Windows Help, the viewer will only close if no other application is using it. */ virtual bool Quit(); /** For wxHtmlHelpController, the title is set (again with %s indicating the - page title) and also the size and position of the frame if the frame is already - open. @a newFrameEachTime is ignored. + page title) and also the size and position of the frame if the frame is + already open. @a newFrameEachTime is ignored. + For all other help controllers this function has no effect. */ virtual void SetFrameParameters(const wxString& title, @@ -236,9 +231,23 @@ public: virtual void SetParentWindow(wxWindow* parentWindow); /** - Sets detailed viewer information. So far this is only relevant to - wxExtHelpController. + Sets detailed viewer information. + So far this is only relevant to wxExtHelpController. Some examples of usage: + + @code + m_help.SetViewer("kdehelp"); + m_help.SetViewer("gnome-help-browser"); + m_help.SetViewer("netscape", wxHELP_NETSCAPE); + @endcode + + @param viewer + This defaults to "netscape" for wxExtHelpController. + @param flags + This defaults to wxHELP_NETSCAPE for wxExtHelpController, indicating + that the viewer is a variant of Netscape Navigator. + + @todo modernize this function with ::wxLaunchDefaultBrowser */ virtual void SetViewer(const wxString& viewer, long flags); }; diff --git a/interface/wx/htmllbox.h b/interface/wx/htmllbox.h index 8003847b38..c7cb35e86d 100644 --- a/interface/wx/htmllbox.h +++ b/interface/wx/htmllbox.h @@ -9,11 +9,19 @@ /** @class wxHtmlListBox - wxHtmlListBox is an implementation of wxVListBox which - shows HTML content in the listbox rows. This is still an abstract base class - and you will need to derive your own class from it (see htlbox sample for the - example) but you will only need to override a single - wxHtmlListBox::OnGetItem function. + wxHtmlListBox is an implementation of wxVListBox which shows HTML content in + the listbox rows. This is still an abstract base class and you will need to + derive your own class from it (see htlbox sample for the example) but you will + only need to override a single wxHtmlListBox::OnGetItem function. + + @beginEventTable{wxHtmlCellEvent,wxHtmlLinkEvent} + @event{EVT_HTML_CELL_CLICKED(id, func)} + A wxHtmlCell was clicked. + @event{EVT_HTML_CELL_HOVER(id, func)} + The mouse passed over a wxHtmlCell. + @event{EVT_HTML_LINK_CLICKED(id, func)} + A wxHtmlCell which contains an hyperlink was clicked. + @endEventTable @library{wxhtml} @category{ctrl} @@ -24,18 +32,19 @@ class wxHtmlListBox : public wxVListBox { public: - //@{ /** - Default constructor, you must call Create() - later. + Normal constructor which calls Create() internally. */ wxHtmlListBox(wxWindow* parent, wxWindowID id = wxID_ANY, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = 0, const wxString& name = wxHtmlListBoxNameStr); + + /** + Default constructor, you must call Create() later. + */ wxHtmlListBox(); - //@} /** Destructor cleans up whatever resources we use. @@ -44,10 +53,11 @@ public: /** Creates the control and optionally sets the initial number of items in it - (it may also be set or changed later with - wxVListBox::SetItemCount). + (it may also be set or changed later with wxVListBox::SetItemCount). + There are no special styles defined for wxHtmlListBox, in particular the wxListBox styles (with the exception of @c wxLB_MULTIPLE) can not be used here. + Returns @true on success or @false if the control couldn't be created */ bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, @@ -58,14 +68,15 @@ public: //@{ /** - Returns the wxFileSystem used by the HTML parser of - this object. The file system object is used to resolve the paths in HTML - fragments displayed in the control and you should use - wxFileSystem::ChangePathTo if you use - relative paths for the images or other resources embedded in your HTML. + Returns the wxFileSystem used by the HTML parser of this object. + + The file system object is used to resolve the paths in HTML fragments + displayed in the control and you should use wxFileSystem::ChangePathTo + if you use relative paths for the images or other resources embedded in + your HTML. */ - wxFileSystem GetFileSystem() const; - const wxFileSystem GetFileSystem() const; + wxFileSystem& GetFileSystem() const; + const wxFileSystem& GetFileSystem() const; //@} protected: @@ -85,12 +96,11 @@ protected: /** This virtual function may be overridden to change the appearance of the - background of the selected cells in the same way as - GetSelectedTextColour(). - It should be rarely, if ever, used because - wxVListBox::SetSelectionBackground allows to - change the selection background for all cells at once and doing anything more - fancy is probably going to look strangely. + background of the selected cells in the same way as GetSelectedTextColour(). + + It should be rarely, if ever, used because wxVListBox::SetSelectionBackground + allows to change the selection background for all cells at once and doing + anything more fancy is probably going to look strangely. @see GetSelectedTextColour() */ @@ -117,13 +127,13 @@ protected: This method must be implemented in the derived class and should return the body (i.e. without @c html nor @c body tags) of the HTML fragment for the given item. + Note that this function should always return a text fragment for the @a n item which renders with the same height both when it is selected and when it's not: i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to make the items appear differently when they are selected, then you should make - sure - that the returned HTML fragment will render with the same height or else you'll - see some artifacts when the user selects an item. + sure that the returned HTML fragment will render with the same height or else + you'll see some artifacts when the user selects an item. */ virtual wxString OnGetItem(size_t n) const = 0; }; @@ -136,44 +146,62 @@ protected: wxSimpleHtmlListBox is an implementation of wxHtmlListBox which shows HTML content in the listbox rows. - Unlike wxHtmlListBox, this is not an abstract class and thus it - has the advantage that you can use it without deriving your own class from it. + Unlike wxHtmlListBox, this is not an abstract class and thus it has the + advantage that you can use it without deriving your own class from it. However, it also has the disadvantage that this is not a virtual control and - thus it's not - well-suited for those cases where you need to show a huge number of items: - every time you - add/insert a string, it will be stored internally and thus will take memory. + thus it's not well-suited for those cases where you need to show a huge number + of items: every time you add/insert a string, it will be stored internally + and thus will take memory. The interface exposed by wxSimpleHtmlListBox fully implements the - wxControlWithItems interface, thus you should refer to - wxControlWithItems's documentation for the API reference - for adding/removing/retrieving items in the listbox. - Also note that the wxVListBox::SetItemCount function is + wxControlWithItems interface, thus you should refer to wxControlWithItems's + documentation for the API reference for adding/removing/retrieving items in + the listbox. Also note that the wxVListBox::SetItemCount function is @c protected in wxSimpleHtmlListBox's context so that you cannot call it - directly, - wxSimpleHtmlListBox will do it for you. + directly, wxSimpleHtmlListBox will do it for you. Note: in case you need to append a lot of items to the control at once, make sure to use the - @ref wxControlWithItems::append "Append(const wxArrayString )" function. + @ref wxControlWithItems::Append "Append(const wxArrayString&)" function. Thus the only difference between a wxListBox and a wxSimpleHtmlListBox is that the latter stores strings which can contain HTML fragments (see the - list of - @ref overview_htmltagssupported "tags supported by wxHTML"). + list of @ref overview_html_supptags "tags supported by wxHTML"). Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain - the @c html - or @c body tags. + the @c \ or @c \ tags. @beginStyleTable @style{wxHLB_DEFAULT_STYLE} The default style: wxBORDER_SUNKEN @style{wxHLB_MULTIPLE} - Multiple-selection list: the user can toggle multiple items on and - off. + Multiple-selection list: the user can toggle multiple items on and off. @endStyleTable + + A wxSimpleHtmlListBox emits the same events used by wxListBox and by wxHtmlListBox. + + @beginEventTable{wxCommandEvent} + @event{EVT_LISTBOX(id, func)} + Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the list + is selected. + @event{EVT_LISTBOX_DCLICK(id, func)} + Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the listbox is + double-clicked. + @endEventTable + + @beginEventTable{wxHtmlCellEvent} + @event{EVT_HTML_CELL_CLICKED(id, func)} + A wxHtmlCell was clicked. + @event{EVT_HTML_CELL_HOVER(id, func)} + The mouse passed over a wxHtmlCell. + @endEventTable + + @beginEventTable{wxHtmlLinkEvent} + @event{EVT_HTML_LINK_CLICKED(id, func)} + A wxHtmlCell which contains an hyperlink was clicked. + @endEventTable + @library{wxhtml} @category{ctrl} @appearance{simplehtmllistbox.png} @@ -183,10 +211,27 @@ protected: class wxSimpleHtmlListBox : public wxHtmlListBox { public: - //@{ /** - Default constructor, you must call Create() - later. + Constructor, creating and showing the HTML list box. + + @param parent + Parent window. Must not be NULL. + @param id + Window identifier. A value of -1 indicates a default value. + @param pos + Window position. + @param size + Window size. If wxDefaultSize is specified then the window is sized appropriately. + @param n + Number of strings with which to initialise the control. + @param choices + An array of strings with which to initialise the control. + @param style + Window style. See wxHLB_* flags. + @param validator + Window validator. + @param name + Window name. */ wxHtmlListBox(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, @@ -196,6 +241,27 @@ public: long style = wxHLB_DEFAULT_STYLE, const wxValidator& validator = wxDefaultValidator, const wxString& name = "simpleHtmlListBox"); + + /** + Constructor, creating and showing the HTML list box. + + @param parent + Parent window. Must not be NULL. + @param id + Window identifier. A value of -1 indicates a default value. + @param pos + Window position. + @param size + Window size. If wxDefaultSize is specified then the window is sized appropriately. + @param choices + An array of strings with which to initialise the control. + @param style + Window style. See wxHLB_* flags. + @param validator + Window validator. + @param name + Window name. + */ wxHtmlListBox(wxWindow* parent, wxWindowID id, const wxPoint& pos, const wxSize& size, @@ -203,11 +269,11 @@ public: long style = wxHLB_DEFAULT_STYLE, const wxValidator& validator = wxDefaultValidator, const wxString& name = "simpleHtmlListBox"); - See also - wxSimpleHtmlListBox::Create + /** + Default constructor, you must call Create() later. + */ wxSimpleHtmlListBox(); - //@} /** Frees the array of stored items and relative client data. diff --git a/interface/wx/hyperlink.h b/interface/wx/hyperlink.h index 0b1685eb8d..115db369cb 100644 --- a/interface/wx/hyperlink.h +++ b/interface/wx/hyperlink.h @@ -9,11 +9,15 @@ /** @class wxHyperlinkEvent - This event class is used for the events generated by - wxHyperlinkCtrl. + This event class is used for the events generated by wxHyperlinkCtrl. + + @beginEventTable{wxHyperlinkEvent} + @event{EVT_HYPERLINK(id, func)} + User clicked on an hyperlink. + @endEventTable @library{wxadv} - @category{FIXME} + @category{events} */ class wxHyperlinkEvent : public wxCommandEvent { @@ -21,8 +25,7 @@ public: /** The constructor is not normally used by the user code. */ - wxHyperlinkEvent(wxObject* generator, int id, - const wxString& url); + wxHyperlinkEvent(wxObject* generator, int id, const wxString& url); /** Returns the URL of the hyperlink where the user has just clicked. @@ -41,15 +44,15 @@ public: @class wxHyperlinkCtrl This class shows a static text element which links to an URL. - Appearance and behaviour is completely customizable. In fact, when the user - clicks on the hyperlink, a wxHyperlinkEvent is - sent but if that event is not handled (or it's skipped; see - wxEvent::Skip), then a call to - wxLaunchDefaultBrowser() is done with the - hyperlink's URL. + Appearance and behaviour is completely customizable. + + In fact, when the user clicks on the hyperlink, a wxHyperlinkEvent is + sent but if that event is not handled (or it's skipped; see wxEvent::Skip), + then a call to wxLaunchDefaultBrowser() is done with the hyperlink's URL. Note that standard wxWindow functions like wxWindow::SetBackgroundColour, - wxWindow::SetFont, wxWindow::SetCursor, wxWindow::SetLabel can be used to customize appearance of the hyperlink. + wxWindow::SetFont, wxWindow::SetCursor, wxWindow::SetLabel can be used to + customize appearance of the hyperlink. @beginStyleTable @style{wxHL_ALIGN_LEFT} @@ -68,6 +71,14 @@ public: wxBORDER_NONE|wxHL_CONTEXTMENU|wxHL_ALIGN_CENTRE. @endStyleTable + @beginEventTable{wxHyperlinkEvent} + @event{EVT_HYPERLINK(id, func)} + The hyperlink was (left) clicked. If this event is not handled in user's + code (or it's skipped; see wxEvent::Skip), then a call to wxLaunchDefaultBrowser + is done with the hyperlink's URL. + @endEventTable + + @library{wxadv} @category{ctrl} @appearance{hyperlinkctrl.png} @@ -102,12 +113,10 @@ public: @param pos Window position. @param size - Window size. If the wxDefaultSize is specified then the window is sized - appropriately. + Window size. + If the wxDefaultSize is specified then the window is sized appropriately. @param style Window style. See wxHyperlinkCtrl. - @param validator - Window validator. @param name Window name. */ @@ -125,8 +134,7 @@ public: /** Returns the colour used to print the label when the link has never been clicked - before - (i.e. the link has not been @e visited) and the mouse is not over the control. + before (i.e. the link has not been @e visited) and the mouse is not over the control. */ virtual wxColour GetNormalColour() const; @@ -143,9 +151,8 @@ public: /** Returns the colour used to print the label when the mouse is not over the - control - and the link has already been clicked before (i.e. the link has been @e - visited). + control and the link has already been clicked before (i.e. the link has + been @e visited). */ virtual wxColour GetVisitedColour() const; @@ -156,8 +163,7 @@ public: virtual void SetHoverColour(const wxColour& colour); /** - Sets the colour used to print the label when the link has never been clicked - before + Sets the colour used to print the label when the link has never been clicked before (i.e. the link has not been @e visited) and the mouse is not over the control. */ virtual void SetNormalColour(const wxColour& colour); @@ -174,8 +180,7 @@ public: /** Sets the colour used to print the label when the mouse is not over the control - and the link has already been clicked before (i.e. the link has been @e - visited). + and the link has already been clicked before (i.e. the link has been @e visited). */ virtual void SetVisitedColour(const wxColour& colour); };