interface/htmllbox.h

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