/**
@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}
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();
//@}
/**
- 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);
/**
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);
@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();
//@}
/**
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<wxHashMap::iterator, bool> @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);
@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();
//@}
/**
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);
//@}
/**
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<wxHashMap::iterator, bool> @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);
/**
@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);
/**
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();
*/
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,
/**
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);
/**
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 = "");
/**
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,
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);
};
/**
@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}
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.
/**
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,
//@{
/**
- 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:
/**
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()
*/
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;
};
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 \<html\> or @c \<body\> 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}
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,
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,
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.
/**
@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
{
/**
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.
@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}
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}
@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.
*/
/**
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;
/**
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;
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);
/**
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);
};
projects / wxWidgets.git / commitdiff
