interface/wx/htmllbox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        htmllbox.h
   3 // Purpose:     interface of wxHtmlListBox
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxHtmlListBox
  10
  11     wxHtmlListBox is an implementation of wxVListBox which shows HTML content in
  12     the listbox rows. This is still an abstract base class and you will need to
  13     derive your own class from it (see htlbox sample for the example) but you will
  14     only need to override a single wxHtmlListBox::OnGetItem function.
  15
  16     @beginEventEmissionTable{wxHtmlCellEvent,wxHtmlLinkEvent}
  17     @event{EVT_HTML_CELL_CLICKED(id, func)}
  18         A wxHtmlCell was clicked.
  19     @event{EVT_HTML_CELL_HOVER(id, func)}
  20         The mouse passed over a wxHtmlCell.
  21     @event{EVT_HTML_LINK_CLICKED(id, func)}
  22         A wxHtmlCell which contains an hyperlink was clicked.
  23     @endEventTable
  24
  25     @library{wxhtml}
  26     @category{ctrl}
  27
  28     @see wxSimpleHtmlListBox
  29 */
  30 class wxHtmlListBox : public wxVListBox
  31 {
  32 public:
  33     /**
  34         Normal constructor which calls Create() internally.
  35     */
  36     wxHtmlListBox(wxWindow* parent, wxWindowID id = wxID_ANY,
  37                   const wxPoint& pos = wxDefaultPosition,
  38                   const wxSize& size = wxDefaultSize,
  39                   long style = 0,
  40                   const wxString& name = wxHtmlListBoxNameStr);
  41
  42     /**
  43         Default constructor, you must call Create() later.
  44     */
  45     wxHtmlListBox();
  46
  47     /**
  48         Destructor cleans up whatever resources we use.
  49     */
  50     virtual ~wxHtmlListBox();
  51
  52     /**
  53         Creates the control and optionally sets the initial number of items in it
  54         (it may also be set or changed later with wxVListBox::SetItemCount).
  55
  56         There are no special styles defined for wxHtmlListBox, in particular the
  57         wxListBox styles (with the exception of @c wxLB_MULTIPLE) cannot be used here.
  58
  59         Returns @true on success or @false if the control couldn't be created
  60     */
  61     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
  62                 const wxPoint& pos = wxDefaultPosition,
  63                 const wxSize& size = wxDefaultSize,
  64                 long style = 0,
  65                 const wxString& name = wxHtmlListBoxNameStr);
  66
  67     //@{
  68     /**
  69         Returns the wxFileSystem used by the HTML parser of this object.
  70
  71         The file system object is used to resolve the paths in HTML fragments
  72         displayed in the control and you should use wxFileSystem::ChangePathTo
  73         if you use relative paths for the images or other resources embedded in
  74         your HTML.
  75     */
  76     wxFileSystem& GetFileSystem() const;
  77     const wxFileSystem& GetFileSystem() const;
  78     //@}
  79
  80 protected:
  81
  82     /**
  83         Called when the user clicks on hypertext link. Does nothing by default.
  84         Overloading this method is deprecated; intercept the event instead.
  85
  86         @param n
  87             Index of the item containing the link.
  88         @param link
  89             Description of the link.
  90
  91         @see wxHtmlLinkInfo.
  92     */
  93     virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link);
  94
  95     /**
  96         This virtual function may be overridden to change the appearance of the
  97         background of the selected cells in the same way as GetSelectedTextColour().
  98
  99         It should be rarely, if ever, used because wxVListBox::SetSelectionBackground
 100         allows to change the selection background for all cells at once and doing
 101         anything more fancy is probably going to look strangely.
 102
 103         @see GetSelectedTextColour()
 104     */
 105     virtual wxColour GetSelectedTextBgColour(const wxColour& colBg) const;
 106
 107     /**
 108         This virtual function may be overridden to customize the appearance of the
 109         selected cells. It is used to determine how the colour @a colFg is going to
 110         look inside selection. By default all original colours are completely ignored
 111         and the standard, system-dependent, selection colour is used but the program
 112         may wish to override this to achieve some custom appearance.
 113
 114         @see GetSelectedTextBgColour(),
 115              wxVListBox::SetSelectionBackground, wxSystemSettings::GetColour
 116     */
 117     virtual wxColour GetSelectedTextColour(const wxColour& colFg) const;
 118
 119     /**
 120         This function may be overridden to decorate HTML returned by OnGetItem().
 121     */
 122     virtual wxString OnGetItemMarkup(size_t n) const;
 123
 124     /**
 125         This method must be implemented in the derived class and should return
 126         the body (i.e. without @c html nor @c body tags) of the HTML fragment
 127         for the given item.
 128
 129         Note that this function should always return a text fragment for the @a n item
 130         which renders with the same height both when it is selected and when it's not:
 131         i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to
 132         make the items appear differently when they are selected, then you should make
 133         sure that the returned HTML fragment will render with the same height or else
 134         you'll see some artifacts when the user selects an item.
 135     */
 136     virtual wxString OnGetItem(size_t n) const = 0;
 137 };
 138
 139
 140
 141 /**
 142     @class wxSimpleHtmlListBox
 143
 144     wxSimpleHtmlListBox is an implementation of wxHtmlListBox which
 145     shows HTML content in the listbox rows.
 146
 147     Unlike wxHtmlListBox, this is not an abstract class and thus it has the
 148     advantage that you can use it without deriving your own class from it.
 149     However, it also has the disadvantage that this is not a virtual control and
 150     thus it's not well-suited for those cases where you need to show a huge number
 151     of items: every time you add/insert a string, it will be stored internally
 152     and thus will take memory.
 153
 154     The interface exposed by wxSimpleHtmlListBox fully implements the
 155     wxControlWithItems interface, thus you should refer to wxControlWithItems's
 156     documentation for the API reference for adding/removing/retrieving items in
 157     the listbox. Also note that the wxVListBox::SetItemCount function is
 158     @c protected in wxSimpleHtmlListBox's context so that you cannot call it
 159     directly, wxSimpleHtmlListBox will do it for you.
 160
 161     Note: in case you need to append a lot of items to the control at once, make
 162     sure to use the
 163     @ref wxControlWithItems::Append "Append(const wxArrayString&)" function.
 164
 165     Thus the only difference between a wxListBox and a wxSimpleHtmlListBox
 166     is that the latter stores strings which can contain HTML fragments (see the
 167     list of @ref overview_html_supptags "tags supported by wxHTML").
 168
 169     Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain
 170     the @c \<html\> or @c \<body\> tags.
 171
 172     @beginStyleTable
 173     @style{wxHLB_DEFAULT_STYLE}
 174            The default style: wxBORDER_SUNKEN
 175     @style{wxHLB_MULTIPLE}
 176            Multiple-selection list: the user can toggle multiple items on and off.
 177     @endStyleTable
 178
 179
 180     A wxSimpleHtmlListBox emits the same events used by wxListBox and by wxHtmlListBox.
 181
 182     @beginEventEmissionTable
 183     @event{EVT_LISTBOX(id, func)}
 184         Process a @c wxEVT_LISTBOX event, when an item on the list
 185         is selected. See wxCommandEvent.
 186     @event{EVT_LISTBOX_DCLICK(id, func)}
 187         Process a @c wxEVT_LISTBOX_DCLICK event, when the listbox is
 188         double-clicked. See wxCommandEvent.
 189     @event{EVT_HTML_CELL_CLICKED(id, func)}
 190         A wxHtmlCell was clicked. See wxHtmlCellEvent.
 191     @event{EVT_HTML_CELL_HOVER(id, func)}
 192         The mouse passed over a wxHtmlCell. See wxHtmlCellEvent.
 193     @event{EVT_HTML_LINK_CLICKED(id, func)}
 194         A wxHtmlCell which contains an hyperlink was clicked. See wxHtmlLinkEvent
 195     @endEventTable
 196
 197     @library{wxhtml}
 198     @category{ctrl}
 199     @genericAppearance{simplehtmllistbox}
 200
 201     @see wxSimpleHtmlListBox::Create
 202 */
 203 class wxSimpleHtmlListBox : public wxHtmlListBox,
 204                             public wxItemContainer
 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