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

remaining h* interface header revision

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56662 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-11-03 14:37:14 +00:00
parent f9bb777f88
commit 9cc56d1fc0
6 changed files with 627 additions and 241 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
interface/wx/hash.h
View File

@@ -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);

191
interface/wx/hashmap.h
View File

@@ -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:
//@{
/**
The size parameter is just a hint, the table will resize automatically
to preserve performance.
*/
wxHashMap(size_type size = 10);
/**
Copy constructor.
*/
wxHashMap(size_type size = 10);
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<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);

164
interface/wx/hashset.h
View File

@@ -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:
//@{
/**
The size parameter is just a hint, the table will resize automatically
to preserve performance.
*/
wxHashSet(size_type size = 10);
/**
Copy constructor.
*/
wxHashSet(size_type size = 10);
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<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);

229
interface/wx/help.h
View File

@@ -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);
};

170
interface/wx/htmllbox.h
View File

@@ -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 \<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}
@@ -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.

55
interface/wx/hyperlink.h
View File

@@ -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);
};