1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxHtmlListBox
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
12 wxHtmlListBox is an implementation of wxVListBox which shows HTML content in
13 the listbox rows. This is still an abstract base class and you will need to
14 derive your own class from it (see htlbox sample for the example) but you will
15 only need to override a single wxHtmlListBox::OnGetItem function.
17 @beginEventTable{wxHtmlCellEvent,wxHtmlLinkEvent}
18 @event{EVT_HTML_CELL_CLICKED(id, func)}
19 A wxHtmlCell was clicked.
20 @event{EVT_HTML_CELL_HOVER(id, func)}
21 The mouse passed over a wxHtmlCell.
22 @event{EVT_HTML_LINK_CLICKED(id, func)}
23 A wxHtmlCell which contains an hyperlink was clicked.
28 @appearance{htmllistbox.png}
30 @see wxSimpleHtmlListBox
32 class wxHtmlListBox
: public wxVListBox
36 Normal constructor which calls Create() internally.
38 wxHtmlListBox(wxWindow
* parent
, wxWindowID id
= wxID_ANY
,
39 const wxPoint
& pos
= wxDefaultPosition
,
40 const wxSize
& size
= wxDefaultSize
,
42 const wxString
& name
= wxHtmlListBoxNameStr
);
45 Default constructor, you must call Create() later.
50 Destructor cleans up whatever resources we use.
52 virtual ~wxHtmlListBox();
55 Creates the control and optionally sets the initial number of items in it
56 (it may also be set or changed later with wxVListBox::SetItemCount).
58 There are no special styles defined for wxHtmlListBox, in particular the
59 wxListBox styles (with the exception of @c wxLB_MULTIPLE) can not be used here.
61 Returns @true on success or @false if the control couldn't be created
63 bool Create(wxWindow
* parent
, wxWindowID id
= wxID_ANY
,
64 const wxPoint
& pos
= wxDefaultPosition
,
65 const wxSize
& size
= wxDefaultSize
,
67 const wxString
& name
= wxHtmlListBoxNameStr
);
71 Returns the wxFileSystem used by the HTML parser of this object.
73 The file system object is used to resolve the paths in HTML fragments
74 displayed in the control and you should use wxFileSystem::ChangePathTo
75 if you use relative paths for the images or other resources embedded in
78 wxFileSystem
& GetFileSystem() const;
79 const wxFileSystem
& GetFileSystem() const;
85 Called when the user clicks on hypertext link. Does nothing by default.
86 Overloading this method is deprecated; intercept the event instead.
89 Index of the item containing the link.
91 Description of the link.
95 virtual void OnLinkClicked(size_t n
, const wxHtmlLinkInfo
& link
);
98 This virtual function may be overridden to change the appearance of the
99 background of the selected cells in the same way as GetSelectedTextColour().
101 It should be rarely, if ever, used because wxVListBox::SetSelectionBackground
102 allows to change the selection background for all cells at once and doing
103 anything more fancy is probably going to look strangely.
105 @see GetSelectedTextColour()
107 virtual wxColour
GetSelectedTextBgColour(const wxColour
& colBg
) const;
110 This virtual function may be overridden to customize the appearance of the
111 selected cells. It is used to determine how the colour @a colFg is going to
112 look inside selection. By default all original colours are completely ignored
113 and the standard, system-dependent, selection colour is used but the program
114 may wish to override this to achieve some custom appearance.
116 @see GetSelectedTextBgColour(),
117 wxVListBox::SetSelectionBackground, wxSystemSettings::GetColour
119 virtual wxColour
GetSelectedTextColour(const wxColour
& colFg
) const;
122 This function may be overridden to decorate HTML returned by OnGetItem().
124 virtual wxString
OnGetItemMarkup(size_t n
) const;
127 This method must be implemented in the derived class and should return
128 the body (i.e. without @c html nor @c body tags) of the HTML fragment
131 Note that this function should always return a text fragment for the @a n item
132 which renders with the same height both when it is selected and when it's not:
133 i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to
134 make the items appear differently when they are selected, then you should make
135 sure that the returned HTML fragment will render with the same height or else
136 you'll see some artifacts when the user selects an item.
138 virtual wxString
OnGetItem(size_t n
) const = 0;
144 @class wxSimpleHtmlListBox
146 wxSimpleHtmlListBox is an implementation of wxHtmlListBox which
147 shows HTML content in the listbox rows.
149 Unlike wxHtmlListBox, this is not an abstract class and thus it has the
150 advantage that you can use it without deriving your own class from it.
151 However, it also has the disadvantage that this is not a virtual control and
152 thus it's not well-suited for those cases where you need to show a huge number
153 of items: every time you add/insert a string, it will be stored internally
154 and thus will take memory.
156 The interface exposed by wxSimpleHtmlListBox fully implements the
157 wxControlWithItems interface, thus you should refer to wxControlWithItems's
158 documentation for the API reference for adding/removing/retrieving items in
159 the listbox. Also note that the wxVListBox::SetItemCount function is
160 @c protected in wxSimpleHtmlListBox's context so that you cannot call it
161 directly, wxSimpleHtmlListBox will do it for you.
163 Note: in case you need to append a lot of items to the control at once, make
165 @ref wxControlWithItems::Append "Append(const wxArrayString&)" function.
167 Thus the only difference between a wxListBox and a wxSimpleHtmlListBox
168 is that the latter stores strings which can contain HTML fragments (see the
169 list of @ref overview_html_supptags "tags supported by wxHTML").
171 Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain
172 the @c \<html\> or @c \<body\> tags.
175 @style{wxHLB_DEFAULT_STYLE}
176 The default style: wxBORDER_SUNKEN
177 @style{wxHLB_MULTIPLE}
178 Multiple-selection list: the user can toggle multiple items on and off.
182 A wxSimpleHtmlListBox emits the same events used by wxListBox and by wxHtmlListBox.
184 @beginEventTable{wxCommandEvent}
185 @event{EVT_LISTBOX(id, func)}
186 Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the list
188 @event{EVT_LISTBOX_DCLICK(id, func)}
189 Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the listbox is
193 @beginEventTable{wxHtmlCellEvent}
194 @event{EVT_HTML_CELL_CLICKED(id, func)}
195 A wxHtmlCell was clicked.
196 @event{EVT_HTML_CELL_HOVER(id, func)}
197 The mouse passed over a wxHtmlCell.
200 @beginEventTable{wxHtmlLinkEvent}
201 @event{EVT_HTML_LINK_CLICKED(id, func)}
202 A wxHtmlCell which contains an hyperlink was clicked.
207 @appearance{simplehtmllistbox.png}
209 @see wxSimpleHtmlListBox::Create
211 class wxSimpleHtmlListBox
: public wxHtmlListBox
215 Constructor, creating and showing the HTML list box.
218 Parent window. Must not be NULL.
220 Window identifier. A value of -1 indicates a default value.
224 Window size. If wxDefaultSize is specified then the window is sized appropriately.
226 Number of strings with which to initialise the control.
228 An array of strings with which to initialise the control.
230 Window style. See wxHLB_* flags.
236 wxSimpleHtmlListBox(wxWindow
* parent
, wxWindowID id
,
237 const wxPoint
& pos
= wxDefaultPosition
,
238 const wxSize
& size
= wxDefaultSize
,
240 const wxString choices
[] = NULL
,
241 long style
= wxHLB_DEFAULT_STYLE
,
242 const wxValidator
& validator
= wxDefaultValidator
,
243 const wxString
& name
= wxSimpleHtmlListBoxNameStr
);
246 Constructor, creating and showing the HTML list box.
249 Parent window. Must not be NULL.
251 Window identifier. A value of -1 indicates a default value.
255 Window size. If wxDefaultSize is specified then the window is sized appropriately.
257 An array of strings with which to initialise the control.
259 Window style. See wxHLB_* flags.
265 wxSimpleHtmlListBox(wxWindow
* parent
, wxWindowID id
,
268 const wxArrayString
& choices
,
269 long style
= wxHLB_DEFAULT_STYLE
,
270 const wxValidator
& validator
= wxDefaultValidator
,
271 const wxString
& name
= wxSimpleHtmlListBoxNameStr
);
274 Default constructor, you must call Create() later.
276 wxSimpleHtmlListBox();
279 Frees the array of stored items and relative client data.
281 virtual ~wxSimpleHtmlListBox();
285 Creates the HTML listbox for two-step construction.
286 See wxSimpleHtmlListBox() for further details.
288 bool Create(wxWindow
* parent
, wxWindowID id
,
289 const wxPoint
& pos
= wxDefaultPosition
,
290 const wxSize
& size
= wxDefaultSize
,
292 const wxString choices
[] = NULL
,
293 long style
= wxHLB_DEFAULT_STYLE
,
294 const wxValidator
& validator
= wxDefaultValidator
,
295 const wxString
& name
= wxSimpleHtmlListBoxNameStr
);
296 bool Create(wxWindow
* parent
, wxWindowID id
,
299 const wxArrayString
& choices
,
300 long style
= wxHLB_DEFAULT_STYLE
,
301 const wxValidator
& validator
= wxDefaultValidator
,
302 const wxString
& name
= wxSimpleHtmlListBoxNameStr
);