Document wxDataViewListModel as common abstract base class for

[wxWidgets.git] / interface / wx / htmllbox.h

diff --git a/interface/wx/htmllbox.h b/interface/wx/htmllbox.h
index b99b8b4528f2106d6a4d1fca21d554a3159bb77f..d34646abd7f9aba65ff3dfcff2533e160c4473be 100644 (file)
--- a/interface/wx/htmllbox.h
+++ b/interface/wx/htmllbox.h
@@ -3,51 +3,60 @@
 // Purpose:     interface of wxHtmlListBox
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxHtmlListBox
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxHtmlListBox
 
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxHtmlListBox
 

-    wxHtmlListBox is an implementation of wxVListBox which
-    shows HTML content in the listbox rows. This is still an abstract base class
-    and you will need to derive your own class from it (see htlbox sample for the
-    example) but you will only need to override a single
-    wxHtmlListBox::OnGetItem function.
+    wxHtmlListBox is an implementation of wxVListBox which shows HTML content in
+    the listbox rows. This is still an abstract base class and you will need to
+    derive your own class from it (see htlbox sample for the example) but you will
+    only need to override a single wxHtmlListBox::OnGetItem function.
+
+    @beginEventEmissionTable{wxHtmlCellEvent,wxHtmlLinkEvent}
+    @event{EVT_HTML_CELL_CLICKED(id, func)}
+        A wxHtmlCell was clicked.
+    @event{EVT_HTML_CELL_HOVER(id, func)}
+        The mouse passed over a wxHtmlCell.
+    @event{EVT_HTML_LINK_CLICKED(id, func)}
+        A wxHtmlCell which contains an hyperlink was clicked.
+    @endEventTable

 
     @library{wxhtml}
     @category{ctrl}
 
     @library{wxhtml}
     @category{ctrl}

-    <!-- @appearance{htmllistbox.png} -->

 
     @see wxSimpleHtmlListBox
 */
 class wxHtmlListBox : public wxVListBox
 {
 public:
 
     @see wxSimpleHtmlListBox
 */
 class wxHtmlListBox : public wxVListBox
 {
 public:

-    //@{

     /**
     /**

-        Default constructor, you must call Create()
-        later.
+        Normal constructor which calls Create() internally.

     */
     wxHtmlListBox(wxWindow* parent, wxWindowID id = wxID_ANY,
                   const wxPoint& pos = wxDefaultPosition,
                   const wxSize& size = wxDefaultSize,
                   long style = 0,
                   const wxString& name = wxHtmlListBoxNameStr);
     */
     wxHtmlListBox(wxWindow* parent, wxWindowID id = wxID_ANY,
                   const wxPoint& pos = wxDefaultPosition,
                   const wxSize& size = wxDefaultSize,
                   long style = 0,
                   const wxString& name = wxHtmlListBoxNameStr);

+
+    /**
+        Default constructor, you must call Create() later.
+    */

     wxHtmlListBox();
     wxHtmlListBox();

-    //@}

 
     /**
         Destructor cleans up whatever resources we use.
     */
 
     /**
         Destructor cleans up whatever resources we use.
     */

-    ~wxHtmlListBox();
+    virtual ~wxHtmlListBox();

 
     /**
         Creates the control and optionally sets the initial number of items in it
 
     /**
         Creates the control and optionally sets the initial number of items in it

-        (it may also be set or changed later with
-        wxVListBox::SetItemCount).
+        (it may also be set or changed later with wxVListBox::SetItemCount).
+

         There are no special styles defined for wxHtmlListBox, in particular the
         wxListBox styles (with the exception of @c wxLB_MULTIPLE) can not be used here.
         There are no special styles defined for wxHtmlListBox, in particular the
         wxListBox styles (with the exception of @c wxLB_MULTIPLE) can not be used here.

+

         Returns @true on success or @false if the control couldn't be created
     */
     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
         Returns @true on success or @false if the control couldn't be created
     */
     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,


@@ -58,28 +67,43 @@ public:
 
     //@{
     /**
 
     //@{
     /**

-        Returns the wxFileSystem used by the HTML parser of
-        this object. The file system object is used to resolve the paths in HTML
-        fragments displayed in the control and you should use
-        wxFileSystem::ChangePathTo if you use
-        relative paths for the images or other resources embedded in your HTML.
+        Returns the wxFileSystem used by the HTML parser of this object.
+
+        The file system object is used to resolve the paths in HTML fragments
+        displayed in the control and you should use wxFileSystem::ChangePathTo
+        if you use relative paths for the images or other resources embedded in
+        your HTML.

     */
     */

-    wxFileSystem GetFileSystem() const;
-    const wxFileSystem GetFileSystem() const;
+    wxFileSystem& GetFileSystem() const;
+    const wxFileSystem& GetFileSystem() const;

     //@}
 
     //@}
 

+protected:
+
+    /**
+        Called when the user clicks on hypertext link. Does nothing by default.
+        Overloading this method is deprecated; intercept the event instead.
+
+        @param n
+            Index of the item containing the link.
+        @param link
+            Description of the link.
+
+        @see wxHtmlLinkInfo.
+    */
+    virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link);
+

     /**
         This virtual function may be overridden to change the appearance of the
     /**
         This virtual function may be overridden to change the appearance of the

-        background of the selected cells in the same way as
-        GetSelectedTextColour().
-        It should be rarely, if ever, used because
-        wxVListBox::SetSelectionBackground allows to
-        change the selection background for all cells at once and doing anything more
-        fancy is probably going to look strangely.
+        background of the selected cells in the same way as GetSelectedTextColour().
+
+        It should be rarely, if ever, used because wxVListBox::SetSelectionBackground
+        allows to change the selection background for all cells at once and doing
+        anything more fancy is probably going to look strangely.

 
         @see GetSelectedTextColour()
     */
 
         @see GetSelectedTextColour()
     */

-    wxColour GetSelectedTextBgColour(const wxColour& colBg) const;
+    virtual wxColour GetSelectedTextBgColour(const wxColour& colBg) const;

 
     /**
         This virtual function may be overridden to customize the appearance of the
 
     /**
         This virtual function may be overridden to customize the appearance of the


@@ -91,40 +115,26 @@ public:
         @see GetSelectedTextBgColour(),
              wxVListBox::SetSelectionBackground, wxSystemSettings::GetColour
     */
         @see GetSelectedTextBgColour(),
              wxVListBox::SetSelectionBackground, wxSystemSettings::GetColour
     */

-    wxColour GetSelectedTextColour(const wxColour& colFg) const;
+    virtual wxColour GetSelectedTextColour(const wxColour& colFg) const;
+
+    /**
+        This function may be overridden to decorate HTML returned by OnGetItem().
+    */
+    virtual wxString OnGetItemMarkup(size_t n) const;

 
     /**
         This method must be implemented in the derived class and should return
         the body (i.e. without @c html nor @c body tags) of the HTML fragment
         for the given item.
 
     /**
         This method must be implemented in the derived class and should return
         the body (i.e. without @c html nor @c body tags) of the HTML fragment
         for the given item.

+

         Note that this function should always return a text fragment for the @a n item
         which renders with the same height both when it is selected and when it's not:
         i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to
         make the items appear differently when they are selected, then you should make
         Note that this function should always return a text fragment for the @a n item
         which renders with the same height both when it is selected and when it's not:
         i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to
         make the items appear differently when they are selected, then you should make

-        sure
-        that the returned HTML fragment will render with the same height or else you'll
-        see some artifacts when the user selects an item.
+        sure that the returned HTML fragment will render with the same height or else
+        you'll see some artifacts when the user selects an item.

     */
     */

-    wxString OnGetItem(size_t n) const;
-
-    /**
-        This function may be overridden to decorate HTML returned by
-        OnGetItem().
-    */
-    wxString OnGetItemMarkup(size_t n) const;
-
-    /**
-        Called when the user clicks on hypertext link. Does nothing by default.
-        Overloading this method is deprecated; intercept the event instead.
-
-        @param n
-            Index of the item containing the link.
-        @param link
-            Description of the link.
-
-        @see See also wxHtmlLinkInfo.
-    */
-    virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link);
+    virtual wxString OnGetItem(size_t n) const = 0;

 };
 
 
 };
 
 


@@ -135,104 +145,155 @@ public:
     wxSimpleHtmlListBox is an implementation of wxHtmlListBox which
     shows HTML content in the listbox rows.
 
     wxSimpleHtmlListBox is an implementation of wxHtmlListBox which
     shows HTML content in the listbox rows.
 

-    Unlike wxHtmlListBox, this is not an abstract class and thus it
-    has the advantage that you can use it without deriving your own class from it.
+    Unlike wxHtmlListBox, this is not an abstract class and thus it has the
+    advantage that you can use it without deriving your own class from it.

     However, it also has the disadvantage that this is not a virtual control and
     However, it also has the disadvantage that this is not a virtual control and

-    thus it's not
-    well-suited for those cases where you need to show a huge number of items:
-    every time you
-    add/insert a string, it will be stored internally and thus will take memory.
+    thus it's not well-suited for those cases where you need to show a huge number
+    of items: every time you add/insert a string, it will be stored internally
+    and thus will take memory.

 
     The interface exposed by wxSimpleHtmlListBox fully implements the
 
     The interface exposed by wxSimpleHtmlListBox fully implements the

-    wxControlWithItems interface, thus you should refer to
-    wxControlWithItems's documentation for the API reference
-    for adding/removing/retrieving items in the listbox.
-    Also note that the wxVListBox::SetItemCount function is
+    wxControlWithItems interface, thus you should refer to wxControlWithItems's
+    documentation for the API reference for adding/removing/retrieving items in
+    the listbox. Also note that the wxVListBox::SetItemCount function is

     @c protected in wxSimpleHtmlListBox's context so that you cannot call it
     @c protected in wxSimpleHtmlListBox's context so that you cannot call it

-    directly,
-    wxSimpleHtmlListBox will do it for you.
+    directly, wxSimpleHtmlListBox will do it for you.

 
     Note: in case you need to append a lot of items to the control at once, make
     sure to use the
 
     Note: in case you need to append a lot of items to the control at once, make
     sure to use the

-    @ref wxControlWithItems::append "Append(const wxArrayString )" function.
+    @ref wxControlWithItems::Append "Append(const wxArrayString&)" function.

 
     Thus the only difference between a wxListBox and a wxSimpleHtmlListBox
     is that the latter stores strings which can contain HTML fragments (see the
 
     Thus the only difference between a wxListBox and a wxSimpleHtmlListBox
     is that the latter stores strings which can contain HTML fragments (see the

-    list of
-    @ref overview_htmltagssupported "tags supported by wxHTML").
+    list of @ref overview_html_supptags "tags supported by wxHTML").

 
     Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain
 
     Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain

-    the @c html
-    or @c body tags.
+    the @c \<html\> or @c \<body\> tags.

 
     @beginStyleTable
     @style{wxHLB_DEFAULT_STYLE}
            The default style: wxBORDER_SUNKEN
     @style{wxHLB_MULTIPLE}
 
     @beginStyleTable
     @style{wxHLB_DEFAULT_STYLE}
            The default style: wxBORDER_SUNKEN
     @style{wxHLB_MULTIPLE}

-           Multiple-selection list: the user can toggle multiple items on and
-           off.
+           Multiple-selection list: the user can toggle multiple items on and off.

     @endStyleTable
 
     @endStyleTable
 

+
+    A wxSimpleHtmlListBox emits the same events used by wxListBox and by wxHtmlListBox.
+
+    @beginEventEmissionTable
+    @event{EVT_LISTBOX(id, func)}
+        Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the list
+        is selected. See wxCommandEvent.
+    @event{EVT_LISTBOX_DCLICK(id, func)}
+        Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the listbox is
+        double-clicked. See wxCommandEvent.
+    @event{EVT_HTML_CELL_CLICKED(id, func)}
+        A wxHtmlCell was clicked. See wxHtmlCellEvent.
+    @event{EVT_HTML_CELL_HOVER(id, func)}
+        The mouse passed over a wxHtmlCell. See wxHtmlCellEvent.
+    @event{EVT_HTML_LINK_CLICKED(id, func)}
+        A wxHtmlCell which contains an hyperlink was clicked. See wxHtmlLinkEvent
+    @endEventTable
+

     @library{wxhtml}
     @category{ctrl}
     @library{wxhtml}
     @category{ctrl}

-    <!-- @appearance{simplehtmllistbox.png} -->
+    @appearance{simplehtmllistbox.png}

 
     @see wxSimpleHtmlListBox::Create
 */
 class wxSimpleHtmlListBox : public wxHtmlListBox
 {
 public:
 
     @see wxSimpleHtmlListBox::Create
 */
 class wxSimpleHtmlListBox : public wxHtmlListBox
 {
 public:

-    //@{

     /**
     /**

-        Default constructor, you must call Create()
-        later.
+        Constructor, creating and showing the HTML list box.
+
+        @param parent
+            Parent window. Must not be NULL.
+        @param id
+            Window identifier. A value of -1 indicates a default value.
+        @param pos
+            Window position.
+            If ::wxDefaultPosition is specified then a default position is chosen.
+        @param size
+            Window size. 
+            If ::wxDefaultSize is specified then the window is sized appropriately.
+        @param n
+            Number of strings with which to initialise the control.
+        @param choices
+            An array of strings with which to initialise the control.
+        @param style
+            Window style. See wxHLB_* flags.
+        @param validator
+            Window validator.
+        @param name
+            Window name.

     */
     */

-    wxHtmlListBox(wxWindow* parent, wxWindowID id,
-                  const wxPoint& pos = wxDefaultPosition,
-                  const wxSize& size = wxDefaultSize,
-                  int n = 0,
-                  const wxString choices[] = NULL,
-                  long style = wxHLB_DEFAULT_STYLE,
-                  const wxValidator& validator = wxDefaultValidator,
-                  const wxString& name = "simpleHtmlListBox");
-    wxHtmlListBox(wxWindow* parent, wxWindowID id,
-                  const wxPoint& pos,
-                  const wxSize& size,
-                  const wxArrayString& choices,
-                  long style = wxHLB_DEFAULT_STYLE,
-                  const wxValidator& validator = wxDefaultValidator,
-                  const wxString& name = "simpleHtmlListBox");
-    See also
-    wxSimpleHtmlListBox::Create
+    wxSimpleHtmlListBox(wxWindow* parent, wxWindowID id,
+                        const wxPoint& pos = wxDefaultPosition,
+                        const wxSize& size = wxDefaultSize,
+                        int n = 0,
+                        const wxString choices[] = NULL,
+                        long style = wxHLB_DEFAULT_STYLE,
+                        const wxValidator& validator = wxDefaultValidator,
+                        const wxString& name = wxSimpleHtmlListBoxNameStr);

 
 

+    /**
+        Constructor, creating and showing the HTML list box.
+
+        @param parent
+            Parent window. Must not be NULL.
+        @param id
+            Window identifier. A value of -1 indicates a default value.
+        @param pos
+            Window position.
+        @param size
+            Window size. If wxDefaultSize is specified then the window is sized appropriately.
+        @param choices
+            An array of strings with which to initialise the control.
+        @param style
+            Window style. See wxHLB_* flags.
+        @param validator
+            Window validator.
+        @param name
+            Window name.
+    */
+    wxSimpleHtmlListBox(wxWindow* parent, wxWindowID id,
+                        const wxPoint& pos,
+                        const wxSize& size,
+                        const wxArrayString& choices,
+                        long style = wxHLB_DEFAULT_STYLE,
+                        const wxValidator& validator = wxDefaultValidator,
+                        const wxString& name = wxSimpleHtmlListBoxNameStr);
+
+    /**
+        Default constructor, you must call Create() later.
+    */

     wxSimpleHtmlListBox();
     wxSimpleHtmlListBox();

-    //@}

 
     /**
         Frees the array of stored items and relative client data.
     */
 
     /**
         Frees the array of stored items and relative client data.
     */

-    ~wxSimpleHtmlListBox();
+    virtual ~wxSimpleHtmlListBox();

 
     //@{
     /**
         Creates the HTML listbox for two-step construction.
         See wxSimpleHtmlListBox() for further details.
     */
 
     //@{
     /**
         Creates the HTML listbox for two-step construction.
         See wxSimpleHtmlListBox() for further details.
     */

-    bool Create(wxWindow* parent, wxWindowID id,
+    bool Create(wxWindow *parent, wxWindowID id,

                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,

-                int n,
-                const wxString choices[] = NULL,
+                int n = 0, const wxString choices[] = NULL,

                 long style = wxHLB_DEFAULT_STYLE,
                 const wxValidator& validator = wxDefaultValidator,
                 long style = wxHLB_DEFAULT_STYLE,
                 const wxValidator& validator = wxDefaultValidator,

-                const wxString& name = "simpleHtmlListBox");
-    bool Create(wxWindow* parent, wxWindowID id,
+                const wxString& name = wxSimpleHtmlListBoxNameStr);
+    bool Create(wxWindow *parent, wxWindowID id,

                 const wxPoint& pos,
                 const wxSize& size,
                 const wxArrayString& choices,
                 long style = wxHLB_DEFAULT_STYLE,
                 const wxValidator& validator = wxDefaultValidator,
                 const wxPoint& pos,
                 const wxSize& size,
                 const wxArrayString& choices,
                 long style = wxHLB_DEFAULT_STYLE,
                 const wxValidator& validator = wxDefaultValidator,

-                const wxString& name = "simpleHtmlListBox");
+                const wxString& name = wxSimpleHtmlListBoxNameStr);

     //@}
 };
 
     //@}
 };