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