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