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{See also}
  34
  35 \helpref{wxSimpleHtmlListBox}{wxsimplehtmllistbox}
  36
  37
  38 \wxheading{Event handling}
  39
  40 To process input from a wxHtmlListBox, use these event handler macros to direct input to member
  41 functions 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
  58 Normal constructor which calls \helpref{Create()}{wxhtmllistboxcreate}
  59 internally.
  60
  61 \func{}{wxHtmlListBox}{\void}
  62
  63 Default constructor, you must call \helpref{Create()}{wxhtmllistboxcreate}
  64 later.
  65
  66
  67 \membersection{wxHtmlListBox::\destruct{wxHtmlListBox}}\label{wxhtmllistboxdtor}
  68
  69 \func{}{\destruct{wxHtmlListBox}}{\void}
  70
  71 Destructor 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
  78 Creates 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
  82 There are no special styles defined for wxHtmlListBox, in particular the
  83 wxListBox styles (with the exception of {\tt wxLB\_MULTIPLE}) can not be used here.
  84
  85 Returns {\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
  94 Returns the \helpref{wxFileSystem}{wxfilesystem} used by the HTML parser of
  95 this object. The file system object is used to resolve the paths in HTML
  96 fragments displayed in the control and you should use
  97 \helpref{wxFileSystem::ChangePathTo}{wxfilesystemchangepathto} if you use
  98 relative 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
 105 This virtual function may be overridden to change the appearance of the
 106 background of the selected cells in the same way as
 107 \helpref{GetSelectedTextColour}{wxhtmllistboxgetselectedtextcolour}.
 108
 109 It should be rarely, if ever, used because
 110 \helpref{SetSelectionBackground}{wxvlistboxsetselectionbackground} allows to
 111 change the selection background for all cells at once and doing anything more
 112 fancy 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
 123 This virtual function may be overridden to customize the appearance of the
 124 selected cells. It is used to determine how the colour {\it colFg} is going to
 125 look inside selection. By default all original colours are completely ignored
 126 and the standard, system-dependent, selection colour is used but the program
 127 may 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
 140 This method must be implemented in the derived class and should return
 141 the body (i.e. without {\tt <html>} nor {\tt <body>} tags) of the HTML fragment
 142 for the given item.
 143
 144 Note that this function should always return a text fragment for the \arg{n} item
 145 which renders with the same height both when it is selected and when it's not:
 146 i.e. if you call, inside your OnGetItem() implementation, {\tt IsSelected(n)} to
 147 make the items appear differently when they are selected, then you should make sure
 148 that the returned HTML fragment will render with the same height or else you'll
 149 see 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
 155 This 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
 162 Called when the user clicks on hypertext link. Does nothing by default.
 163 Overloading 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
 173 See also \helpref{wxHtmlLinkInfo}{wxhtmllinkinfo}.
 174
 175
 176
 177
 178
 179
 180
 181 %
 182 % wxSimpleHtmlListBox
 183 %
 184
 185
 186 \section{\class{wxSimpleHtmlListBox}}\label{wxsimplehtmllistbox}
 187
 188 wxSimpleHtmlListBox is an implementation of \helpref{wxHtmlListBox}{wxhtmllistbox} which
 189 shows HTML content in the listbox rows.
 190
 191 Unlike \helpref{wxHtmlListBox}{wxhtmllistbox}, this is not an abstract class and thus it
 192 has the advantage that you can use it without deriving your own class from it.
 193 However, it also has the disadvantage that this is not a virtual control and thus it's not
 194 well-suited for those cases where you need to show a huge number of items: every time you
 195 add/insert a string, it will be stored internally and thus will take memory.
 196
 197 The 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
 200 for adding/removing/retrieving items in the listbox.
 201 Also note that the \helpref{wxVListBox::SetItemCount}{wxvlistboxsetitemcount} function is
 202 {\tt protected} in wxSimpleHtmlListBox's context so that you cannot call it directly,
 203 wxSimpleHtmlListBox will do it for you.
 204
 205 Note: 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
 208 Thus the only difference between a \helpref{wxListBox}{wxlistbox} and a wxSimpleHtmlListBox
 209 is that the latter stores strings which can contain HTML fragments (see the list of
 210 \helpref{tags supported by wxHTML}{htmltagssupported}).
 211
 212 Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain the {\tt <html>}
 213 or {\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
 236 items on and off.}
 237 \end{twocollist}
 238
 239 See also \helpref{window styles overview}{windowstyles}.
 240
 241 \wxheading{Event handling}
 242
 243 A wxSimpleHtmlListBox emits the same events used by \helpref{wxListBox}{wxlistbox} and by
 244 \helpref{wxHtmlListBox}{wxhtmllistbox}.
 245
 246 The 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,
 251 when an item on the list is selected.}
 252 \twocolitem{{\bf EVT\_LISTBOX\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_DOUBLECLICKED event,
 253 when the listbox is double-clicked.}
 254 \end{twocollist}
 255
 256 The event handlers for the following events take a \helpref{wxHtmlCellEvent}{wxhtmlcellevent}
 257 or 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
 284 Constructor, 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
 295 appropriately.}
 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
 315 Default constructor, you must call \helpref{Create()}{wxsimplehtmllistboxcreate}
 316 later.
 317
 318
 319 \membersection{wxSimpleHtmlListBox::\destruct{wxSimpleHtmlListBox}}\label{wxsimplehtmllistboxdtor}
 320
 321 \func{}{\destruct{wxSimpleHtmlListBox}}{\void}
 322
 323 Frees 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
 340 Creates the HTML listbox for two-step construction.
 341 See \helpref{wxSimpleHtmlListBox::wxSimpleHtmlListBox}{wxsimplehtmllistboxctor} for further details.
 342