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     ~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     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     wxColour GetSelectedTextColour(const wxColour& colFg) const;
  95
  96     /**
  97         This method must be implemented in the derived class and should return
  98         the body (i.e. without @c html nor @c body tags) of the HTML fragment
  99         for the given item.
 100         Note that this function should always return a text fragment for the @a n item
 101         which renders with the same height both when it is selected and when it's not:
 102         i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to
 103         make the items appear differently when they are selected, then you should make
 104         sure
 105         that the returned HTML fragment will render with the same height or else you'll
 106         see some artifacts when the user selects an item.
 107     */
 108     wxString OnGetItem(size_t n) const;
 109
 110     /**
 111         This function may be overridden to decorate HTML returned by
 112         OnGetItem().
 113     */
 114     wxString OnGetItemMarkup(size_t n) const;
 115
 116     /**
 117         Called when the user clicks on hypertext link. Does nothing by default.
 118         Overloading this method is deprecated; intercept the event instead.
 119
 120         @param n
 121             Index of the item containing the link.
 122         @param link
 123             Description of the link.
 124
 125         @see See also wxHtmlLinkInfo.
 126     */
 127     virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link);
 128 };
 129
 130
 131
 132 /**
 133     @class wxSimpleHtmlListBox
 134
 135     wxSimpleHtmlListBox is an implementation of wxHtmlListBox which
 136     shows HTML content in the listbox rows.
 137
 138     Unlike wxHtmlListBox, this is not an abstract class and thus it
 139     has the advantage that you can use it without deriving your own class from it.
 140     However, it also has the disadvantage that this is not a virtual control and
 141     thus it's not
 142     well-suited for those cases where you need to show a huge number of items:
 143     every time you
 144     add/insert a string, it will be stored internally and thus will take memory.
 145
 146     The interface exposed by wxSimpleHtmlListBox fully implements the
 147     wxControlWithItems interface, thus you should refer to
 148     wxControlWithItems's documentation for the API reference
 149     for adding/removing/retrieving items in the listbox.
 150     Also note that the wxVListBox::SetItemCount function is
 151     @c protected in wxSimpleHtmlListBox's context so that you cannot call it
 152     directly,
 153     wxSimpleHtmlListBox will do it for you.
 154
 155     Note: in case you need to append a lot of items to the control at once, make
 156     sure to use the
 157     @ref wxControlWithItems::append "Append(const wxArrayString )" function.
 158
 159     Thus the only difference between a wxListBox and a wxSimpleHtmlListBox
 160     is that the latter stores strings which can contain HTML fragments (see the
 161     list of
 162     @ref overview_htmltagssupported "tags supported by wxHTML").
 163
 164     Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain
 165     the @c html
 166     or @c body tags.
 167
 168     @beginStyleTable
 169     @style{wxHLB_DEFAULT_STYLE}
 170            The default style: wxBORDER_SUNKEN
 171     @style{wxHLB_MULTIPLE}
 172            Multiple-selection list: the user can toggle multiple items on and
 173            off.
 174     @endStyleTable
 175
 176     @library{wxhtml}
 177     @category{ctrl}
 178     <!-- @appearance{simplehtmllistbox.png} -->
 179
 180     @see wxSimpleHtmlListBox::Create
 181 */
 182 class wxSimpleHtmlListBox : public wxHtmlListBox
 183 {
 184 public:
 185     //@{
 186     /**
 187         Default constructor, you must call Create()
 188         later.
 189     */
 190     wxHtmlListBox(wxWindow* parent, wxWindowID id,
 191                   const wxPoint& pos = wxDefaultPosition,
 192                   const wxSize& size = wxDefaultSize,
 193                   int n = 0,
 194                   const wxString choices[] = NULL,
 195                   long style = wxHLB_DEFAULT_STYLE,
 196                   const wxValidator& validator = wxDefaultValidator,
 197                   const wxString& name = "simpleHtmlListBox");
 198     wxHtmlListBox(wxWindow* parent, wxWindowID id,
 199                   const wxPoint& pos,
 200                   const wxSize& size,
 201                   const wxArrayString& choices,
 202                   long style = wxHLB_DEFAULT_STYLE,
 203                   const wxValidator& validator = wxDefaultValidator,
 204                   const wxString& name = "simpleHtmlListBox");
 205     See also
 206     wxSimpleHtmlListBox::Create
 207
 208     wxSimpleHtmlListBox();
 209     //@}
 210
 211     /**
 212         Frees the array of stored items and relative client data.
 213     */
 214     ~wxSimpleHtmlListBox();
 215
 216     //@{
 217     /**
 218         Creates the HTML listbox for two-step construction.
 219         See wxSimpleHtmlListBox() for further details.
 220     */
 221     bool Create(wxWindow* parent, wxWindowID id,
 222                 const wxPoint& pos = wxDefaultPosition,
 223                 const wxSize& size = wxDefaultSize,
 224                 int n,
 225                 const wxString choices[] = NULL,
 226                 long style = wxHLB_DEFAULT_STYLE,
 227                 const wxValidator& validator = wxDefaultValidator,
 228                 const wxString& name = "simpleHtmlListBox");
 229     bool Create(wxWindow* parent, wxWindowID id,
 230                 const wxPoint& pos,
 231                 const wxSize& size,
 232                 const wxArrayString& choices,
 233                 long style = wxHLB_DEFAULT_STYLE,
 234                 const wxValidator& validator = wxDefaultValidator,
 235                 const wxString& name = "simpleHtmlListBox");
 236     //@}
 237 };
 238