interface/htmllbox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        htmllbox.h
   3 // Purpose:     documentation for wxHtmlListBox class
   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     @seealso
  24     wxSimpleHtmlListBox
  25 */
  26 class wxHtmlListBox : public wxVListBox
  27 {
  28 public:
  29     //@{
  30     /**
  31         Default constructor, you must call Create()
  32         later.
  33     */
  34     wxHtmlListBox(wxWindow* parent, wxWindowID id = wxID_ANY,
  35                   const wxPoint& pos = wxDefaultPosition,
  36                   const wxSize& size = wxDefaultSize,
  37                   long style = 0,
  38                   const wxString& name = wxHtmlListBoxNameStr);
  39     wxHtmlListBox();
  40     //@}
  41
  42     /**
  43         Destructor cleans up whatever resources we use.
  44     */
  45     ~wxHtmlListBox();
  46
  47     /**
  48         Creates the control and optionally sets the initial number of items in it
  49         (it may also be set or changed later with
  50         wxVListBox::SetItemCount).
  51         There are no special styles defined for wxHtmlListBox, in particular the
  52         wxListBox styles (with the exception of @c wxLB_MULTIPLE) can not be used here.
  53         Returns @true on success or @false if the control couldn't be created
  54     */
  55     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
  56                 const wxPoint& pos = wxDefaultPosition,
  57                 const wxSize& size = wxDefaultSize,
  58                 long style = 0,
  59                 const wxString& name = wxHtmlListBoxNameStr);
  60
  61     //@{
  62     /**
  63         Returns the wxFileSystem used by the HTML parser of
  64         this object. The file system object is used to resolve the paths in HTML
  65         fragments displayed in the control and you should use
  66         wxFileSystem::ChangePathTo if you use
  67         relative paths for the images or other resources embedded in your HTML.
  68     */
  69     wxFileSystem GetFileSystem();
  70     const wxFileSystem GetFileSystem();
  71     //@}
  72
  73     /**
  74         This virtual function may be overridden to change the appearance of the
  75         background of the selected cells in the same way as
  76         GetSelectedTextColour().
  77         It should be rarely, if ever, used because
  78         wxVListBox::SetSelectionBackground allows to
  79         change the selection background for all cells at once and doing anything more
  80         fancy is probably going to look strangely.
  81
  82         @see GetSelectedTextColour()
  83     */
  84     wxColour GetSelectedTextBgColour(const wxColour& colBg);
  85
  86     /**
  87         This virtual function may be overridden to customize the appearance of the
  88         selected cells. It is used to determine how the colour @a colFg is going to
  89         look inside selection. By default all original colours are completely ignored
  90         and the standard, system-dependent, selection colour is used but the program
  91         may wish to override this to achieve some custom appearance.
  92
  93         @see GetSelectedTextBgColour(),
  94              wxVListBox::SetSelectionBackground, wxSystemSettings::GetColour
  95     */
  96     wxColour GetSelectedTextColour(const wxColour& colFg);
  97
  98     /**
  99         This method must be implemented in the derived class and should return
 100         the body (i.e. without @c html nor @c body tags) of the HTML fragment
 101         for the given item.
 102         Note that this function should always return a text fragment for the @a n item
 103         which renders with the same height both when it is selected and when it's not:
 104         i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to
 105         make the items appear differently when they are selected, then you should make
 106         sure
 107         that the returned HTML fragment will render with the same height or else you'll
 108         see some artifacts when the user selects an item.
 109     */
 110     wxString OnGetItem(size_t n);
 111
 112     /**
 113         This function may be overridden to decorate HTML returned by
 114         OnGetItem().
 115     */
 116     wxString OnGetItemMarkup(size_t n);
 117
 118     /**
 119         Called when the user clicks on hypertext link. Does nothing by default.
 120         Overloading this method is deprecated; intercept the event instead.
 121
 122         @param n
 123             Index of the item containing the link.
 124         @param link
 125             Description of the link.
 126
 127         @see See also wxHtmlLinkInfo.
 128     */
 129     virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link);
 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     @seealso
 183     wxSimpleHtmlListBox::Create
 184 */
 185 class wxSimpleHtmlListBox : public wxHtmlListBox
 186 {
 187 public:
 188     //@{
 189     /**
 190         Default constructor, you must call Create()
 191         later.
 192     */
 193     wxHtmlListBox(wxWindow* parent, wxWindowID id,
 194                   const wxPoint& pos = wxDefaultPosition,
 195                   const wxSize& size = wxDefaultSize,
 196                   int n = 0,
 197                   const wxString choices[] = NULL,
 198                   long style = wxHLB_DEFAULT_STYLE,
 199                   const wxValidator& validator = wxDefaultValidator,
 200                   const wxString& name = "simpleHtmlListBox");
 201     wxHtmlListBox(wxWindow* parent, wxWindowID id,
 202                   const wxPoint& pos,
 203                   const wxSize& size,
 204                   const wxArrayString& choices,
 205                   long style = wxHLB_DEFAULT_STYLE,
 206                   const wxValidator& validator = wxDefaultValidator,
 207                   const wxString& name = "simpleHtmlListBox");
 208     See also
 209     wxSimpleHtmlListBox::Create
 210
 211     wxSimpleHtmlListBox();
 212     //@}
 213
 214     /**
 215         Frees the array of stored items and relative client data.
 216     */
 217     ~wxSimpleHtmlListBox();
 218
 219     //@{
 220     /**
 221         Creates the HTML listbox for two-step construction.
 222         See wxSimpleHtmlListBox() for further details.
 223     */
 224     bool Create(wxWindow* parent, wxWindowID id,
 225                 const wxPoint& pos = wxDefaultPosition,
 226                 const wxSize& size = wxDefaultSize,
 227                 int n,
 228                 const wxString choices[] = NULL,
 229                 long style = wxHLB_DEFAULT_STYLE,
 230                 const wxValidator& validator = wxDefaultValidator,
 231                 const wxString& name = "simpleHtmlListBox");
 232     bool Create(wxWindow* parent, wxWindowID id,
 233                 const wxPoint& pos,
 234                 const wxSize& size,
 235                 const wxArrayString& choices,
 236                 long style = wxHLB_DEFAULT_STYLE,
 237                 const wxValidator& validator = wxDefaultValidator,
 238                 const wxString& name = "simpleHtmlListBox");
 239     //@}
 240 };