no changes, just come cleanup and more comments

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

\section{\class{wxDocTemplate}}\label{wxdoctemplate}

The wxDocTemplate class is used to model the relationship between a
document class and a view class.

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/docview.h>

\wxheading{Library}

\helpref{wxCore}{librarieslist}

\wxheading{See also}

\helpref{wxDocTemplate overview}{wxdoctemplateoverview}, \helpref{wxDocument}{wxdocument}, \helpref{wxView}{wxview}

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

\membersection{wxDocTemplate::m\_defaultExt}\label{wxdoctemplatemdefaultext}

\member{wxString}{m\_defaultExt}

The default extension for files of this type.

\membersection{wxDocTemplate::m\_description}\label{wxdoctemplatemdescription}

\member{wxString}{m\_description}

A short description of this template.

\membersection{wxDocTemplate::m\_directory}\label{wxdoctemplatemdirectory}

\member{wxString}{m\_directory}

The default directory for files of this type.

\membersection{wxDocTemplate::m\_docClassInfo}\label{wxdoctemplatemdocclassinfo}

\member{wxClassInfo* }{m\_docClassInfo}

Run-time class information that allows document instances to be constructed dynamically.

\membersection{wxDocTemplate::m\_docTypeName}\label{wxdoctemplatemdoctypename}

\member{wxString}{m\_docTypeName}

The named type of the document associated with this template.

\membersection{wxDocTemplate::m\_documentManager}\label{wxdoctemplatedocumentmanager}

\member{wxDocTemplate*}{m\_documentManager}

A pointer to the document manager for which this template was created.

\membersection{wxDocTemplate::m\_fileFilter}\label{wxdoctemplatemfilefilter}

\member{wxString}{m\_fileFilter}

The file filter (such as {\tt *.txt}) to be used in file selector dialogs.

\membersection{wxDocTemplate::m\_flags}\label{wxdoctemplatemflags}

\member{long}{m\_flags}

The flags passed to the constructor.

\membersection{wxDocTemplate::m\_viewClassInfo}\label{wxdoctemplatemviewclassinfo}

\member{wxClassInfo*}{m\_viewClassInfo}

Run-time class information that allows view instances to be constructed dynamically.

\membersection{wxDocTemplate::m\_viewTypeName}\label{wxdoctemplatemviewtypename}

\member{wxString}{m\_viewTypeName}

The named type of the view associated with this template.

\membersection{wxDocTemplate::wxDocTemplate}\label{wxdoctemplatector}

\func{}{wxDocTemplate}{\param{wxDocManager* }{manager}, \param{const wxString\& }{descr}, \param{const wxString\& }{filter},
 \param{const wxString\& }{dir}, \param{const wxString\& }{ext}, \param{const wxString\& }{docTypeName},
 \param{const wxString\& }{viewTypeName}, \param{wxClassInfo* }{docClassInfo = NULL},
 \param{wxClassInfo* }{viewClassInfo = NULL}, \param{long}{ flags = wxDEFAULT\_TEMPLATE\_FLAGS}}

Constructor. Create instances dynamically near the start of your application after creating
a wxDocManager instance, and before doing any document or view operations.

{\it manager} is the document manager object which manages this template.

{\it descr} is a short description of what the template is for. This string will be displayed in the
file filter list of Windows file selectors.

{\it filter} is an appropriate file filter such as {\tt *.txt}.

{\it dir} is the default directory to use for file selectors.

{\it ext} is the default file extension (such as txt).

{\it docTypeName} is a name that should be unique for a given type of document, used for
gathering a list of views relevant to a particular document.

{\it viewTypeName} is a name that should be unique for a given view.

{\it docClassInfo} is a pointer to the run-time document class information as returned
by the CLASSINFO macro, e.g. CLASSINFO(MyDocumentClass). If this is not supplied,
you will need to derive a new wxDocTemplate class and override the CreateDocument
member to return a new document instance on demand.

{\it viewClassInfo} is a pointer to the run-time view class information as returned
by the CLASSINFO macro, e.g. CLASSINFO(MyViewClass). If this is not supplied,
you will need to derive a new wxDocTemplate class and override the CreateView
member to return a new view instance on demand.

{\it flags} is a bit list of the following:

\begin{itemize}\itemsep=0pt
\item wxTEMPLATE\_VISIBLE The template may be displayed to the user in dialogs.
\item wxTEMPLATE\_INVISIBLE The template may not be displayed to the user in dialogs.
\item wxDEFAULT\_TEMPLATE\_FLAGS Defined as wxTEMPLATE\_VISIBLE.
\end{itemize}

\perlnote{In wxPerl {\tt docClassInfo} and {\tt viewClassInfo} can be
either {\tt Wx::ClassInfo} objects or strings which contain the name
of the perl packages which are to be used as {\tt Wx::Document} and
{\tt Wx::View} classes (they must have a constructor named {\tt
new}):

\indented{2cm}{\begin{twocollist}
\twocolitem{{\bf Wx::DocTemplate->new( docmgr, descr, filter, dir,
ext, docTypeName, viewTypeName, docClassInfo, viewClassInfo, flags
)}}{ will construct document and view objects from the class information}
\twocolitem{{\bf Wx::DocTemplate->new( docmgr, descr, filter, dir,
ext, docTypeName, viewTypeName, docClassName, viewClassName, flags
)}}{ will construct document and view objects from perl packages}
\twocolitem{{\bf Wx::DocTemplate->new( docmgr, descr, filter, dir,
ext, docTypeName, viewTypeName )}}{
{\tt Wx::DocTemplate::CreateDocument()} and
{\tt Wx::DocTemplate::CreateView()} must be overridden}
\end{twocollist}}}

\membersection{wxDocTemplate::\destruct{wxDocTemplate}}\label{wxdoctemplatedtor}

\func{void}{\destruct{wxDocTemplate}}{\void}

Destructor.

\membersection{wxDocTemplate::CreateDocument}\label{wxdoctemplatecreatedocument}

\func{wxDocument *}{CreateDocument}{\param{const wxString\& }{path}, \param{long}{ flags = 0}}

Creates a new instance of the associated document class. If you have not supplied
a wxClassInfo parameter to the template constructor, you will need to override this
function to return an appropriate document instance.

This function calls wxDocTemplate::InitDocument which in turns
calls wxDocument::OnCreate.

\membersection{wxDocTemplate::CreateView}\label{wxdoctemplatecreateview}

\func{wxView *}{CreateView}{\param{wxDocument *}{doc}, \param{long}{ flags = 0}}

Creates a new instance of the associated view class. If you have not supplied
a wxClassInfo parameter to the template constructor, you will need to override this
function to return an appropriate view instance.

\membersection{wxDocTemplate::GetDefaultExtension}\label{wxdoctemplategetdefaultextension}

\func{wxString}{GetDefaultExtension}{\void}

Returns the default file extension for the document data, as passed to the document template constructor.

\membersection{wxDocTemplate::GetDescription}\label{wxdoctemplategetdescription}

\func{wxString}{GetDescription}{\void}

Returns the text description of this template, as passed to the document template constructor.

\membersection{wxDocTemplate::GetDirectory}\label{wxdoctemplategetdirectory}

\func{wxString}{GetDirectory}{\void}

Returns the default directory, as passed to the document template constructor.

\membersection{wxDocTemplate::GetDocumentManager}\label{wxdoctemplategetdocumentmanager}

\func{wxDocManager *}{GetDocumentManager}{\void}

Returns a pointer to the document manager instance for which this template was created.

\membersection{wxDocTemplate::GetDocumentName}\label{wxdoctemplategetdocumentname}

\func{wxString}{GetDocumentName}{\void}

Returns the document type name, as passed to the document template constructor.

\membersection{wxDocTemplate::GetFileFilter}\label{wxdoctemplategetfilefilter}

\func{wxString}{GetFileFilter}{\void}

Returns the file filter, as passed to the document template constructor.

\membersection{wxDocTemplate::GetFlags}\label{wxdoctemplategetflags}

\func{long}{GetFlags}{\void}

Returns the flags, as passed to the document template constructor.

\membersection{wxDocTemplate::GetViewName}\label{wxdoctemplategetviewname}

\func{wxString}{GetViewName}{\void}

Returns the view type name, as passed to the document template constructor.

\membersection{wxDocTemplate::InitDocument}\label{wxdoctemplateinitdocument}

\func{bool}{InitDocument}{\param{wxDocument* }{doc}, \param{const wxString\& }{path}, \param{long}{ flags = 0}}

Initialises the document, calling wxDocument::OnCreate. This is called from
wxDocTemplate::CreateDocument.

\membersection{wxDocTemplate::IsVisible}\label{wxdoctemplateisvisible}

\func{bool}{IsVisible}{\void}

Returns true if the document template can be shown in user dialogs, false otherwise.

\membersection{wxDocTemplate::SetDefaultExtension}\label{wxdoctemplatesetdefaultextension}

\func{void}{SetDefaultExtension}{\param{const wxString\& }{ext}}

Sets the default file extension.

\membersection{wxDocTemplate::SetDescription}\label{wxdoctemplatesetdescription}

\func{void}{SetDescription}{\param{const wxString\& }{descr}}

Sets the template description.

\membersection{wxDocTemplate::SetDirectory}\label{wxdoctemplatesetdirectory}

\func{void}{SetDirectory}{\param{const wxString\& }{dir}}

Sets the default directory.

\membersection{wxDocTemplate::SetDocumentManager}\label{wxdoctemplatesetdocumentmanager}

\func{void}{SetDocumentManager}{\param{wxDocManager *}{manager}}

Sets the pointer to the document manager instance for which this template was created.
Should not be called by the application.

\membersection{wxDocTemplate::SetFileFilter}\label{wxdoctemplatesetfilefilter}

\func{void}{SetFileFilter}{\param{const wxString\& }{filter}}

Sets the file filter.

\membersection{wxDocTemplate::SetFlags}\label{wxdoctemplatesetflags}

\func{void}{SetFlags}{\param{long }{flags}}

Sets the internal document template flags (see the constructor description for more details).