X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/410bfc938346c4326f455631dd795e7d12cbc43e..6d98f9631aa3fbebb420cf8322cf7a75fc8e1db1:/docs/latex/wx/htmllbox.tex

diff --git a/docs/latex/wx/htmllbox.tex b/docs/latex/wx/htmllbox.tex
index 08500a998b..def468fc46 100644
--- a/docs/latex/wx/htmllbox.tex
+++ b/docs/latex/wx/htmllbox.tex
@@ -1,6 +1,6 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %% Name:        htmllbox.tex
-%% Purpose:     wxHtmlListBox documentation
+%% Purpose:     wxHtmlListBox and wxSimpleHtmlListBox documentation
 %% Author:      Vadim Zeitlin
 %% Modified by:
 %% Created:     01.06.03
@@ -30,13 +30,34 @@ example) but you will only need to override a single
 
 <wx/htmllbox.h>
 
+\wxheading{Library}
+
+\helpref{wxHtml}{librarieslist}
+
+\wxheading{See also}
+
+\helpref{wxSimpleHtmlListBox}{wxsimplehtmllistbox}
+
+
+\wxheading{Event handling}
+
+To process input from a wxHtmlListBox, use these event handler macros to direct input to member
+functions that take a \helpref{wxHtmlCellEvent}{wxhtmlcellevent} argument or a \helpref{wxHtmlLinkEvent}{wxhtmllinkevent}.
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf EVT\_HTML\_CELL\_CLICKED(id, func)}}{A \helpref{wxHtmlCell}{wxhtmlcell} was clicked.}
+\twocolitem{{\bf EVT\_HTML\_CELL\_HOVER(id, func)}}{The mouse passed over a \helpref{wxHtmlCell}{wxhtmlcell}.}
+\twocolitem{{\bf EVT\_HTML\_LINK\_CLICKED(id, func)}}{A \helpref{wxHtmlCell}{wxhtmlcell} which contains an hyperlink was clicked.}
+\end{twocollist}
+
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \membersection{wxHtmlListBox::wxHtmlListBox}\label{wxhtmllistboxwxhtmllistbox}
 
-\func{}{wxHtmlListBox}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxVListBoxNameStr}}
+\func{}{wxHtmlListBox}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxHtmlListBoxNameStr}}
 
 Normal constructor which calls \helpref{Create()}{wxhtmllistboxcreate}
 internally.
@@ -56,14 +77,14 @@ Destructor cleans up whatever resources we use.
 
 \membersection{wxHtmlListBox::Create}\label{wxhtmllistboxcreate}
 
-\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxVListBoxNameStr}}
+\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxHtmlListBoxNameStr}}
 
 Creates the control and optionally sets the initial number of items in it
 (it may also be set or changed later with
 \helpref{SetItemCount()}{wxvlistboxsetitemcount}).
 
 There are no special styles defined for wxHtmlListBox, in particular the
-wxListBox styles can not be used here.
+wxListBox styles (with the exception of {\tt wxLB\_MULTIPLE}) can not be used here.
 
 Returns {\tt true} on success or {\tt false} if the control couldn't be created
 
@@ -124,6 +145,12 @@ This method must be implemented in the derived class and should return
 the body (i.e. without {\tt <html>} nor {\tt <body>} tags) of the HTML fragment
 for the given item.
 
+Note that this function should always return a text fragment for the \arg{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, {\tt 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.
 
 \membersection{wxHtmlListBox::OnGetItemMarkup}\label{wxhtmllistboxongetitemmarkup}
 
@@ -137,6 +164,7 @@ This function may be overridden to decorate HTML returned by
 \func{virtual void}{OnLinkClicked}{\param{size\_t }{n}, \param{const wxHtmlLinkInfo\& }{link}}
 
 Called when the user clicks on hypertext link. Does nothing by default.
+Overloading this method is deprecated; intercept the event instead.
 
 \wxheading{Parameters}
 
@@ -147,3 +175,176 @@ Called when the user clicks on hypertext link. Does nothing by default.
 \wxheading{See also}
 
 See also \helpref{wxHtmlLinkInfo}{wxhtmllinkinfo}.
+
+
+
+
+
+
+
+%
+% wxSimpleHtmlListBox
+%
+
+
+\section{\class{wxSimpleHtmlListBox}}\label{wxsimplehtmllistbox}
+
+wxSimpleHtmlListBox is an implementation of \helpref{wxHtmlListBox}{wxhtmllistbox} which
+shows HTML content in the listbox rows.
+
+Unlike \helpref{wxHtmlListBox}{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 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
+\helpref{wxControlWithItems}{wxcontrolwithitems} interface, thus you should refer to
+\helpref{wxControlWithItems}{wxcontrolwithitems}'s documentation for the API reference
+for adding/removing/retrieving items in the listbox.
+Also note that the \helpref{wxVListBox::SetItemCount}{wxvlistboxsetitemcount} function is
+{\tt protected} in wxSimpleHtmlListBox's context so that you cannot call it 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
+\helpref{Append(const wxArrayString \&)}{wxcontrolwithitemsappend} function.
+
+Thus the only difference between a \helpref{wxListBox}{wxlistbox} and a wxSimpleHtmlListBox
+is that the latter stores strings which can contain HTML fragments (see the list of
+\helpref{tags supported by wxHTML}{htmltagssupported}).
+
+Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain the {\tt <html>} 
+or {\tt <body>} tags.
+
+
+\wxheading{Derived from}
+
+\helpref{wxHtmlListBox}{wxhtmllistbox}, \helpref{wxControlWithItems}{wxcontrolwithitems}\\
+\helpref{wxVListBox}{wxvlistbox}\\
+\helpref{wxVScrolledWindow}{wxvscrolledwindow}\\
+\helpref{wxPanel}{wxpanel}\\
+\helpref{wxWindow}{wxwindow}\\
+\helpref{wxEvtHandler}{wxevthandler}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/htmllbox.h>
+
+\wxheading{Library}
+
+\helpref{wxHtml}{librarieslist}
+
+\wxheading{Window styles}
+
+\twocolwidtha{5cm}%
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\windowstyle{wxHLB\_DEFAULT\_STYLE}}{The default style: wxBORDER\_SUNKEN}
+\twocolitem{\windowstyle{wxHLB\_MULTIPLE}}{Multiple-selection list: the user can toggle multiple
+items on and off.}
+\end{twocollist}
+
+See also \helpref{window styles overview}{windowstyles}.
+
+\wxheading{Event handling}
+
+A wxSimpleHtmlListBox emits the same events used by \helpref{wxListBox}{wxlistbox} and by
+\helpref{wxHtmlListBox}{wxhtmllistbox}.
+
+The event handlers for the following events take a \helpref{wxCommandEvent}{wxcommandevent}:
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf EVT\_LISTBOX(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_SELECTED event,
+when an item on the list is selected.}
+\twocolitem{{\bf EVT\_LISTBOX\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_DOUBLECLICKED event,
+when the listbox is double-clicked.}
+\end{twocollist}
+
+The event handlers for the following events take a \helpref{wxHtmlCellEvent}{wxhtmlcellevent}
+or a \helpref{wxHtmlLinkEvent}{wxhtmllinkevent}:
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf EVT\_HTML\_CELL\_CLICKED(id, func)}}{A \helpref{wxHtmlCell}{wxhtmlcell} was clicked.}
+\twocolitem{{\bf EVT\_HTML\_CELL\_HOVER(id, func)}}{The mouse passed over a \helpref{wxHtmlCell}{wxhtmlcell}.}
+\twocolitem{{\bf EVT\_HTML\_LINK\_CLICKED(id, func)}}{A \helpref{wxHtmlCell}{wxhtmlcell} which contains an hyperlink was clicked.}
+\end{twocollist}
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxSimpleHtmlListBox::wxSimpleHtmlListBox}\label{wxsimplehtmllistboxctor}
+
+\func{}{wxHtmlListBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
+\param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
+\param{int}{ n = 0}, \param{const wxString }{choices[] = NULL},\rtfsp
+\param{long}{ style = wxHLB\_DEFAULT\_STYLE}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp
+\param{const wxString\& }{name = ``simpleHtmlListBox"}}
+
+\func{}{wxHtmlListBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
+\param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
+\param{const wxArrayString\& }{choices},\rtfsp
+\param{long}{ style = wxHLB\_DEFAULT\_STYLE}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp
+\param{const wxString\& }{name = ``simpleHtmlListBox"}}
+
+Constructor, creating and showing the HTML list box.
+
+\wxheading{Parameters}
+
+\docparam{parent}{Parent window. Must not be NULL.}
+
+\docparam{id}{Window identifier. A value of -1 indicates a default value.}
+
+\docparam{pos}{Window position.}
+
+\docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
+appropriately.}
+
+\docparam{n}{Number of strings with which to initialise the control.}
+
+\docparam{choices}{An array of strings with which to initialise the control.}
+
+\docparam{style}{Window style. See {\tt wxHLB\_*} flags.}
+
+\docparam{validator}{Window validator.}
+
+\docparam{name}{Window name.}
+
+\wxheading{See also}
+
+\helpref{wxSimpleHtmlListBox::Create}{wxsimplehtmllistboxcreate}
+
+
+
+\func{}{wxSimpleHtmlListBox}{\void}
+
+Default constructor, you must call \helpref{Create()}{wxsimplehtmllistboxcreate}
+later.
+
+
+\membersection{wxSimpleHtmlListBox::\destruct{wxSimpleHtmlListBox}}\label{wxsimplehtmllistboxdtor}
+
+\func{}{\destruct{wxSimpleHtmlListBox}}{\void}
+
+Frees the array of stored items and relative client data.
+
+
+\membersection{wxSimpleHtmlListBox::Create}\label{wxsimplehtmllistboxcreate}
+
+\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
+\param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
+\param{int}{ n}, \param{const wxString }{choices[] = NULL},\rtfsp
+\param{long}{ style = wxHLB\_DEFAULT\_STYLE}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp
+\param{const wxString\& }{name = ``simpleHtmlListBox"}}
+
+\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
+\param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
+\param{const wxArrayString\& }{choices},\rtfsp
+\param{long}{ style = wxHLB\_DEFAULT\_STYLE}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp
+\param{const wxString\& }{name = ``simpleHtmlListBox"}}
+
+Creates the HTML listbox for two-step construction. 
+See \helpref{wxSimpleHtmlListBox::wxSimpleHtmlListBox}{wxsimplehtmllistboxctor} for further details.
+
