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