%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name: htmllbox.tex
-%% Purpose: wxHtmlListBox documentation
+%% Purpose: wxHtmlListBox and wxSimpleHtmlListBox documentation
%% Author: Vadim Zeitlin
%% Modified by:
%% Created: 01.06.03
wxHtmlListBox is an implementation of \helpref{wxVListBox}{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
+example) but you will only need to override a single
\helpref{OnGetItem()}{wxhtmllistboxongetitem} function.
\wxheading{Derived from}
-\helpref{wxVListBox}{wxvlistbox}
+\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{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.
\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
+(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
Returns the \helpref{wxFileSystem}{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
+fragments displayed in the control and you should use
\helpref{wxFileSystem::ChangePathTo}{wxfilesystemchangepathto} if you use
relative paths for the images or other resources embedded in your HTML.
\constfunc{wxColour}{GetSelectedTextBgColour}{\param{const wxColour\& }{colBg}}
This virtual function may be overridden to change the appearance of the
-background of the selected cells in the same way as
+background of the selected cells in the same way as
\helpref{GetSelectedTextColour}{wxhtmllistboxgetselectedtextcolour}.
-It should be rarely, if ever, used because
+It should be rarely, if ever, used because
\helpref{SetSelectionBackground}{wxvlistboxsetselectionbackground} allows to
change the selection background for all cells at once and doing anything more
fancy is probably going to look strangely.
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}
This function may be overridden to decorate HTML returned by
\helpref{OnGetItem()}{wxhtmllistboxongetitem}.
+\membersection{wxHtmlListBox::OnLinkClicked}\label{wxhtmlistboxonlinkclicked}
+
+\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}
+
+\docparam{n}{Index of the item containing the link.}
+
+\docparam{link}{Description of the link.}
+
+\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{Window styles}
+
+\twocolwidtha{5cm}%
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\windowstyle{wxHLB\_DEFAULT\_STYLE}}{The default style: wxSUNKEN\_BORDER}
+\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.
+
projects / wxWidgets.git / blobdiff