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