Added font setting and ability to determine AUI notebook height for a given page...

[wxWidgets.git] / docs / latex / wx / notebook.tex

diff --git a/docs/latex/wx/notebook.tex b/docs/latex/wx/notebook.tex
index f97a2e9725b0ec7f00f0a1fa7901645e22ed2f0b..f59eb9767a186cd065e255071f8344873befb60f 100644 (file)
--- a/docs/latex/wx/notebook.tex
+++ b/docs/latex/wx/notebook.tex
@@ -10,6 +10,7 @@ managed by wxNotebook.
 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 

+wxBookCtrlBase (see \helpref{wxBookCtrl overview}{wxbookctrloverview})\\

 \helpref{wxControl}{wxcontrol}\\
 \helpref{wxWindow}{wxwindow}\\
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxControl}{wxcontrol}\\
 \helpref{wxWindow}{wxwindow}\\
 \helpref{wxEvtHandler}{wxevthandler}\\


@@ -23,39 +24,70 @@ managed by wxNotebook.
 
 \twocolwidtha{5cm}
 \begin{twocollist}\itemsep=0pt
 
 \twocolwidtha{5cm}
 \begin{twocollist}\itemsep=0pt

-\twocolitem{\windowstyle{wxNB\_FIXEDWIDTH}}{Make all tabs of equal width}
-\twocolitem{\windowstyle{wxNB\_LEFT}}{Put the tabs on the left side of the notebook}
-\twocolitem{\windowstyle{wxNB\_RIGHT}}{Put the tabs on the right side of the notebook}
-\twocolitem{\windowstyle{wxNB\_BOTTOM}}{Put the tabs on the bottom of the notebook}
+\twocolitem{\windowstyle{wxNB\_TOP}}{Place tabs on the top side.}
+\twocolitem{\windowstyle{wxNB\_LEFT}}{Place tabs on the left side.}
+\twocolitem{\windowstyle{wxNB\_RIGHT}}{Place tabs on the right side.}
+\twocolitem{\windowstyle{wxNB\_BOTTOM}}{Place tabs under instead of above the notebook pages.}
+\twocolitem{\windowstyle{wxNB\_FIXEDWIDTH}}{(Windows only) All tabs will have same width.}
+\twocolitem{\windowstyle{wxNB\_MULTILINE}}{(Windows only) There can be several rows of tabs.}
+\twocolitem{\windowstyle{wxNB\_NOPAGETHEME}}{(Windows only) Display a solid colour on notebook pages, and not a gradient, which can reduce performance.}
+\twocolitem{\windowstyle{wxNB\_FLAT}}{(Windows CE only) Show tabs in a flat style.}
+

 \end{twocollist}
 
 \end{twocollist}
 

-\wxheading{Event handling}
+The styles \texttt{wxNB\_LEFT}, \texttt{RIGHT} and \texttt{BOTTOM} are not
+supported under Microsoft Windows XP when using visual themes.

 
 

-To process input from a notebook control, use the following event handler macros to direct input to member
-functions that take a \helpref{wxNotebookEvent}{wxnotebookevent} argument.
+See also \helpref{window styles overview}{windowstyles}.

 
 

-\twocolwidtha{7cm}
-\begin{twocollist}\itemsep=0pt
-\twocolitem{{\bf EVT\_NOTEBOOK\_PAGE\_CHANGED(id, func)}}{The page selection was changed.}
-\twocolitem{{\bf EVT\_NOTEBOOK\_PAGE\_CHANGING(id, func)}}{The page selection is about to be changed.
-This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
-\end{twocollist}%
+\input noteevt.inc
+
+\wxheading{Page backgrounds}
+
+On Windows XP, the default theme paints a gradient on the notebook's pages.
+If you wish to suppress this theme, for aesthetic or performance reasons,
+there are three ways of doing it. You can use wxNB\_NOPAGETHEME to disable
+themed drawing for a particular notebook, you can call {\tt wxSystemOptions::SetOption}
+to disable it for the whole application, or you can disable it for individual
+pages by using {\tt SetBackgroundColour}.
+
+To disable themed pages globally:
+
+\begin{verbatim}
+    wxSystemOptions::SetOption(wxT("msw.notebook.themed-background"), 0);
+\end{verbatim}
+
+Set the value to 1 to enable it again.
+
+To give a single page a solid background that more or less fits in with the
+overall theme, use:
+
+\begin{verbatim}
+    wxColour col = notebook->GetThemeBackgroundColour();
+    if (col.Ok())
+    {
+        page->SetBackgroundColour(col);
+    }
+\end{verbatim}
+
+On platforms other than Windows, or if the application is not using Windows
+themes, {\tt GetThemeBackgroundColour} will return an uninitialised colour object,
+and the above code will therefore work on all platforms.

 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxNotebookEvent}{wxnotebookevent}, \helpref{wxImageList}{wximagelist},\rtfsp
-\helpref{wxTabCtrl}{wxtabctrl}
+\helpref{wxBookCtrl}{wxbookctrloverview}, \helpref{wxNotebookEvent}{wxnotebookevent}, \helpref{wxImageList}{wximagelist}, \helpref{notebook sample}{samplenotebook}\rtfsp

 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxNotebook::wxNotebook}\label{wxnotebookconstr}
+\membersection{wxNotebook::wxNotebook}\label{wxnotebookctor}

 
 \func{}{wxNotebook}{\void}
 
 Default constructor.
 
 \func{}{wxNotebook}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id}, \param{const wxPoint\&}{ pos = wxDefaultPosition},
 
 \func{}{wxNotebook}{\void}
 
 Default constructor.
 
 \func{}{wxNotebook}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id}, \param{const wxPoint\&}{ pos = wxDefaultPosition},

- \param{const wxSize\&}{ size}, \param{long}{ style = 0}, \param{const wxString\& }{name = "notebook"}}
+ \param{const wxSize\&}{ size = wxDefaultSize}, \param{long}{ style = 0}, \param{const wxString\& }{name = wxNotebookNameStr}}

 
 Constructs a notebook control.
 
 
 Constructs a notebook control.
 


@@ -71,28 +103,29 @@ Note that sometimes you can reduce flicker by passing the wxCLIP\_CHILDREN windo
 
 \docparam{size}{The window size.}
 
 
 \docparam{size}{The window size.}
 

-\docparam{style}{The window style. Its value is a bit list of zero or more of {\bf wxTC\_MULTILINE},
- {\bf wxTC\_RIGHTJUSTIFY}, {\bf wxTC\_FIXEDWIDTH} and {\bf wxTC\_OWNERDRAW}
- possibly combined with one of {\bf wxNB\_LEFT}, {\bf wxNB\_RIGHT} or 
- {\bf wxNB\_BOTTOM}.}
+\docparam{style}{The window style. See \helpref{wxNotebook}{wxnotebook}.}

 
 \docparam{name}{The name of the control (used only under Motif).}
 
 
 \docparam{name}{The name of the control (used only under Motif).}
 

-\membersection{wxNotebook::\destruct{wxNotebook}}
+
+\membersection{wxNotebook::\destruct{wxNotebook}}\label{wxnotebookdtor}

 
 \func{}{\destruct{wxNotebook}}{\void}
 
 Destroys the wxNotebook object.
 
 
 \func{}{\destruct{wxNotebook}}{\void}
 
 Destroys the wxNotebook object.
 

+

 \membersection{wxNotebook::AddPage}\label{wxnotebookaddpage}
 
 \func{bool}{AddPage}{\param{wxNotebookPage*}{ page},
  \param{const wxString\&}{ text},
 \membersection{wxNotebook::AddPage}\label{wxnotebookaddpage}
 
 \func{bool}{AddPage}{\param{wxNotebookPage*}{ page},
  \param{const wxString\&}{ text},

- \param{bool}{ select = FALSE},
+ \param{bool}{ select = false},

  \param{int}{ imageId = -1}}
 
 Adds a new page.
 
  \param{int}{ imageId = -1}}
 
 Adds a new page.
 

+The call to this function may generate the page changing events.
+

 \wxheading{Parameters}
 
 \docparam{page}{Specifies the new page.}
 \wxheading{Parameters}
 
 \docparam{page}{Specifies the new page.}


@@ -105,7 +138,7 @@ Adds a new page.
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-TRUE if successful, FALSE otherwise.
+true if successful, false otherwise.

 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 


@@ -115,32 +148,61 @@ Do not delete the page, it will be deleted by the notebook.
 
 \helpref{wxNotebook::InsertPage}{wxnotebookinsertpage}
 
 
 \helpref{wxNotebook::InsertPage}{wxnotebookinsertpage}
 

+

 \membersection{wxNotebook::AdvanceSelection}\label{wxnotebookadvanceselection}
 
 \membersection{wxNotebook::AdvanceSelection}\label{wxnotebookadvanceselection}
 

-\func{void}{AdvanceSelection}{\param{bool}{ forward = TRUE}}
+\func{void}{AdvanceSelection}{\param{bool}{ forward = true}}

 
 Cycles through the tabs.
 
 
 Cycles through the tabs.
 

+The call to this function generates the page changing events.
+
+
+\membersection{wxNotebook::AssignImageList}\label{wxnotebookassignimagelist}
+
+\func{void}{AssignImageList}{\param{wxImageList*}{ imageList}}
+
+Sets the image list for the page control and takes ownership of
+the list.
+
+\wxheading{See also}
+
+\helpref{wxImageList}{wximagelist},
+\helpref{SetImageList}{wxnotebooksetimagelist}
+
+

 \membersection{wxNotebook::Create}\label{wxnotebookcreate}
 
 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id}, \param{const wxPoint\&}{ pos = wxDefaultPosition},
 \membersection{wxNotebook::Create}\label{wxnotebookcreate}
 
 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id}, \param{const wxPoint\&}{ pos = wxDefaultPosition},

- \param{const wxSize\&}{ size}, \param{long}{ style = 0}, \param{const wxString\& }{name = "notebook"}}
+ \param{const wxSize\&}{ size}, \param{long}{ style = 0}, \param{const wxString\& }{name = wxNotebookNameStr}}

 
 

-Creates a notebook control. See \helpref{wxNotebook::wxNotebook}{wxnotebookconstr} for a description
+Creates a notebook control. See \helpref{wxNotebook::wxNotebook}{wxnotebookctor} for a description

 of the parameters.
 
 of the parameters.
 

+

 \membersection{wxNotebook::DeleteAllPages}\label{wxnotebookdeleteallpages}
 
 \func{bool}{DeleteAllPages}{\void}
 
 Deletes all pages.
 
 \membersection{wxNotebook::DeleteAllPages}\label{wxnotebookdeleteallpages}
 
 \func{bool}{DeleteAllPages}{\void}
 
 Deletes all pages.
 

+

 \membersection{wxNotebook::DeletePage}\label{wxnotebookdeletepage}
 
 \membersection{wxNotebook::DeletePage}\label{wxnotebookdeletepage}
 

-\func{bool}{DeletePage}{\param{int}{ page}}
+\func{bool}{DeletePage}{\param{size\_t}{ page}}

 
 Deletes the specified page, and the associated window.
 
 
 Deletes the specified page, and the associated window.
 

+The call to this function generates the page changing events.
+
+
+\membersection{wxNotebook::GetCurrentPage}\label{wxnotebookgetcurrentpage}
+
+\constfunc{wxWindow *}{GetCurrentPage}{\void}
+
+Returns the currently selected notebook page or \NULL.
+
+

 \membersection{wxNotebook::GetImageList}\label{wxnotebookgetimagelist}
 
 \constfunc{wxImageList*}{GetImageList}{\void}
 \membersection{wxNotebook::GetImageList}\label{wxnotebookgetimagelist}
 
 \constfunc{wxImageList*}{GetImageList}{\void}


@@ -151,47 +213,97 @@ Returns the associated image list.
 
 \helpref{wxImageList}{wximagelist}, \helpref{wxNotebook::SetImageList}{wxnotebooksetimagelist}
 
 
 \helpref{wxImageList}{wximagelist}, \helpref{wxNotebook::SetImageList}{wxnotebooksetimagelist}
 

+

 \membersection{wxNotebook::GetPage}\label{wxnotebookgetpage}
 
 \membersection{wxNotebook::GetPage}\label{wxnotebookgetpage}
 

-\func{wxNotebookPage*}{GetPage}{\param{int}{ page}}
+\func{wxNotebookPage*}{GetPage}{\param{size\_t}{ page}}

 
 Returns the window at the given page position.
 
 
 Returns the window at the given page position.
 

+

 \membersection{wxNotebook::GetPageCount}\label{wxnotebookgetpagecount}
 
 \membersection{wxNotebook::GetPageCount}\label{wxnotebookgetpagecount}
 

-\constfunc{int}{GetPageCount}{\void}
+\constfunc{size\_t}{GetPageCount}{\void}

 
 Returns the number of pages in the notebook control.
 
 
 Returns the number of pages in the notebook control.
 

+

 \membersection{wxNotebook::GetPageImage}\label{wxnotebookgetpageimage}
 
 \membersection{wxNotebook::GetPageImage}\label{wxnotebookgetpageimage}
 

-\constfunc{int}{GetPageImage}{\void}
+\constfunc{int}{GetPageImage}{\param{size\_t }{nPage}}

 
 Returns the image index for the given page.
 
 
 Returns the image index for the given page.
 

+

 \membersection{wxNotebook::GetPageText}\label{wxnotebookgetpagetext}
 
 \membersection{wxNotebook::GetPageText}\label{wxnotebookgetpagetext}
 

-\constfunc{wxString}{GetPageText}{\void}
+\constfunc{wxString}{GetPageText}{\param{size\_t }{nPage}}

 
 Returns the string for the given page.
 
 
 Returns the string for the given page.
 

+

 \membersection{wxNotebook::GetRowCount}\label{wxnotebookgetrowcount}
 
 \constfunc{int}{GetRowCount}{\void}
 
 Returns the number of rows in the notebook control.
 
 \membersection{wxNotebook::GetRowCount}\label{wxnotebookgetrowcount}
 
 \constfunc{int}{GetRowCount}{\void}
 
 Returns the number of rows in the notebook control.
 

+

 \membersection{wxNotebook::GetSelection}\label{wxnotebookgetselection}
 
 \constfunc{int}{GetSelection}{\void}
 
 \membersection{wxNotebook::GetSelection}\label{wxnotebookgetselection}
 
 \constfunc{int}{GetSelection}{\void}
 

-Returns the currently selected page, or -1 if none was selected.
+Returns the currently selected page, or $-1$ if none was selected.
+
+Note that this method may return either the previously or newly selected page
+when called from the {\tt EVT\_NOTEBOOK\_PAGE\_CHANGED} handler depending on
+the platform and so\rtfsp
+\helpref{wxNotebookEvent::GetSelection}{wxnotebookeventgetselection} should be
+used instead in this case.
+
+\membersection{wxNotebook::GetThemeBackgroundColour}\label{wxnotebookgetthemebackgroundcolour}
+
+\constfunc{wxColour}{GetThemeBackgroundColour}{\void}
+
+If running under Windows and themes are enabled for the application, this function
+returns a suitable colour for painting the background of a notebook page, and can be passed
+to {\tt SetBackgroundColour}. Otherwise, an uninitialised colour will be returned.
+
+\membersection{wxNotebook::HitTest}\label{wxnotebookhittest}
+
+\func{int}{HitTest}{\param{const wxPoint\&}{ pt}, \param{long}{ *flags = {\tt NULL}}}
+
+Returns the index of the tab at the specified position or {\tt wxNOT\_FOUND}
+if none. If {\it flags} parameter is non-{\tt NULL}, the position of the point
+inside the tab is returned as well.
+
+\wxheading{Parameters}
+
+\docparam{pt}{Specifies the point for the hit test.}
+
+\docparam{flags}{Return value for detailed information. One of the following values:
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf wxBK\_HITTEST\_NOWHERE}}{There was no tab under this point.}
+\twocolitem{{\bf wxBK\_HITTEST\_ONICON}}{The point was over an icon (currently wxMSW only).}
+\twocolitem{{\bf wxBK\_HITTEST\_ONLABEL}}{The point was over a label (currently wxMSW only).}
+\twocolitem{{\bf wxBK\_HITTEST\_ONITEM}}{The point was over an item, but not on the label or icon.}
+\twocolitem{{\bf wxBK\_HITTEST\_ONPAGE}}{The point was over a currently selected page, not over any tab. Note that this flag is present only if {\tt wxNOT\_FOUND} is returned.}
+\end{twocollist}
+}
+
+\wxheading{Return value}
+
+Returns the zero-based tab index or {\tt wxNOT\_FOUND} if there is no tab is at
+the specified position.
+
+

 
 \membersection{wxNotebook::InsertPage}\label{wxnotebookinsertpage}
 
 
 \membersection{wxNotebook::InsertPage}\label{wxnotebookinsertpage}
 

-\func{bool}{InsertPage}{\param{int}{ index}, \param{wxNotebookPage*}{ page},
+\func{bool}{InsertPage}{\param{size\_t}{ index}, \param{wxNotebookPage*}{ page},

  \param{const wxString\&}{ text},
  \param{const wxString\&}{ text},

- \param{bool}{ select = FALSE},
+ \param{bool}{ select = false},

  \param{int}{ imageId = -1}}
 
 Inserts a new page at the specified position.
  \param{int}{ imageId = -1}}
 
 Inserts a new page at the specified position.


@@ -210,7 +322,7 @@ Inserts a new page at the specified position.
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-TRUE if successful, FALSE otherwise.
+true if successful, false otherwise.

 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 


@@ -220,6 +332,7 @@ Do not delete the page, it will be deleted by the notebook.
 
 \helpref{wxNotebook::AddPage}{wxnotebookaddpage}
 
 
 \helpref{wxNotebook::AddPage}{wxnotebookaddpage}
 

+

 \membersection{wxNotebook::OnSelChange}\label{wxnotebookonselchange}
 
 \func{void}{OnSelChange}{\param{wxNotebookEvent\&}{ event}}
 \membersection{wxNotebook::OnSelChange}\label{wxnotebookonselchange}
 
 \func{void}{OnSelChange}{\param{wxNotebookEvent\&}{ event}}


@@ -230,21 +343,26 @@ An event handler function, called when the page selection is changed.
 
 \helpref{wxNotebookEvent}{wxnotebookevent}
 
 
 \helpref{wxNotebookEvent}{wxnotebookevent}
 

+

 \membersection{wxNotebook::RemovePage}\label{wxnotebookremovepage}
 
 \membersection{wxNotebook::RemovePage}\label{wxnotebookremovepage}
 

-\func{bool}{RemovePage}{\param{int}{ page}}
+\func{bool}{RemovePage}{\param{size\_t}{ page}}

 
 Deletes the specified page, without deleting the associated window.
 
 
 Deletes the specified page, without deleting the associated window.
 

+

 \membersection{wxNotebook::SetImageList}\label{wxnotebooksetimagelist}
 
 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
 
 \membersection{wxNotebook::SetImageList}\label{wxnotebooksetimagelist}
 
 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
 

-Sets the image list for the page control.
+Sets the image list for the page control. It does not take
+ownership of the image list, you must delete it yourself.

 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxImageList}{wximagelist}
+\helpref{wxImageList}{wximagelist},
+\helpref{AssignImageList}{wxnotebookassignimagelist}
+

 
 \membersection{wxNotebook::SetPadding}\label{wxnotebooksetpadding}
 
 
 \membersection{wxNotebook::SetPadding}\label{wxnotebooksetpadding}
 


@@ -252,33 +370,56 @@ Sets the image list for the page control.
 
 Sets the amount of space around each page's icon and label, in pixels.
 
 
 Sets the amount of space around each page's icon and label, in pixels.
 

+{\bf NB:} The vertical padding cannot be changed in wxGTK.
+
+

 \membersection{wxNotebook::SetPageSize}\label{wxnotebooksetpagesize}
 
 \func{void}{SetPageSize}{\param{const wxSize\&}{ size}}
 
 Sets the width and height of the pages.
 
 \membersection{wxNotebook::SetPageSize}\label{wxnotebooksetpagesize}
 
 \func{void}{SetPageSize}{\param{const wxSize\&}{ size}}
 
 Sets the width and height of the pages.
 

+{\bf NB:} This method is currently not implemented for wxGTK.
+
+

 \membersection{wxNotebook::SetPageImage}\label{wxnotebooksetpageimage}
 
 \membersection{wxNotebook::SetPageImage}\label{wxnotebooksetpageimage}
 

-\func{bool}{SetPageImage}{\param{int}{ page}, \param{int }{image}}
+\func{bool}{SetPageImage}{\param{size\_t}{ page}, \param{int }{image}}

 
 Sets the image index for the given page. {\it image} is an index into
 the image list which was set with \helpref{wxNotebook::SetImageList}{wxnotebooksetimagelist}.
 
 
 Sets the image index for the given page. {\it image} is an index into
 the image list which was set with \helpref{wxNotebook::SetImageList}{wxnotebooksetimagelist}.
 

+

 \membersection{wxNotebook::SetPageText}\label{wxnotebooksetpagetext}
 
 \membersection{wxNotebook::SetPageText}\label{wxnotebooksetpagetext}
 

-\func{bool}{SetPageText}{\param{int}{ page}, \param{const wxString\& }{text}}
+\func{bool}{SetPageText}{\param{size\_t}{ page}, \param{const wxString\& }{text}}

 
 Sets the text for the given page.
 
 
 Sets the text for the given page.
 

+

 \membersection{wxNotebook::SetSelection}\label{wxnotebooksetselection}
 
 \membersection{wxNotebook::SetSelection}\label{wxnotebooksetselection}
 

-\func{int}{SetSelection}{\param{int}{ page}}
+\func{int}{SetSelection}{\param{size\_t}{ page}}

 
 Sets the selection for the given page, returning the previous selection.
 
 
 Sets the selection for the given page, returning the previous selection.
 

+The call to this function generates the page changing events.
+
+This function is deprecated and should not be used in new code. Please use the
+\helpref{ChangeSelection}{wxnotebookchangeselection} function instead.
+

 \wxheading{See also}
 
 \helpref{wxNotebook::GetSelection}{wxnotebookgetselection}
 
 
 \wxheading{See also}
 
 \helpref{wxNotebook::GetSelection}{wxnotebookgetselection}
 
 

+\membersection{wxNotebook::ChangeSelection}\label{wxnotebookchangeselection}
+
+\func{int}{ChangeSelection}{\param{size\_t}{ page}}
+
+Changes the selection for the given page, returning the previous selection.
+
+The call to this function \emph{does not} generate the page changing events.
+This is the only difference with \helpref{SetSelection}{wxnotebooksetselection}.
+See \helpref{this topic}{progevent} for more info.
+