docs/latex/wx/view.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        view.tex
   3 %% Purpose:     wxView documentation
   4 %% Author:      wxWidgets Team
   5 %% Modified by:
   6 %% Created:
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) wxWidgets Team
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxView}}\label{wxview}
  13
  14 The view class can be used to model the viewing and editing component of
  15 an application's file-based data. It is part of the document/view framework supported by wxWidgets,
  16 and cooperates with the \helpref{wxDocument}{wxdocument}, \helpref{wxDocTemplate}{wxdoctemplate}
  17 and \helpref{wxDocManager}{wxdocmanager} classes.
  18
  19 \wxheading{Derived from}
  20
  21 \helpref{wxEvtHandler}{wxevthandler}\\
  22 \helpref{wxObject}{wxobject}
  23
  24 \wxheading{Include files}
  25
  26 <wx/docview.h>
  27
  28 \wxheading{Library}
  29
  30 \helpref{wxCore}{librarieslist}
  31
  32 \wxheading{See also}
  33
  34 \helpref{wxView overview}{wxviewoverview}, \helpref{wxDocument}{wxdocument}, \helpref{wxDocTemplate}{wxdoctemplate},\rtfsp
  35 \helpref{wxDocManager}{wxdocmanager}
  36
  37 \latexignore{\rtfignore{\wxheading{Members}}}
  38
  39 \membersection{wxView::m\_viewDocument}\label{wxviewmviewdocument}
  40
  41 \member{wxDocument*}{m\_viewDocument}
  42
  43 The document associated with this view. There may be more than one view per
  44 document, but there can never be more than one document for one view.
  45
  46 \membersection{wxView::m\_viewFrame}\label{wxviewmviewframe}
  47
  48 \member{wxFrame*}{m\_viewFrame}
  49
  50 Frame associated with the view, if any.
  51
  52 \membersection{wxView::m\_viewTypeName}\label{wxviewmviewtypename}
  53
  54 \member{wxString}{m\_viewTypeName}
  55
  56 The view type name given to the wxDocTemplate constructor, copied to this
  57 variable when the view is created. Not currently used by the framework.
  58
  59 \membersection{wxView::wxView}\label{wxviewctor}
  60
  61 \func{}{wxView}{\void}
  62
  63 Constructor. Define your own default constructor to initialize application-specific
  64 data.
  65
  66 \membersection{wxView::\destruct{wxView}}\label{wxviewdtor}
  67
  68 \func{}{\destruct{wxView}}{\void}
  69
  70 Destructor. Removes itself from the document's list of views.
  71
  72 \membersection{wxView::Activate}\label{wxviewactivate}
  73
  74 \func{virtual void}{Activate}{\param{bool}{ activate}}
  75
  76 Call this from your view frame's OnActivate member to tell the framework which view is
  77 currently active. If your windowing system doesn't call OnActivate, you may need to
  78 call this function from any place where you know the view must
  79 be active, and the framework will need to get the current view.
  80
  81 The prepackaged view frame wxDocChildFrame calls wxView::Activate from its OnActivate member.
  82
  83 This function calls wxView::OnActivateView.
  84
  85 \membersection{wxView::Close}\label{wxviewclose}
  86
  87 \func{virtual bool}{Close}{\param{bool}{ deleteWindow = true}}
  88
  89 Closes the view by calling OnClose. If {\it deleteWindow} is true, this function should
  90 delete the window associated with the view.
  91
  92 \membersection{wxView::GetDocument}\label{wxviewgetdocument}
  93
  94 \constfunc{wxDocument*}{GetDocument}{\void}
  95
  96 Gets a pointer to the document associated with the view.
  97
  98 \membersection{wxView::GetDocumentManager}\label{wxviewgetdocumentmanager}
  99
 100 \constfunc{wxDocManager*}{GetDocumentManager}{\void}
 101
 102 Returns a pointer to the document manager instance associated with this view.
 103
 104 \membersection{wxView::GetFrame}\label{wxviewgetframe}
 105
 106 \func{wxWindow *}{GetFrame}{\void}
 107
 108 Gets the frame associated with the view (if any). Note that this ``frame'' is
 109 not a wxFrame at all in the generic MDI implementation which uses the notebook
 110 pages instead of the frames and this is why this method returns a wxWindow and
 111 not a wxFrame.
 112
 113 \membersection{wxView::GetViewName}\label{wxviewgetviewname}
 114
 115 \constfunc{wxString}{GetViewName}{\void}
 116
 117 Gets the name associated with the view (passed to the wxDocTemplate constructor).
 118 Not currently used by the framework.
 119
 120 \membersection{wxView::OnActivateView}\label{wxviewonactivateview}
 121
 122 \func{virtual void}{OnActivateView}{\param{bool }{activate}, \param{wxView *}{activeView}, \param{wxView *}{deactiveView}}
 123
 124 Called when a view is activated by means of wxView::Activate. The default implementation does
 125 nothing.
 126
 127 \membersection{wxView::OnChangeFilename}\label{wxviewonchangefilename}
 128
 129 \func{virtual void}{OnChangeFilename}{\void}
 130
 131 Called when the filename has changed. The default implementation constructs a
 132 suitable title and sets the title of the view frame (if any).
 133
 134 \membersection{wxView::OnClose}\label{wxviewonclose}
 135
 136 \func{virtual bool}{OnClose}{\param{bool}{ deleteWindow}}
 137
 138 Implements closing behaviour. The default implementation calls wxDocument::Close
 139 to close the associated document. Does not delete the view. The application
 140 may wish to do some cleaning up operations in this function, {\it if} a
 141 call to wxDocument::Close succeeded. For example, if your views
 142 all share the same window, you need to disassociate the window from the view
 143 and perhaps clear the window. If {\it deleteWindow} is true, delete the
 144 frame associated with the view.
 145
 146 \membersection{wxView::OnClosingDocument}\label{wxviewonclosingdocument}
 147
 148 \func{virtual void}{OnClosingDocument}{\void}
 149
 150 Override this to clean up the view when the document is being
 151 closed.
 152
 153 \membersection{wxView::OnCreate}\label{wxviewoncreate}
 154
 155 \func{virtual bool}{OnCreate}{\param{wxDocument* }{doc}, \param{long}{ flags}}
 156
 157 wxDocManager or wxDocument creates a wxView via a wxDocTemplate.
 158 Just after the wxDocTemplate creates the wxView, it calls
 159 wxView::OnCreate. In its OnCreate member function, the wxView can create a wxDocChildFrame
 160 or a derived class. This wxDocChildFrame provides user interface
 161 elements to view and/or edit the contents of the wxDocument.
 162
 163 By default, simply returns true. If the function returns false, the
 164 view will be deleted.
 165
 166 \membersection{wxView::OnCreatePrintout}\label{wxviewoncreateprintout}
 167
 168 \func{virtual wxPrintout*}{OnCreatePrintout}{\void}
 169
 170 If the printing framework is enabled in the library, this function returns a
 171 \rtfsp\helpref{wxPrintout}{wxprintout} object for the purposes of printing. It should create a new object
 172 every time it is called; the framework will delete objects it creates.
 173
 174 By default, this function returns an instance of wxDocPrintout, which prints
 175 and previews one page by calling wxView::OnDraw.
 176
 177 Override to return an instance of a class other than wxDocPrintout.
 178
 179 \membersection{wxView::OnDraw}\label{onviewondraw}
 180
 181 \func{virtual void}{OnDraw}{\param{wxDC* }{dc}}
 182
 183 Override this function to render the view on the given device context.
 184
 185 \membersection{wxView::OnUpdate}\label{onviewonupdate}
 186
 187 \func{virtual void}{OnUpdate}{\param{wxView* }{sender}, \param{wxObject* }{hint}}
 188
 189 Called when the view should be updated. {\it sender} is a pointer to the view
 190 that sent the update request, or NULL if no single view requested the update (for instance,
 191 when the document is opened). {\it hint} is as yet unused but may in future contain
 192 application-specific information for making updating more efficient.
 193
 194 \membersection{wxView::SetDocument}\label{wxviewsetdocument}
 195
 196 \func{void}{SetDocument}{\param{wxDocument* }{doc}}
 197
 198 Associates the given document with the view. Normally called by the
 199 framework.
 200
 201 \membersection{wxView::SetFrame}\label{wxviewsetframe}
 202
 203 \func{void}{SetFrame}{\param{wxWindow* }{frame}}
 204
 205 Sets the frame associated with this view. The application should call this
 206 if possible, to tell the view about the frame.
 207
 208 See \helpref{GetFrame}{wxviewgetframe} for the explanation about the mismatch
 209 between the ``Frame'' in the method name and the type of its parameter.
 210
 211 \membersection{wxView::SetViewName}\label{wxviewsetviewname}
 212
 213 \func{void}{SetViewName}{\param{const wxString\& }{name}}
 214
 215 Sets the view type name. Should only be called by the framework.
 216