1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: htmllbox.tex 3%% Purpose: wxHtmlListBox and wxSimpleHtmlListBox documentation 4%% Author: Vadim Zeitlin 5%% Modified by: 6%% Created: 01.06.03 7%% RCS-ID: $Id: htmllbox.tex 43749 2006-12-02 18:35:55Z VZ $ 8%% Copyright: (c) 2003 Vadim Zeitlin <vadim@wxwindows.org> 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxHtmlListBox}}\label{wxhtmllistbox} 13 14wxHtmlListBox is an implementation of \helpref{wxVListBox}{wxvlistbox} which 15shows HTML content in the listbox rows. This is still an abstract base class 16and you will need to derive your own class from it (see htlbox sample for the 17example) but you will only need to override a single 18\helpref{OnGetItem()}{wxhtmllistboxongetitem} function. 19 20\wxheading{Derived from} 21 22\helpref{wxVListBox}{wxvlistbox}\\ 23\helpref{wxVScrolledWindow}{wxvscrolledwindow}\\ 24\helpref{wxPanel}{wxpanel}\\ 25\helpref{wxWindow}{wxwindow}\\ 26\helpref{wxEvtHandler}{wxevthandler}\\ 27\helpref{wxObject}{wxobject} 28 29\wxheading{Include files} 30 31<wx/htmllbox.h> 32 33\wxheading{See also} 34 35\helpref{wxSimpleHtmlListBox}{wxsimplehtmllistbox} 36 37 38\wxheading{Event handling} 39 40To process input from a wxHtmlListBox, use these event handler macros to direct input to member 41functions that take a \helpref{wxHtmlCellEvent}{wxhtmlcellevent} argument or a \helpref{wxHtmlLinkEvent}{wxhtmllinkevent}. 42 43\twocolwidtha{7cm} 44\begin{twocollist}\itemsep=0pt 45\twocolitem{{\bf EVT\_HTML\_CELL\_CLICKED(id, func)}}{A \helpref{wxHtmlCell}{wxhtmlcell} was clicked.} 46\twocolitem{{\bf EVT\_HTML\_CELL\_HOVER(id, func)}}{The mouse passed over a \helpref{wxHtmlCell}{wxhtmlcell}.} 47\twocolitem{{\bf EVT\_HTML\_LINK\_CLICKED(id, func)}}{A \helpref{wxHtmlCell}{wxhtmlcell} which contains an hyperlink was clicked.} 48\end{twocollist} 49 50 51\latexignore{\rtfignore{\wxheading{Members}}} 52 53 54\membersection{wxHtmlListBox::wxHtmlListBox}\label{wxhtmllistboxwxhtmllistbox} 55 56\func{}{wxHtmlListBox}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxHtmlListBoxNameStr}} 57 58Normal constructor which calls \helpref{Create()}{wxhtmllistboxcreate} 59internally. 60 61\func{}{wxHtmlListBox}{\void} 62 63Default constructor, you must call \helpref{Create()}{wxhtmllistboxcreate} 64later. 65 66 67\membersection{wxHtmlListBox::\destruct{wxHtmlListBox}}\label{wxhtmllistboxdtor} 68 69\func{}{\destruct{wxHtmlListBox}}{\void} 70 71Destructor cleans up whatever resources we use. 72 73 74\membersection{wxHtmlListBox::Create}\label{wxhtmllistboxcreate} 75 76\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxHtmlListBoxNameStr}} 77 78Creates the control and optionally sets the initial number of items in it 79(it may also be set or changed later with 80\helpref{SetItemCount()}{wxvlistboxsetitemcount}). 81 82There are no special styles defined for wxHtmlListBox, in particular the 83wxListBox styles (with the exception of {\tt wxLB\_MULTIPLE}) can not be used here. 84 85Returns {\tt true} on success or {\tt false} if the control couldn't be created 86 87 88\membersection{wxHtmlListBox::GetFileSystem}\label{wxhtmllistboxgetfilesystem} 89 90\func{wxFileSystem\&}{GetFileSystem}{\void} 91 92\constfunc{const wxFileSystem\&}{GetFileSystem}{\void} 93 94Returns the \helpref{wxFileSystem}{wxfilesystem} used by the HTML parser of 95this object. The file system object is used to resolve the paths in HTML 96fragments displayed in the control and you should use 97\helpref{wxFileSystem::ChangePathTo}{wxfilesystemchangepathto} if you use 98relative paths for the images or other resources embedded in your HTML. 99 100 101\membersection{wxHtmlListBox::GetSelectedTextBgColour}\label{wxhtmllistboxgetselectedtextbgcolour} 102 103\constfunc{wxColour}{GetSelectedTextBgColour}{\param{const wxColour\& }{colBg}} 104 105This virtual function may be overridden to change the appearance of the 106background of the selected cells in the same way as 107\helpref{GetSelectedTextColour}{wxhtmllistboxgetselectedtextcolour}. 108 109It should be rarely, if ever, used because 110\helpref{SetSelectionBackground}{wxvlistboxsetselectionbackground} allows to 111change the selection background for all cells at once and doing anything more 112fancy is probably going to look strangely. 113 114\wxheading{See also} 115 116\helpref{GetSelectedTextColour}{wxhtmllistboxgetselectedtextcolour} 117 118 119\membersection{wxHtmlListBox::GetSelectedTextColour}\label{wxhtmllistboxgetselectedtextcolour} 120 121\constfunc{wxColour}{GetSelectedTextColour}{\param{const wxColour\& }{colFg}} 122 123This virtual function may be overridden to customize the appearance of the 124selected cells. It is used to determine how the colour {\it colFg} is going to 125look inside selection. By default all original colours are completely ignored 126and the standard, system-dependent, selection colour is used but the program 127may wish to override this to achieve some custom appearance. 128 129\wxheading{See also} 130 131\helpref{GetSelectedTextBgColour}{wxhtmllistboxgetselectedtextbgcolour},\\ 132\helpref{SetSelectionBackground}{wxvlistboxsetselectionbackground},\\ 133\helpref{wxSystemSettings::GetColour}{wxsystemsettingsgetcolour} 134 135 136\membersection{wxHtmlListBox::OnGetItem}\label{wxhtmllistboxongetitem} 137 138\constfunc{wxString}{OnGetItem}{\param{size\_t }{n}} 139 140This method must be implemented in the derived class and should return 141the body (i.e. without {\tt <html>} nor {\tt <body>} tags) of the HTML fragment 142for the given item. 143 144Note that this function should always return a text fragment for the \arg{n} item 145which renders with the same height both when it is selected and when it's not: 146i.e. if you call, inside your OnGetItem() implementation, {\tt IsSelected(n)} to 147make the items appear differently when they are selected, then you should make sure 148that the returned HTML fragment will render with the same height or else you'll 149see some artifacts when the user selects an item. 150 151\membersection{wxHtmlListBox::OnGetItemMarkup}\label{wxhtmllistboxongetitemmarkup} 152 153\constfunc{wxString}{OnGetItemMarkup}{\param{size\_t }{n}} 154 155This function may be overridden to decorate HTML returned by 156\helpref{OnGetItem()}{wxhtmllistboxongetitem}. 157 158\membersection{wxHtmlListBox::OnLinkClicked}\label{wxhtmlistboxonlinkclicked} 159 160\func{virtual void}{OnLinkClicked}{\param{size\_t }{n}, \param{const wxHtmlLinkInfo\& }{link}} 161 162Called when the user clicks on hypertext link. Does nothing by default. 163Overloading this method is deprecated; intercept the event instead. 164 165\wxheading{Parameters} 166 167\docparam{n}{Index of the item containing the link.} 168 169\docparam{link}{Description of the link.} 170 171\wxheading{See also} 172 173See also \helpref{wxHtmlLinkInfo}{wxhtmllinkinfo}. 174 175 176 177 178 179 180 181% 182% wxSimpleHtmlListBox 183% 184 185 186\section{\class{wxSimpleHtmlListBox}}\label{wxsimplehtmllistbox} 187 188wxSimpleHtmlListBox is an implementation of \helpref{wxHtmlListBox}{wxhtmllistbox} which 189shows HTML content in the listbox rows. 190 191Unlike \helpref{wxHtmlListBox}{wxhtmllistbox}, this is not an abstract class and thus it 192has the advantage that you can use it without deriving your own class from it. 193However, it also has the disadvantage that this is not a virtual control and thus it's not 194well-suited for those cases where you need to show a huge number of items: every time you 195add/insert a string, it will be stored internally and thus will take memory. 196 197The interface exposed by wxSimpleHtmlListBox fully implements the 198\helpref{wxControlWithItems}{wxcontrolwithitems} interface, thus you should refer to 199\helpref{wxControlWithItems}{wxcontrolwithitems}'s documentation for the API reference 200for adding/removing/retrieving items in the listbox. 201Also note that the \helpref{wxVListBox::SetItemCount}{wxvlistboxsetitemcount} function is 202{\tt protected} in wxSimpleHtmlListBox's context so that you cannot call it directly, 203wxSimpleHtmlListBox will do it for you. 204 205Note: in case you need to append a lot of items to the control at once, make sure to use the 206\helpref{Append(const wxArrayString \&)}{wxcontrolwithitemsappend} function. 207 208Thus the only difference between a \helpref{wxListBox}{wxlistbox} and a wxSimpleHtmlListBox 209is that the latter stores strings which can contain HTML fragments (see the list of 210\helpref{tags supported by wxHTML}{htmltagssupported}). 211 212Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain the {\tt <html>} 213or {\tt <body>} tags. 214 215 216\wxheading{Derived from} 217 218\helpref{wxHtmlListBox}{wxhtmllistbox}, \helpref{wxControlWithItems}{wxcontrolwithitems}\\ 219\helpref{wxVListBox}{wxvlistbox}\\ 220\helpref{wxVScrolledWindow}{wxvscrolledwindow}\\ 221\helpref{wxPanel}{wxpanel}\\ 222\helpref{wxWindow}{wxwindow}\\ 223\helpref{wxEvtHandler}{wxevthandler}\\ 224\helpref{wxObject}{wxobject} 225 226\wxheading{Include files} 227 228<wx/htmllbox.h> 229 230\wxheading{Window styles} 231 232\twocolwidtha{5cm}% 233\begin{twocollist}\itemsep=0pt 234\twocolitem{\windowstyle{wxHLB\_DEFAULT\_STYLE}}{The default style: wxSUNKEN\_BORDER} 235\twocolitem{\windowstyle{wxHLB\_MULTIPLE}}{Multiple-selection list: the user can toggle multiple 236items on and off.} 237\end{twocollist} 238 239See also \helpref{window styles overview}{windowstyles}. 240 241\wxheading{Event handling} 242 243A wxSimpleHtmlListBox emits the same events used by \helpref{wxListBox}{wxlistbox} and by 244\helpref{wxHtmlListBox}{wxhtmllistbox}. 245 246The event handlers for the following events take a \helpref{wxCommandEvent}{wxcommandevent}: 247 248\twocolwidtha{7cm} 249\begin{twocollist}\itemsep=0pt 250\twocolitem{{\bf EVT\_LISTBOX(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_SELECTED event, 251when an item on the list is selected.} 252\twocolitem{{\bf EVT\_LISTBOX\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_DOUBLECLICKED event, 253when the listbox is double-clicked.} 254\end{twocollist} 255 256The event handlers for the following events take a \helpref{wxHtmlCellEvent}{wxhtmlcellevent} 257or a \helpref{wxHtmlLinkEvent}{wxhtmllinkevent}: 258 259\twocolwidtha{7cm} 260\begin{twocollist}\itemsep=0pt 261\twocolitem{{\bf EVT\_HTML\_CELL\_CLICKED(id, func)}}{A \helpref{wxHtmlCell}{wxhtmlcell} was clicked.} 262\twocolitem{{\bf EVT\_HTML\_CELL\_HOVER(id, func)}}{The mouse passed over a \helpref{wxHtmlCell}{wxhtmlcell}.} 263\twocolitem{{\bf EVT\_HTML\_LINK\_CLICKED(id, func)}}{A \helpref{wxHtmlCell}{wxhtmlcell} which contains an hyperlink was clicked.} 264\end{twocollist} 265 266 267\latexignore{\rtfignore{\wxheading{Members}}} 268 269 270\membersection{wxSimpleHtmlListBox::wxSimpleHtmlListBox}\label{wxsimplehtmllistboxctor} 271 272\func{}{wxHtmlListBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp 273\param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp 274\param{int}{ n = 0}, \param{const wxString }{choices[] = NULL},\rtfsp 275\param{long}{ style = wxHLB\_DEFAULT\_STYLE}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp 276\param{const wxString\& }{name = ``simpleHtmlListBox"}} 277 278\func{}{wxHtmlListBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp 279\param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp 280\param{const wxArrayString\& }{choices},\rtfsp 281\param{long}{ style = wxHLB\_DEFAULT\_STYLE}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp 282\param{const wxString\& }{name = ``simpleHtmlListBox"}} 283 284Constructor, creating and showing the HTML list box. 285 286\wxheading{Parameters} 287 288\docparam{parent}{Parent window. Must not be NULL.} 289 290\docparam{id}{Window identifier. A value of -1 indicates a default value.} 291 292\docparam{pos}{Window position.} 293 294\docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized 295appropriately.} 296 297\docparam{n}{Number of strings with which to initialise the control.} 298 299\docparam{choices}{An array of strings with which to initialise the control.} 300 301\docparam{style}{Window style. See {\tt wxHLB\_*} flags.} 302 303\docparam{validator}{Window validator.} 304 305\docparam{name}{Window name.} 306 307\wxheading{See also} 308 309\helpref{wxSimpleHtmlListBox::Create}{wxsimplehtmllistboxcreate} 310 311 312 313\func{}{wxSimpleHtmlListBox}{\void} 314 315Default constructor, you must call \helpref{Create()}{wxsimplehtmllistboxcreate} 316later. 317 318 319\membersection{wxSimpleHtmlListBox::\destruct{wxSimpleHtmlListBox}}\label{wxsimplehtmllistboxdtor} 320 321\func{}{\destruct{wxSimpleHtmlListBox}}{\void} 322 323Frees the array of stored items and relative client data. 324 325 326\membersection{wxSimpleHtmlListBox::Create}\label{wxsimplehtmllistboxcreate} 327 328\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp 329\param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp 330\param{int}{ n}, \param{const wxString }{choices[] = NULL},\rtfsp 331\param{long}{ style = wxHLB\_DEFAULT\_STYLE}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp 332\param{const wxString\& }{name = ``simpleHtmlListBox"}} 333 334\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp 335\param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp 336\param{const wxArrayString\& }{choices},\rtfsp 337\param{long}{ style = wxHLB\_DEFAULT\_STYLE}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp 338\param{const wxString\& }{name = ``simpleHtmlListBox"}} 339 340Creates the HTML listbox for two-step construction. 341See \helpref{wxSimpleHtmlListBox::wxSimpleHtmlListBox}{wxsimplehtmllistboxctor} for further details. 342 343