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