]> git.saurik.com Git - wxWidgets.git/blame - interface/htmllbox.h
don't blit too much when copying static box border in OnPaint()
[wxWidgets.git] / interface / htmllbox.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: htmllbox.h
e54c96f1 3// Purpose: interface of wxHtmlListBox
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxHtmlListBox
11 @wxheader{htmllbox.h}
7c913512 12
23324ae1
FM
13 wxHtmlListBox is an implementation of wxVListBox which
14 shows HTML content in the listbox rows. This is still an abstract base class
15 and you will need to derive your own class from it (see htlbox sample for the
16 example) but you will only need to override a single
17 wxHtmlListBox::OnGetItem function.
7c913512 18
23324ae1
FM
19 @library{wxhtml}
20 @category{ctrl}
21 @appearance{htmllistbox.png}
7c913512 22
e54c96f1 23 @see wxSimpleHtmlListBox
23324ae1
FM
24*/
25class wxHtmlListBox : public wxVListBox
26{
27public:
28 //@{
29 /**
30 Default constructor, you must call Create()
31 later.
32 */
33 wxHtmlListBox(wxWindow* parent, wxWindowID id = wxID_ANY,
34 const wxPoint& pos = wxDefaultPosition,
35 const wxSize& size = wxDefaultSize,
36 long style = 0,
37 const wxString& name = wxHtmlListBoxNameStr);
7c913512 38 wxHtmlListBox();
23324ae1
FM
39 //@}
40
41 /**
42 Destructor cleans up whatever resources we use.
43 */
44 ~wxHtmlListBox();
45
46 /**
47 Creates the control and optionally sets the initial number of items in it
48 (it may also be set or changed later with
49 wxVListBox::SetItemCount).
23324ae1
FM
50 There are no special styles defined for wxHtmlListBox, in particular the
51 wxListBox styles (with the exception of @c wxLB_MULTIPLE) can not be used here.
23324ae1
FM
52 Returns @true on success or @false if the control couldn't be created
53 */
54 bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
55 const wxPoint& pos = wxDefaultPosition,
56 const wxSize& size = wxDefaultSize,
57 long style = 0,
58 const wxString& name = wxHtmlListBoxNameStr);
59
60 //@{
61 /**
62 Returns the wxFileSystem used by the HTML parser of
63 this object. The file system object is used to resolve the paths in HTML
64 fragments displayed in the control and you should use
65 wxFileSystem::ChangePathTo if you use
66 relative paths for the images or other resources embedded in your HTML.
67 */
328f5751
FM
68 wxFileSystem GetFileSystem() const;
69 const wxFileSystem GetFileSystem() const;
23324ae1
FM
70 //@}
71
72 /**
73 This virtual function may be overridden to change the appearance of the
74 background of the selected cells in the same way as
75 GetSelectedTextColour().
23324ae1
FM
76 It should be rarely, if ever, used because
77 wxVListBox::SetSelectionBackground allows to
78 change the selection background for all cells at once and doing anything more
79 fancy is probably going to look strangely.
3c4f71cc 80
4cc4bfaf 81 @see GetSelectedTextColour()
23324ae1 82 */
328f5751 83 wxColour GetSelectedTextBgColour(const wxColour& colBg) const;
23324ae1
FM
84
85 /**
86 This virtual function may be overridden to customize the appearance of the
4cc4bfaf 87 selected cells. It is used to determine how the colour @a colFg is going to
23324ae1
FM
88 look inside selection. By default all original colours are completely ignored
89 and the standard, system-dependent, selection colour is used but the program
90 may wish to override this to achieve some custom appearance.
3c4f71cc 91
4cc4bfaf
FM
92 @see GetSelectedTextBgColour(),
93 wxVListBox::SetSelectionBackground, wxSystemSettings::GetColour
23324ae1 94 */
328f5751 95 wxColour GetSelectedTextColour(const wxColour& colFg) const;
23324ae1
FM
96
97 /**
98 This method must be implemented in the derived class and should return
99 the body (i.e. without @c html nor @c body tags) of the HTML fragment
100 for the given item.
4cc4bfaf 101 Note that this function should always return a text fragment for the @a n item
23324ae1
FM
102 which renders with the same height both when it is selected and when it's not:
103 i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to
104 make the items appear differently when they are selected, then you should make
105 sure
106 that the returned HTML fragment will render with the same height or else you'll
107 see some artifacts when the user selects an item.
108 */
328f5751 109 wxString OnGetItem(size_t n) const;
23324ae1
FM
110
111 /**
112 This function may be overridden to decorate HTML returned by
113 OnGetItem().
114 */
328f5751 115 wxString OnGetItemMarkup(size_t n) const;
23324ae1
FM
116
117 /**
118 Called when the user clicks on hypertext link. Does nothing by default.
119 Overloading this method is deprecated; intercept the event instead.
3c4f71cc 120
7c913512 121 @param n
4cc4bfaf 122 Index of the item containing the link.
7c913512 123 @param link
4cc4bfaf 124 Description of the link.
3c4f71cc 125
4cc4bfaf 126 @see See also wxHtmlLinkInfo.
23324ae1
FM
127 */
128 virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link);
129};
130
131
e54c96f1 132
23324ae1
FM
133/**
134 @class wxSimpleHtmlListBox
135 @wxheader{htmllbox.h}
7c913512 136
23324ae1
FM
137 wxSimpleHtmlListBox is an implementation of wxHtmlListBox which
138 shows HTML content in the listbox rows.
7c913512 139
23324ae1
FM
140 Unlike wxHtmlListBox, this is not an abstract class and thus it
141 has the advantage that you can use it without deriving your own class from it.
142 However, it also has the disadvantage that this is not a virtual control and
143 thus it's not
144 well-suited for those cases where you need to show a huge number of items:
145 every time you
146 add/insert a string, it will be stored internally and thus will take memory.
7c913512 147
23324ae1
FM
148 The interface exposed by wxSimpleHtmlListBox fully implements the
149 wxControlWithItems interface, thus you should refer to
150 wxControlWithItems's documentation for the API reference
151 for adding/removing/retrieving items in the listbox.
152 Also note that the wxVListBox::SetItemCount function is
153 @c protected in wxSimpleHtmlListBox's context so that you cannot call it
154 directly,
155 wxSimpleHtmlListBox will do it for you.
7c913512 156
23324ae1
FM
157 Note: in case you need to append a lot of items to the control at once, make
158 sure to use the
159 @ref wxControlWithItems::append "Append(const wxArrayString )" function.
7c913512 160
23324ae1
FM
161 Thus the only difference between a wxListBox and a wxSimpleHtmlListBox
162 is that the latter stores strings which can contain HTML fragments (see the
163 list of
164 @ref overview_htmltagssupported "tags supported by wxHTML").
7c913512 165
23324ae1 166 Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain
7c913512 167 the @c html
23324ae1 168 or @c body tags.
7c913512 169
23324ae1
FM
170 @beginStyleTable
171 @style{wxHLB_DEFAULT_STYLE}:
172 The default style: wxBORDER_SUNKEN
173 @style{wxHLB_MULTIPLE}:
174 Multiple-selection list: the user can toggle multiple items on and
175 off.
176 @endStyleTable
7c913512 177
23324ae1
FM
178 @library{wxhtml}
179 @category{ctrl}
180 @appearance{simplehtmllistbox.png}
7c913512 181
e54c96f1 182 @see wxSimpleHtmlListBox::Create
23324ae1
FM
183*/
184class wxSimpleHtmlListBox : public wxHtmlListBox
185{
186public:
187 //@{
188 /**
189 Default constructor, you must call Create()
190 later.
191 */
192 wxHtmlListBox(wxWindow* parent, wxWindowID id,
193 const wxPoint& pos = wxDefaultPosition,
194 const wxSize& size = wxDefaultSize,
195 int n = 0,
4cc4bfaf 196 const wxString choices[] = NULL,
23324ae1
FM
197 long style = wxHLB_DEFAULT_STYLE,
198 const wxValidator& validator = wxDefaultValidator,
199 const wxString& name = "simpleHtmlListBox");
7c913512
FM
200 wxHtmlListBox(wxWindow* parent, wxWindowID id,
201 const wxPoint& pos,
202 const wxSize& size,
203 const wxArrayString& choices,
204 long style = wxHLB_DEFAULT_STYLE,
205 const wxValidator& validator = wxDefaultValidator,
206 const wxString& name = "simpleHtmlListBox");
207 See also
208 wxSimpleHtmlListBox::Create
209
210 wxSimpleHtmlListBox();
23324ae1
FM
211 //@}
212
213 /**
214 Frees the array of stored items and relative client data.
215 */
216 ~wxSimpleHtmlListBox();
217
218 //@{
219 /**
7c913512 220 Creates the HTML listbox for two-step construction.
23324ae1
FM
221 See wxSimpleHtmlListBox() for further details.
222 */
223 bool Create(wxWindow* parent, wxWindowID id,
224 const wxPoint& pos = wxDefaultPosition,
225 const wxSize& size = wxDefaultSize,
226 int n,
4cc4bfaf 227 const wxString choices[] = NULL,
23324ae1
FM
228 long style = wxHLB_DEFAULT_STYLE,
229 const wxValidator& validator = wxDefaultValidator,
230 const wxString& name = "simpleHtmlListBox");
7c913512
FM
231 bool Create(wxWindow* parent, wxWindowID id,
232 const wxPoint& pos,
233 const wxSize& size,
234 const wxArrayString& choices,
235 long style = wxHLB_DEFAULT_STYLE,
236 const wxValidator& validator = wxDefaultValidator,
237 const wxString& name = "simpleHtmlListBox");
23324ae1
FM
238 //@}
239};
e54c96f1 240