]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/htmllbox.h
undo the last change as it results in buildbot configuration error
[wxWidgets.git] / interface / wx / htmllbox.h
index 8003847b38abc2583a50613b77f80828f3c06e54..723b24ea848d12b9eec47dae4710cdc8280d3697 100644 (file)
@@ -9,33 +9,41 @@
 /**
     @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.
@@ -44,10 +52,11 @@ public:
 
     /**
         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,14 +67,15 @@ 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:
     //@}
 
 protected:
@@ -79,18 +89,17 @@ protected:
         @param link
             Description of the link.
 
         @param link
             Description of the link.
 
-        @see See also wxHtmlLinkInfo.
+        @see wxHtmlLinkInfo.
     */
     virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link);
 
     /**
         This virtual function may be overridden to change the appearance of the
     */
     virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link);
 
     /**
         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()
     */
@@ -117,13 +126,13 @@ protected:
         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.
     */
     virtual wxString OnGetItem(size_t n) const = 0;
 };
     */
     virtual wxString OnGetItem(size_t n) const = 0;
 };
@@ -136,44 +145,56 @@ protected:
     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}
     @appearance{simplehtmllistbox.png}
     @library{wxhtml}
     @category{ctrl}
     @appearance{simplehtmllistbox.png}
@@ -183,31 +204,71 @@ protected:
 class wxSimpleHtmlListBox : public wxHtmlListBox
 {
 public:
 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.
@@ -219,21 +280,20 @@ public:
         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(wxWindowparent, 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(wxWindowparent, 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);
     //@}
 };
 
     //@}
 };