docs/latex/wx/htmllbox.tex

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