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