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