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