don't make read-only text controls editable when enabled

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        collpane.tex
%% Purpose:     wxCollapsiblePane documentation
%% Author:      Francesco Montorsi
%% Created:     2006-10-14
%% RCS-ID:      $Id$
%% Copyright:   (c) 2006 Francesco Montorsi
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxCollapsiblePane}}\label{wxcollapsiblepane}

A collapsible pane is a container with an embedded button-like control which can be
used by the user to collapse or expand the pane's contents.

Once constructed you should use the \helpref{GetPane}{wxcollapsiblepanegetpane}
function to access the pane and add your controls inside it (i.e. use the
\helpref{GetPane}{wxcollapsiblepanegetpane}'s returned pointer as parent for the
controls which must go in the pane, NOT the wxCollapsiblePane itself!).

Note that because of its nature of control which can dynamically (and drastically)
change its size at run-time under user-input, when putting wxCollapsiblePane inside
a \helpref{wxSizer}{wxsizer} you should be careful to add it with a proportion value
of zero; this is because otherwise all other windows with non-null proportion values
would automatically get resized each time the user expands or collapse the pane window
resulting usually in a weird, flickering effect.

Usage sample:

\begin{verbatim}
    wxCollapsiblePane *collpane = new wxCollapsiblePane(this, wxID_ANY, wxT("Details:"));

    // add the pane with a zero proportion value to the 'sz' sizer which contains it
    sz->Add(collpane, 0, wxGROW|wxALL, 5);

    // now add a test label in the collapsible pane using a sizer to layout it:
    wxWindow *win = collpane->GetPane();
    wxSizer *paneSz = new wxBoxSizer(wxVERTICAL);
    paneSz->Add(new wxStaticText(win, wxID_ANY, wxT("test!")), 1, wxGROW|wxALL, 2);
    win->SetSizer(paneSz);
    paneSz->SetSizeHints(win);

\end{verbatim}


It is only available if \texttt{wxUSE\_COLLPANE} is set to $1$ (the default).

\wxheading{Derived from}

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

\wxheading{Include files}

<wx/collpane.h>

\wxheading{Window styles}

\twocolwidtha{5cm}%
\begin{twocollist}\itemsep=0pt
\twocolitem{\windowstyle{wxCP\_DEFAULT\_STYLE}}{The default style: 0.}
\end{twocollist}

\wxheading{Event handling}

To process a collapsible pane event, use these event handler macros to direct input to member
functions that take a \helpref{wxCollapsiblePaneEvent}{wxcollapsiblepaneevent} argument.

\twocolwidtha{7cm}%
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf EVT\_COLLAPSIBLEPANE\_CHANGED(id, func)}}{The user showed or hidden the collapsible pane. }
\end{twocollist}


\wxheading{See also}

\helpref{wxPanel}{wxpanel},\\
\helpref{wxCollapsiblePaneEvent}{wxcollapsiblepaneevent}

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



\membersection{wxCollapsiblePane::wxCollapsiblePane}\label{wxcollapsiblepane}

\func{}{wxCollapsiblePane}{\param{wxWindow *}{parent},\rtfsp
\param{wxWindowID}{ id},\rtfsp
\param{const wxString\& }{label},\rtfsp
\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
\param{long}{ style = wxCP\_DEFAULT\_STYLE},\rtfsp
\param{const wxValidator\& }{validator = wxDefaultValidator},
\param{const wxString\& }{name = ``collapsiblePane"}}

Initializes the object and calls \helpref{Create}{wxcollapsiblepanecreate} with
all the parameters.


\membersection{wxCollapsiblePane::Create}\label{wxcollapsiblepanecreate}

\func{bool}{Create}{\param{wxWindow *}{parent},\rtfsp
\param{wxWindowID}{ id},\rtfsp
\param{const wxString\& }{label},\rtfsp
\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
\param{long}{ style = wxCP\_DEFAULT\_STYLE},\rtfsp
\param{const wxValidator\& }{validator = wxDefaultValidator},
\param{const wxString\& }{name = ``collapsiblePane"}}

\wxheading{Parameters}

\docparam{parent}{Parent window, must not be non-\texttt{NULL}.}

\docparam{id}{The identifier for the control.}

\docparam{label}{The initial label shown in the button which allows the user to expand or collapse the pane window.}

\docparam{pos}{Initial position.}

\docparam{size}{Initial size.}

\docparam{style}{The window style, see {\tt wxCP\_*} flags.}

\docparam{validator}{Validator which can be used for additional date checks.}

\docparam{name}{Control name.}

\wxheading{Return value}

\true if the control was successfully created or \false if creation failed.


\membersection{wxCollapsiblePane::IsCollapsed}\label{wxcollapsiblepaneiscollapsed}

\constfunc{bool}{IsCollapsed}{\void}

Returns \true if the pane window is currently hidden.


\membersection{wxCollapsiblePane::IsExpanded}\label{wxcollapsiblepaneisexpanded}

\constfunc{bool}{IsExpanded}{\void}

Returns \true if the pane window is currently shown.


\membersection{wxCollapsiblePane::Collapse}\label{wxcollapsiblepanecollapse}

\func{void}{Collapse}{\param{bool }{collapse = true}}

Collapses or expands the pane window.


\membersection{wxCollapsiblePane::Expand}\label{wxcollapsiblepaneexpand}

\func{void}{Expand}{\void}

Same as \texttt{\helpref{Collapse}{wxcollapsiblepanecollapse}(false)}.


\membersection{wxCollapsiblePane::GetPane}\label{wxcollapsiblepanegetpane}

\constfunc{wxWindow *}{GetPane}{\void}

Returns a pointer to the pane window. Add controls to the returned \helpref{wxWindow}{wxwindow}
to make them collapsible.





%% wxCollapsiblePaneEvent documentation

\section{\class{wxCollapsiblePaneEvent}}\label{wxcollapsiblepaneevent}

This event class is used for the events generated by
\helpref{wxCollapsiblePane}{wxcollapsiblepane}.

\wxheading{Derived from}

\helpref{wxCommandEvent}{wxcommandevent}\\
\helpref{wxEvent}{wxevent}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/collpane.h>

\wxheading{Event handling}

To process input from a wxCollapsiblePane, use one of these event handler macros to
direct input to member function that take a
\helpref{wxCollapsiblePaneEvent}{wxcollapsiblepaneevent} argument:

\twocolwidtha{7cm}
\begin{twocollist}
\twocolitem{{\bf EVT\_COLLAPSIBLEPANE\_CHANGED(id, func)}}{The user showed or hidden the collapsible pane.}
\end{twocollist}%


\wxheading{See also}

\helpref{wxCollapsiblePane}{wxcollapsiblepane}

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

\membersection{wxCollapsiblePaneEvent::wxCollapsiblePaneEvent}\label{wxcollapsiblepaneeventctor}

\func{}{wxCollapsiblePaneEvent}{\param{wxObject *}{ generator}, \param{int}{ id}, \param{bool}{ collapsed}}

The constructor is not normally used by the user code.


\membersection{wxCollapsiblePaneEvent::GetCollapsed}\label{wxcollapsiblepaneeventgetcollapsed}

\constfunc{bool}{GetCollapsed}{\void}

Returns \true if the pane has been collapsed.


\membersection{wxCollapsiblePaneEvent::SetCollapsed}\label{wxcollapsiblepaneeventsetcollapsed}

\func{void}{SetCollapsed}{\param{bool}{ collapsed}}

Sets this as a collapsed pane event (if \arg{collapsed} is \true) or as an expanded
pane event (if \arg{collapsed} is \false).