include/wx/htmllbox.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/htmllbox.h
   3 // Purpose:     wxHtmlListBox is a listbox whose items are wxHtmlCells
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     31.05.03
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2003 Vadim Zeitlin <vadim@wxwidgets.org>
   9 // Licence:     wxWindows licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_HTMLLBOX_H_
  13 #define _WX_HTMLLBOX_H_
  14
  15 #include "wx/vlbox.h"               // base class
  16 #include "wx/html/htmlwin.h"
  17 #include "wx/ctrlsub.h"
  18
  19 #if wxUSE_FILESYSTEM
  20     #include "wx/filesys.h"
  21 #endif // wxUSE_FILESYSTEM
  22
  23 class WXDLLIMPEXP_HTML wxHtmlCell;
  24 class WXDLLIMPEXP_HTML wxHtmlWinParser;
  25 class WXDLLIMPEXP_HTML wxHtmlListBoxCache;
  26 class WXDLLIMPEXP_HTML wxHtmlListBoxStyle;
  27
  28 extern WXDLLIMPEXP_DATA_HTML(const wxChar) wxHtmlListBoxNameStr[];
  29 extern WXDLLIMPEXP_DATA_HTML(const wxChar) wxSimpleHtmlListBoxNameStr[];
  30
  31 // ----------------------------------------------------------------------------
  32 // wxHtmlListBox
  33 // ----------------------------------------------------------------------------
  34
  35 class WXDLLIMPEXP_HTML wxHtmlListBox : public wxVListBox,
  36                                        public wxHtmlWindowInterface,
  37                                        public wxHtmlWindowMouseHelper
  38 {
  39     DECLARE_ABSTRACT_CLASS(wxHtmlListBox)
  40 public:
  41     // constructors and such
  42     // ---------------------
  43
  44     // default constructor, you must call Create() later
  45     wxHtmlListBox();
  46
  47     // normal constructor which calls Create() internally
  48     wxHtmlListBox(wxWindow *parent,
  49                   wxWindowID id = wxID_ANY,
  50                   const wxPoint& pos = wxDefaultPosition,
  51                   const wxSize& size = wxDefaultSize,
  52                   long style = 0,
  53                   const wxString& name = wxHtmlListBoxNameStr);
  54
  55     // really creates the control and sets the initial number of items in it
  56     // (which may be changed later with SetItemCount())
  57     //
  58     // the only special style which may be specified here is wxLB_MULTIPLE
  59     //
  60     // returns true on success or false if the control couldn't be created
  61     bool Create(wxWindow *parent,
  62                 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     // destructor cleans up whatever resources we use
  69     virtual ~wxHtmlListBox();
  70
  71     // override some base class virtuals
  72     virtual void RefreshLine(size_t line);
  73     virtual void RefreshLines(size_t from, size_t to);
  74     virtual void RefreshAll();
  75     virtual void SetItemCount(size_t count);
  76
  77     // provide a way to set the default encoding (non-Unicode only)
  78     void SetEncoding(wxFontEncoding encoding) { m_fontEncoding = encoding; }
  79     wxFontEncoding GetEncoding() { return m_fontEncoding; }
  80
  81 #if wxUSE_FILESYSTEM
  82     // retrieve the file system used by the wxHtmlWinParser: if you use
  83     // relative paths in your HTML, you should use its ChangePathTo() method
  84     wxFileSystem& GetFileSystem() { return m_filesystem; }
  85     const wxFileSystem& GetFileSystem() const { return m_filesystem; }
  86 #endif // wxUSE_FILESYSTEM
  87
  88     virtual void OnInternalIdle();
  89
  90 protected:
  91     // this method must be implemented in the derived class and should return
  92     // the body (i.e. without <html>) of the HTML for the given item
  93     virtual wxString OnGetItem(size_t n) const = 0;
  94
  95     // this function may be overridden to decorate HTML returned by OnGetItem()
  96     virtual wxString OnGetItemMarkup(size_t n) const;
  97
  98
  99     // this method allows to customize the selection appearance: it may be used
 100     // to specify the colour of the text which normally has the given colour
 101     // colFg when it is inside the selection
 102     //
 103     // by default, the original colour is not used at all and all text has the
 104     // same (default for this system) colour inside selection
 105     virtual wxColour GetSelectedTextColour(const wxColour& colFg) const;
 106
 107     // this is the same as GetSelectedTextColour() but allows to customize the
 108     // background colour -- this is even more rarely used as you can change it
 109     // globally using SetSelectionBackground()
 110     virtual wxColour GetSelectedTextBgColour(const wxColour& colBg) const;
 111
 112
 113     // we implement both of these functions in terms of OnGetItem(), they are
 114     // not supposed to be overridden by our descendants
 115     virtual void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n) const;
 116     virtual wxCoord OnMeasureItem(size_t n) const;
 117
 118     // This method may be overriden to handle clicking on a link in
 119     // the listbox. By default, clicking links is ignored.
 120     virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link);
 121
 122     // event handlers
 123     void OnSize(wxSizeEvent& event);
 124     void OnMouseMove(wxMouseEvent& event);
 125     void OnLeftDown(wxMouseEvent& event);
 126
 127
 128     // common part of all ctors
 129     void Init();
 130
 131     // ensure that the given item is cached
 132     void CacheItem(size_t n) const;
 133
 134 private:
 135     // wxHtmlWindowInterface methods:
 136     virtual void SetHTMLWindowTitle(const wxString& title);
 137     virtual void OnHTMLLinkClicked(const wxHtmlLinkInfo& link);
 138     virtual wxHtmlOpeningStatus OnHTMLOpeningURL(wxHtmlURLType type,
 139                                                  const wxString& url,
 140                                                  wxString *redirect) const;
 141     virtual wxPoint HTMLCoordsToWindow(wxHtmlCell *cell,
 142                                        const wxPoint& pos) const;
 143     virtual wxWindow* GetHTMLWindow();
 144     virtual wxColour GetHTMLBackgroundColour() const;
 145     virtual void SetHTMLBackgroundColour(const wxColour& clr);
 146     virtual void SetHTMLBackgroundImage(const wxBitmap& bmpBg);
 147     virtual void SetHTMLStatusText(const wxString& text);
 148     virtual wxCursor GetHTMLCursor(HTMLCursor type) const;
 149
 150     // returns index of item that contains given HTML cell
 151     size_t GetItemForCell(const wxHtmlCell *cell) const;
 152
 153     // return physical coordinates of root wxHtmlCell of n-th item
 154     wxPoint GetRootCellCoords(size_t n) const;
 155
 156     // Converts physical coordinates stored in @a pos into coordinates
 157     // relative to the root cell of the item under mouse cursor, if any. If no
 158     // cell is found under the cursor, returns false.  Otherwise stores the new
 159     // coordinates back into @a pos and pointer to the cell under cursor into
 160     // @a cell and returns true.
 161     bool PhysicalCoordsToCell(wxPoint& pos, wxHtmlCell*& cell) const;
 162
 163     // The opposite of PhysicalCoordsToCell: converts coordinates relative to
 164     // given cell to physical coordinates in the window
 165     wxPoint CellCoordsToPhysical(const wxPoint& pos, wxHtmlCell *cell) const;
 166
 167 private:
 168     // this class caches the pre-parsed HTML to speed up display
 169     wxHtmlListBoxCache *m_cache;
 170
 171     // HTML parser we use
 172     wxHtmlWinParser *m_htmlParser;
 173
 174     // font encoding (used in non-Unicode mode only)
 175     wxFontEncoding  m_fontEncoding;
 176
 177 #if wxUSE_FILESYSTEM
 178     // file system used by m_htmlParser
 179     wxFileSystem m_filesystem;
 180 #endif // wxUSE_FILESYSTEM
 181
 182     // rendering style for the parser which allows us to customize our colours
 183     wxHtmlListBoxStyle *m_htmlRendStyle;
 184
 185
 186     // it calls our GetSelectedTextColour() and GetSelectedTextBgColour()
 187     friend class wxHtmlListBoxStyle;
 188     friend class wxHtmlListBoxWinInterface;
 189
 190
 191     DECLARE_EVENT_TABLE()
 192     DECLARE_NO_COPY_CLASS(wxHtmlListBox)
 193 };
 194
 195
 196 // ----------------------------------------------------------------------------
 197 // wxSimpleHtmlListBox
 198 // ----------------------------------------------------------------------------
 199
 200 #define wxHLB_DEFAULT_STYLE     wxBORDER_SUNKEN
 201 #define wxHLB_MULTIPLE          wxLB_MULTIPLE
 202
 203 class WXDLLIMPEXP_HTML wxSimpleHtmlListBox : public wxHtmlListBox,
 204                                              public wxItemContainer
 205 {
 206 public:
 207     // wxListbox-compatible constructors
 208     // ---------------------------------
 209
 210     wxSimpleHtmlListBox() { }
 211
 212     wxSimpleHtmlListBox(wxWindow *parent,
 213                         wxWindowID id,
 214                         const wxPoint& pos = wxDefaultPosition,
 215                         const wxSize& size = wxDefaultSize,
 216                         int n = 0, const wxString choices[] = NULL,
 217                         long style = wxHLB_DEFAULT_STYLE,
 218                         const wxValidator& validator = wxDefaultValidator,
 219                         const wxString& name = wxSimpleHtmlListBoxNameStr)
 220     {
 221         Create(parent, id, pos, size, n, choices, style, validator, name);
 222     }
 223
 224     wxSimpleHtmlListBox(wxWindow *parent,
 225                         wxWindowID id,
 226                         const wxPoint& pos,
 227                         const wxSize& size,
 228                         const wxArrayString& choices,
 229                         long style = wxHLB_DEFAULT_STYLE,
 230                         const wxValidator& validator = wxDefaultValidator,
 231                         const wxString& name = wxSimpleHtmlListBoxNameStr)
 232     {
 233         Create(parent, id, pos, size, choices, style, validator, name);
 234     }
 235
 236     bool Create(wxWindow *parent, wxWindowID id,
 237                 const wxPoint& pos = wxDefaultPosition,
 238                 const wxSize& size = wxDefaultSize,
 239                 int n = 0, const wxString choices[] = NULL,
 240                 long style = wxHLB_DEFAULT_STYLE,
 241                 const wxValidator& validator = wxDefaultValidator,
 242                 const wxString& name = wxSimpleHtmlListBoxNameStr);
 243     bool Create(wxWindow *parent, wxWindowID id,
 244                 const wxPoint& pos,
 245                 const wxSize& size,
 246                 const wxArrayString& choices,
 247                 long style = wxHLB_DEFAULT_STYLE,
 248                 const wxValidator& validator = wxDefaultValidator,
 249                 const wxString& name = wxSimpleHtmlListBoxNameStr);
 250
 251     virtual ~wxSimpleHtmlListBox();
 252
 253     // these must be overloaded otherwise the compiler will complain
 254     // about  wxItemContainerImmutable::[G|S]etSelection being pure virtuals...
 255     void SetSelection(int n)
 256         { wxVListBox::SetSelection(n); }
 257     int GetSelection() const
 258         { return wxVListBox::GetSelection(); }
 259
 260     // see ctrlsub.h for more info about this:
 261     wxCONTROL_ITEMCONTAINER_CLIENTDATAOBJECT_RECAST
 262
 263
 264     // accessing strings
 265     // -----------------
 266
 267     virtual unsigned int GetCount() const
 268         { return m_items.GetCount(); }
 269
 270     virtual wxString GetString(unsigned int n) const;
 271
 272     // override default unoptimized wxItemContainer::GetStrings() function
 273     wxArrayString GetStrings() const
 274         { return m_items; }
 275
 276     virtual void SetString(unsigned int n, const wxString& s);
 277
 278     virtual void Clear();
 279     virtual void Delete(unsigned int n);
 280
 281     // override default unoptimized wxItemContainer::Append() function
 282     void Append(const wxArrayString& strings);
 283
 284     // since we override one Append() overload, we need to overload all others too
 285     int Append(const wxString& item)
 286         { return wxItemContainer::Append(item); }
 287     int Append(const wxString& item, void *clientData)
 288         { return wxItemContainer::Append(item, clientData); }
 289     int Append(const wxString& item, wxClientData *clientData)
 290         { return wxItemContainer::Append(item, clientData); }
 291
 292
 293 protected:
 294
 295     virtual int DoAppend(const wxString& item);
 296     virtual int DoInsert(const wxString& item, unsigned int pos);
 297
 298     virtual void DoSetItemClientData(unsigned int n, void *clientData)
 299         { m_HTMLclientData[n] = clientData; }
 300
 301     virtual void *DoGetItemClientData(unsigned int n) const
 302         { return m_HTMLclientData[n]; }
 303     virtual void DoSetItemClientObject(unsigned int n, wxClientData *clientData)
 304         { m_HTMLclientData[n] = (void *)clientData; }
 305     virtual wxClientData *DoGetItemClientObject(unsigned int n) const
 306         { return (wxClientData *)m_HTMLclientData[n]; }
 307
 308     // calls wxHtmlListBox::SetItemCount() and RefreshAll()
 309     void UpdateCount();
 310
 311     // overload these functions just to change their visibility: users of
 312     // wxSimpleHtmlListBox shouldn't be allowed to call them directly!
 313     virtual void SetItemCount(size_t count)
 314         { wxHtmlListBox::SetItemCount(count); }
 315     virtual void SetLineCount(size_t count)
 316         { wxHtmlListBox::SetLineCount(count); }
 317
 318     virtual wxString OnGetItem(size_t n) const
 319         { return m_items[n]; }
 320
 321     wxArrayString   m_items;
 322     wxArrayPtrVoid  m_HTMLclientData;
 323
 324     // Note: For the benefit of old compilers (like gcc-2.8) this should
 325     // not be named m_clientdata as that clashes with the name of an
 326     // anonymous struct member in wxEvtHandler, which we derive from.
 327
 328     DECLARE_NO_COPY_CLASS(wxSimpleHtmlListBox)
 329 };
 330
 331 #endif // _WX_HTMLLBOX_H_
 332