| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: htmllbox.h |
| 3 | // Purpose: interface of wxHtmlListBox |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows licence |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | @class wxHtmlListBox |
| 11 | |
| 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. |
| 16 | |
| 17 | @beginEventEmissionTable{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. |
| 24 | @endEventTable |
| 25 | |
| 26 | @library{wxhtml} |
| 27 | @category{ctrl} |
| 28 | |
| 29 | @see wxSimpleHtmlListBox |
| 30 | */ |
| 31 | class wxHtmlListBox : public wxVListBox |
| 32 | { |
| 33 | public: |
| 34 | /** |
| 35 | Normal constructor which calls Create() internally. |
| 36 | */ |
| 37 | wxHtmlListBox(wxWindow* parent, wxWindowID id = wxID_ANY, |
| 38 | const wxPoint& pos = wxDefaultPosition, |
| 39 | const wxSize& size = wxDefaultSize, |
| 40 | long style = 0, |
| 41 | const wxString& name = wxHtmlListBoxNameStr); |
| 42 | |
| 43 | /** |
| 44 | Default constructor, you must call Create() later. |
| 45 | */ |
| 46 | wxHtmlListBox(); |
| 47 | |
| 48 | /** |
| 49 | Destructor cleans up whatever resources we use. |
| 50 | */ |
| 51 | virtual ~wxHtmlListBox(); |
| 52 | |
| 53 | /** |
| 54 | Creates the control and optionally sets the initial number of items in it |
| 55 | (it may also be set or changed later with wxVListBox::SetItemCount). |
| 56 | |
| 57 | There are no special styles defined for wxHtmlListBox, in particular the |
| 58 | wxListBox styles (with the exception of @c wxLB_MULTIPLE) cannot be used here. |
| 59 | |
| 60 | Returns @true on success or @false if the control couldn't be created |
| 61 | */ |
| 62 | bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, |
| 63 | const wxPoint& pos = wxDefaultPosition, |
| 64 | const wxSize& size = wxDefaultSize, |
| 65 | long style = 0, |
| 66 | const wxString& name = wxHtmlListBoxNameStr); |
| 67 | |
| 68 | //@{ |
| 69 | /** |
| 70 | Returns the wxFileSystem used by the HTML parser of this object. |
| 71 | |
| 72 | The file system object is used to resolve the paths in HTML fragments |
| 73 | displayed in the control and you should use wxFileSystem::ChangePathTo |
| 74 | if you use relative paths for the images or other resources embedded in |
| 75 | your HTML. |
| 76 | */ |
| 77 | wxFileSystem& GetFileSystem() const; |
| 78 | const wxFileSystem& GetFileSystem() const; |
| 79 | //@} |
| 80 | |
| 81 | protected: |
| 82 | |
| 83 | /** |
| 84 | Called when the user clicks on hypertext link. Does nothing by default. |
| 85 | Overloading this method is deprecated; intercept the event instead. |
| 86 | |
| 87 | @param n |
| 88 | Index of the item containing the link. |
| 89 | @param link |
| 90 | Description of the link. |
| 91 | |
| 92 | @see wxHtmlLinkInfo. |
| 93 | */ |
| 94 | virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link); |
| 95 | |
| 96 | /** |
| 97 | This virtual function may be overridden to change the appearance of the |
| 98 | background of the selected cells in the same way as GetSelectedTextColour(). |
| 99 | |
| 100 | It should be rarely, if ever, used because wxVListBox::SetSelectionBackground |
| 101 | allows to change the selection background for all cells at once and doing |
| 102 | anything more fancy is probably going to look strangely. |
| 103 | |
| 104 | @see GetSelectedTextColour() |
| 105 | */ |
| 106 | virtual wxColour GetSelectedTextBgColour(const wxColour& colBg) const; |
| 107 | |
| 108 | /** |
| 109 | This virtual function may be overridden to customize the appearance of the |
| 110 | selected cells. It is used to determine how the colour @a colFg is going to |
| 111 | look inside selection. By default all original colours are completely ignored |
| 112 | and the standard, system-dependent, selection colour is used but the program |
| 113 | may wish to override this to achieve some custom appearance. |
| 114 | |
| 115 | @see GetSelectedTextBgColour(), |
| 116 | wxVListBox::SetSelectionBackground, wxSystemSettings::GetColour |
| 117 | */ |
| 118 | virtual wxColour GetSelectedTextColour(const wxColour& colFg) const; |
| 119 | |
| 120 | /** |
| 121 | This function may be overridden to decorate HTML returned by OnGetItem(). |
| 122 | */ |
| 123 | virtual wxString OnGetItemMarkup(size_t n) const; |
| 124 | |
| 125 | /** |
| 126 | This method must be implemented in the derived class and should return |
| 127 | the body (i.e. without @c html nor @c body tags) of the HTML fragment |
| 128 | for the given item. |
| 129 | |
| 130 | Note that this function should always return a text fragment for the @a n item |
| 131 | which renders with the same height both when it is selected and when it's not: |
| 132 | i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to |
| 133 | make the items appear differently when they are selected, then you should make |
| 134 | sure that the returned HTML fragment will render with the same height or else |
| 135 | you'll see some artifacts when the user selects an item. |
| 136 | */ |
| 137 | virtual wxString OnGetItem(size_t n) const = 0; |
| 138 | }; |
| 139 | |
| 140 | |
| 141 | |
| 142 | /** |
| 143 | @class wxSimpleHtmlListBox |
| 144 | |
| 145 | wxSimpleHtmlListBox is an implementation of wxHtmlListBox which |
| 146 | shows HTML content in the listbox rows. |
| 147 | |
| 148 | Unlike wxHtmlListBox, this is not an abstract class and thus it has the |
| 149 | advantage that you can use it without deriving your own class from it. |
| 150 | However, it also has the disadvantage that this is not a virtual control and |
| 151 | thus it's not well-suited for those cases where you need to show a huge number |
| 152 | of items: every time you add/insert a string, it will be stored internally |
| 153 | and thus will take memory. |
| 154 | |
| 155 | The interface exposed by wxSimpleHtmlListBox fully implements the |
| 156 | wxControlWithItems interface, thus you should refer to wxControlWithItems's |
| 157 | documentation for the API reference for adding/removing/retrieving items in |
| 158 | the listbox. Also note that the wxVListBox::SetItemCount function is |
| 159 | @c protected in wxSimpleHtmlListBox's context so that you cannot call it |
| 160 | directly, wxSimpleHtmlListBox will do it for you. |
| 161 | |
| 162 | Note: in case you need to append a lot of items to the control at once, make |
| 163 | sure to use the |
| 164 | @ref wxControlWithItems::Append "Append(const wxArrayString&)" function. |
| 165 | |
| 166 | Thus the only difference between a wxListBox and a wxSimpleHtmlListBox |
| 167 | is that the latter stores strings which can contain HTML fragments (see the |
| 168 | list of @ref overview_html_supptags "tags supported by wxHTML"). |
| 169 | |
| 170 | Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain |
| 171 | the @c \<html\> or @c \<body\> tags. |
| 172 | |
| 173 | @beginStyleTable |
| 174 | @style{wxHLB_DEFAULT_STYLE} |
| 175 | The default style: wxBORDER_SUNKEN |
| 176 | @style{wxHLB_MULTIPLE} |
| 177 | Multiple-selection list: the user can toggle multiple items on and off. |
| 178 | @endStyleTable |
| 179 | |
| 180 | |
| 181 | A wxSimpleHtmlListBox emits the same events used by wxListBox and by wxHtmlListBox. |
| 182 | |
| 183 | @beginEventEmissionTable |
| 184 | @event{EVT_LISTBOX(id, func)} |
| 185 | Process a @c wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the list |
| 186 | is selected. See wxCommandEvent. |
| 187 | @event{EVT_LISTBOX_DCLICK(id, func)} |
| 188 | Process a @c wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the listbox is |
| 189 | double-clicked. See wxCommandEvent. |
| 190 | @event{EVT_HTML_CELL_CLICKED(id, func)} |
| 191 | A wxHtmlCell was clicked. See wxHtmlCellEvent. |
| 192 | @event{EVT_HTML_CELL_HOVER(id, func)} |
| 193 | The mouse passed over a wxHtmlCell. See wxHtmlCellEvent. |
| 194 | @event{EVT_HTML_LINK_CLICKED(id, func)} |
| 195 | A wxHtmlCell which contains an hyperlink was clicked. See wxHtmlLinkEvent |
| 196 | @endEventTable |
| 197 | |
| 198 | @library{wxhtml} |
| 199 | @category{ctrl} |
| 200 | @appearance{simplehtmllistbox.png} |
| 201 | |
| 202 | @see wxSimpleHtmlListBox::Create |
| 203 | */ |
| 204 | class wxSimpleHtmlListBox : public wxHtmlListBox, |
| 205 | public wxItemContainer |
| 206 | { |
| 207 | public: |
| 208 | /** |
| 209 | Constructor, creating and showing the HTML list box. |
| 210 | |
| 211 | @param parent |
| 212 | Parent window. Must not be NULL. |
| 213 | @param id |
| 214 | Window identifier. A value of -1 indicates a default value. |
| 215 | @param pos |
| 216 | Window position. |
| 217 | If ::wxDefaultPosition is specified then a default position is chosen. |
| 218 | @param size |
| 219 | Window size. |
| 220 | If ::wxDefaultSize is specified then the window is sized appropriately. |
| 221 | @param n |
| 222 | Number of strings with which to initialise the control. |
| 223 | @param choices |
| 224 | An array of strings with which to initialise the control. |
| 225 | @param style |
| 226 | Window style. See wxHLB_* flags. |
| 227 | @param validator |
| 228 | Window validator. |
| 229 | @param name |
| 230 | Window name. |
| 231 | */ |
| 232 | wxSimpleHtmlListBox(wxWindow* parent, wxWindowID id, |
| 233 | const wxPoint& pos = wxDefaultPosition, |
| 234 | const wxSize& size = wxDefaultSize, |
| 235 | int n = 0, |
| 236 | const wxString choices[] = NULL, |
| 237 | long style = wxHLB_DEFAULT_STYLE, |
| 238 | const wxValidator& validator = wxDefaultValidator, |
| 239 | const wxString& name = wxSimpleHtmlListBoxNameStr); |
| 240 | |
| 241 | /** |
| 242 | Constructor, creating and showing the HTML list box. |
| 243 | |
| 244 | @param parent |
| 245 | Parent window. Must not be NULL. |
| 246 | @param id |
| 247 | Window identifier. A value of -1 indicates a default value. |
| 248 | @param pos |
| 249 | Window position. |
| 250 | @param size |
| 251 | Window size. If wxDefaultSize is specified then the window is sized appropriately. |
| 252 | @param choices |
| 253 | An array of strings with which to initialise the control. |
| 254 | @param style |
| 255 | Window style. See wxHLB_* flags. |
| 256 | @param validator |
| 257 | Window validator. |
| 258 | @param name |
| 259 | Window name. |
| 260 | */ |
| 261 | wxSimpleHtmlListBox(wxWindow* parent, wxWindowID id, |
| 262 | const wxPoint& pos, |
| 263 | const wxSize& size, |
| 264 | const wxArrayString& choices, |
| 265 | long style = wxHLB_DEFAULT_STYLE, |
| 266 | const wxValidator& validator = wxDefaultValidator, |
| 267 | const wxString& name = wxSimpleHtmlListBoxNameStr); |
| 268 | |
| 269 | /** |
| 270 | Default constructor, you must call Create() later. |
| 271 | */ |
| 272 | wxSimpleHtmlListBox(); |
| 273 | |
| 274 | /** |
| 275 | Frees the array of stored items and relative client data. |
| 276 | */ |
| 277 | virtual ~wxSimpleHtmlListBox(); |
| 278 | |
| 279 | //@{ |
| 280 | /** |
| 281 | Creates the HTML listbox for two-step construction. |
| 282 | See wxSimpleHtmlListBox() for further details. |
| 283 | */ |
| 284 | bool Create(wxWindow *parent, wxWindowID id, |
| 285 | const wxPoint& pos = wxDefaultPosition, |
| 286 | const wxSize& size = wxDefaultSize, |
| 287 | int n = 0, const wxString choices[] = NULL, |
| 288 | long style = wxHLB_DEFAULT_STYLE, |
| 289 | const wxValidator& validator = wxDefaultValidator, |
| 290 | const wxString& name = wxSimpleHtmlListBoxNameStr); |
| 291 | bool Create(wxWindow *parent, wxWindowID id, |
| 292 | const wxPoint& pos, |
| 293 | const wxSize& size, |
| 294 | const wxArrayString& choices, |
| 295 | long style = wxHLB_DEFAULT_STYLE, |
| 296 | const wxValidator& validator = wxDefaultValidator, |
| 297 | const wxString& name = wxSimpleHtmlListBoxNameStr); |
| 298 | //@} |
| 299 | }; |
| 300 | |