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