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     @beginEventEmissionTable{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     @beginEventEmissionTable
 184     @event{EVT_LISTBOX(id, func)}
 185         Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the list
 186         is selected. See wxCommandEvent.
 187     @event{EVT_LISTBOX_DCLICK(id, func)}
 188         Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the listbox is
 189         double-clicked. See wxCommandEvent.
 190     @event{EVT_HTML_CELL_CLICKED(id, func)}
 191         A wxHtmlCell was clicked. See wxHtmlCellEvent.
 192     @event{EVT_HTML_CELL_HOVER(id, func)}
 193         The mouse passed over a wxHtmlCell. See wxHtmlCellEvent.
 194     @event{EVT_HTML_LINK_CLICKED(id, func)}
 195         A wxHtmlCell which contains an hyperlink was clicked. See wxHtmlLinkEvent
 196     @endEventTable
 197
 198     @library{wxhtml}
 199     @category{ctrl}
 200     @appearance{simplehtmllistbox.png}
 201
 202     @see wxSimpleHtmlListBox::Create
 203 */
 204 class wxSimpleHtmlListBox : public wxHtmlListBox
 205 {
 206 public:
 207     /**
 208         Constructor, creating and showing the HTML list box.
 209
 210         @param parent
 211             Parent window. Must not be NULL.
 212         @param id
 213             Window identifier. A value of -1 indicates a default value.
 214         @param pos
 215             Window position.
 216         @param size
 217             Window size. If wxDefaultSize is specified then the window is sized appropriately.
 218         @param n
 219             Number of strings with which to initialise the control.
 220         @param choices
 221             An array of strings with which to initialise the control.
 222         @param style
 223             Window style. See wxHLB_* flags.
 224         @param validator
 225             Window validator.
 226         @param name
 227             Window name.
 228     */
 229     wxSimpleHtmlListBox(wxWindow* parent, wxWindowID id,
 230                         const wxPoint& pos = wxDefaultPosition,
 231                         const wxSize& size = wxDefaultSize,
 232                         int n = 0,
 233                         const wxString choices[] = NULL,
 234                         long style = wxHLB_DEFAULT_STYLE,
 235                         const wxValidator& validator = wxDefaultValidator,
 236                         const wxString& name = wxSimpleHtmlListBoxNameStr);
 237
 238     /**
 239         Constructor, creating and showing the HTML list box.
 240
 241         @param parent
 242             Parent window. Must not be NULL.
 243         @param id
 244             Window identifier. A value of -1 indicates a default value.
 245         @param pos
 246             Window position.
 247         @param size
 248             Window size. If wxDefaultSize is specified then the window is sized appropriately.
 249         @param choices
 250             An array of strings with which to initialise the control.
 251         @param style
 252             Window style. See wxHLB_* flags.
 253         @param validator
 254             Window validator.
 255         @param name
 256             Window name.
 257     */
 258     wxSimpleHtmlListBox(wxWindow* parent, wxWindowID id,
 259                         const wxPoint& pos,
 260                         const wxSize& size,
 261                         const wxArrayString& choices,
 262                         long style = wxHLB_DEFAULT_STYLE,
 263                         const wxValidator& validator = wxDefaultValidator,
 264                         const wxString& name = wxSimpleHtmlListBoxNameStr);
 265
 266     /**
 267         Default constructor, you must call Create() later.
 268     */
 269     wxSimpleHtmlListBox();
 270
 271     /**
 272         Frees the array of stored items and relative client data.
 273     */
 274     virtual ~wxSimpleHtmlListBox();
 275
 276     //@{
 277     /**
 278         Creates the HTML listbox for two-step construction.
 279         See wxSimpleHtmlListBox() for further details.
 280     */
 281     bool Create(wxWindow *parent, wxWindowID id,
 282                 const wxPoint& pos = wxDefaultPosition,
 283                 const wxSize& size = wxDefaultSize,
 284                 int n = 0, const wxString choices[] = NULL,
 285                 long style = wxHLB_DEFAULT_STYLE,
 286                 const wxValidator& validator = wxDefaultValidator,
 287                 const wxString& name = wxSimpleHtmlListBoxNameStr);
 288     bool Create(wxWindow *parent, wxWindowID id,
 289                 const wxPoint& pos,
 290                 const wxSize& size,
 291                 const wxArrayString& choices,
 292                 long style = wxHLB_DEFAULT_STYLE,
 293                 const wxValidator& validator = wxDefaultValidator,
 294                 const wxString& name = wxSimpleHtmlListBoxNameStr);
 295     //@}
 296 };
 297