X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4e5d278c12ccc50bb04d9ca20ec97ca380a7d94b..db679b8c836e69c111cdc31e62cf92cebe4f938f:/wxPython/wx/lib/docview.py?ds=inline diff --git a/wxPython/wx/lib/docview.py b/wxPython/wx/lib/docview.py index 9512cf5226..2dd76d012a 100644 --- a/wxPython/wx/lib/docview.py +++ b/wxPython/wx/lib/docview.py @@ -1,6 +1,6 @@ #---------------------------------------------------------------------------- # Name: docview.py -# Purpose: Port of the wxWidgets docview classes +# Purpose: Port of the wxWindows docview classes # # Author: Peter Yared # @@ -10,11 +10,6 @@ # License: wxWindows license #---------------------------------------------------------------------------- -""" -A port of the wxWidgets doc/view classes to Python. - -:see: `pydocview` -""" import os import os.path @@ -78,10 +73,9 @@ def PathOnly(path): class Document(wx.EvtHandler): """ - The document class can be used to model an application's - file-based data. It is part of the document/view framework, and - cooperates with the `View`, `DocTemplate` and `DocManager` - classes. + The document class can be used to model an application's file-based data. It + is part of the document/view framework supported by wxWindows, and cooperates + with the wxView, wxDocTemplate and wxDocManager classes. Note this wxPython version also keeps track of the modification date of the document and if it changes on disk outside of the application, we will warn the @@ -89,7 +83,7 @@ class Document(wx.EvtHandler): """ - def __init__(self, parent = None): + def __init__(self, parent=None): """ Constructor. Define your own default constructor to initialize application-specific data. @@ -148,10 +142,10 @@ class Document(wx.EvtHandler): def GetDocumentName(self): """ - The document type name given to the `DocTemplate` constructor, + The document type name given to the wxDocTemplate constructor, copied to this document when the document is created. If several document templates are created that use the same document type, this - variable is used in `DocManager.CreateView` to collate a list of + variable is used in wxDocManager::CreateView to collate a list of alternative view types that can be used on this kind of document. """ return self._documentTypeName @@ -159,10 +153,10 @@ class Document(wx.EvtHandler): def SetDocumentName(self, name): """ - Sets the document type name given to the `DocTemplate` constructor, + Sets he document type name given to the wxDocTemplate constructor, copied to this document when the document is created. If several document templates are created that use the same document type, this - variable is used in `DocManager.CreateView` to collate a list of + variable is used in wxDocManager::CreateView to collate a list of alternative view types that can be used on this kind of document. Do not change the value of this variable. """ @@ -171,14 +165,16 @@ class Document(wx.EvtHandler): def GetDocumentSaved(self): """ - Returns True if the document has been saved. + Returns True if the document has been saved. This method has been + added to wxPython and is not in wxWindows. """ return self._savedYet - def SetDocumentSaved(self, saved = True): + def SetDocumentSaved(self, saved=True): """ - Sets whether the document has been saved. + Sets whether the document has been saved. This method has been + added to wxPython and is not in wxWindows. """ self._savedYet = saved @@ -194,7 +190,7 @@ class Document(wx.EvtHandler): """ Sets the command processor to be used for this document. The document will then be responsible for its deletion. Normally you should not - call this; override `OnCreateCommandProcessor` instead. + call this; override OnCreateCommandProcessor instead. """ self._commandProcessor = processor @@ -214,7 +210,7 @@ class Document(wx.EvtHandler): Call with true to mark the document as modified since the last save, false otherwise. You may need to override this if your document view maintains its own record of being modified (for example if using - `wx.TextCtrl` to view and edit the document). + xTextWindow to view and edit the document). """ self._documentModified = modify @@ -223,6 +219,7 @@ class Document(wx.EvtHandler): """ Saves the file's last modification date. This is used to check if the file has been modified outside of the application. + This method has been added to wxPython and is not in wxWindows. """ self._documentModificationDate = os.path.getmtime(self.GetFilename()) @@ -231,6 +228,7 @@ class Document(wx.EvtHandler): """ Returns the file's modification date when it was loaded from disk. This is used to check if the file has been modified outside of the application. + This method has been added to wxPython and is not in wxWindows. """ return self._documentModificationDate @@ -277,10 +275,9 @@ class Document(wx.EvtHandler): def Close(self): """ - Closes the document, by calling `OnSaveModified` and then (if - this returns True) `OnCloseDocument`. This does not normally - delete the document object: use DeleteAllViews to do this - implicitly. + Closes the document, by calling OnSaveModified and then (if this true) + OnCloseDocument. This does not normally delete the document object: + use DeleteAllViews to do this implicitly. """ if self.OnSaveModified(): if self.OnCloseDocument(): @@ -293,10 +290,9 @@ class Document(wx.EvtHandler): def OnCloseDocument(self): """ - The default implementation calls `DeleteContents` (an empty - implementation) sets the modified flag to false. Override this - to supply additional behaviour when the document is closed - with `Close`. + The default implementation calls DeleteContents (an empty + implementation) sets the modified flag to false. Override this to + supply additional behaviour when the document is closed with Close. """ self.NotifyClosing() self.DeleteContents() @@ -306,9 +302,9 @@ class Document(wx.EvtHandler): def DeleteAllViews(self): """ - Calls `View.Close` and deletes each view. Deleting the final view will - implicitly delete the document itself, because the `View` destructor - calls `RemoveView`. This in turns calls `Document.OnChangedViewList`, + Calls wxView.Close and deletes each view. Deleting the final view will + implicitly delete the document itself, because the wxView destructor + calls RemoveView. This in turns calls wxDocument::OnChangedViewList, whose default implemention is to save and delete the document if no views exist. """ @@ -342,10 +338,9 @@ class Document(wx.EvtHandler): def OnNewDocument(self): """ - The default implementation calls `OnSaveModified` and - `DeleteContents`, makes a default title for the document, and - notifies the views that the filename (in fact, the title) has - changed. + The default implementation calls OnSaveModified and DeleteContents, + makes a default title for the document, and notifies the views that + the filename (in fact, the title) has changed. """ if not self.OnSaveModified() or not self.OnCloseDocument(): return False @@ -359,8 +354,8 @@ class Document(wx.EvtHandler): def Save(self): """ - Saves the document by calling `OnSaveDocument` if there is an - associated filename, or `SaveAs` if there is no filename. + Saves the document by calling OnSaveDocument if there is an associated + filename, or SaveAs if there is no filename. """ if not self.IsModified(): # and self._savedYet: This was here, but if it is not modified who cares if it hasn't been saved yet? return True @@ -389,7 +384,7 @@ class Document(wx.EvtHandler): def SaveAs(self): """ - Prompts the user for a file to save to, and then calls `OnSaveDocument`. + Prompts the user for a file to save to, and then calls OnSaveDocument. """ docTemplate = self.GetDocumentTemplate() if not docTemplate: @@ -428,9 +423,9 @@ class Document(wx.EvtHandler): def OnSaveDocument(self, filename): """ Constructs an output file for the given filename (which must - not be empty), and calls `SaveObject`. If `SaveObject` returns - true, the document is set to unmodified; otherwise, an error - message box is displayed. + not be empty), and calls SaveObject. If SaveObject returns true, the + document is set to unmodified; otherwise, an error message box is + displayed. """ if not filename: return False @@ -461,6 +456,7 @@ class Document(wx.EvtHandler): fileObject = file(filename, 'w') self.SaveObject(fileObject) + fileObject.close() if backupFilename: os.remove(backupFilename) @@ -489,7 +485,7 @@ class Document(wx.EvtHandler): def OnOpenDocument(self, filename): """ Constructs an input file for the given filename (which must not - be empty), and calls `LoadObject`. If `LoadObject` returns true, the + be empty), and calls LoadObject. If LoadObject returns true, the document is set to unmodified; otherwise, an error message box is displayed. The document's views are notified that the filename has changed, to give windows an opportunity to update their titles. All of @@ -522,26 +518,24 @@ class Document(wx.EvtHandler): def LoadObject(self, file): """ - Override this function and call it from your own `LoadObject` - before loading your own data. `LoadObject` is called by the - framework automatically when the document contents need to be - loaded. + Override this function and call it from your own LoadObject before + loading your own data. LoadObject is called by the framework + automatically when the document contents need to be loaded. - Note that the wxPython version simply sends you a Python file - object, so you can use pickle. + Note that the wxPython version simply sends you a Python file object, + so you can use pickle. """ return True def SaveObject(self, file): """ - Override this function and call it from your own `SaveObject` - before saving your own data. `SaveObject` is called by the - framework automatically when the document contents need to be - saved. + Override this function and call it from your own SaveObject before + saving your own data. SaveObject is called by the framework + automatically when the document contents need to be saved. - Note that the wxPython version simply sends you a Python file - object, so you can use pickle. + Note that the wxPython version simply sends you a Python file object, + so you can use pickle. """ return True @@ -582,19 +576,18 @@ class Document(wx.EvtHandler): def OnCreateCommandProcessor(self): """ Override this function if you want a different (or no) command - processor to be created when the document is created. By - default, it returns an instance of `CommandProcessor`. + processor to be created when the document is created. By default, it + returns an instance of wxCommandProcessor. """ return CommandProcessor() def OnSaveModified(self): """ - If the document has been modified, prompts the user to ask if - the changes should be changed. If the user replies Yes, the - `Save` function is called. If No, the document is marked as - unmodified and the function succeeds. If Cancel, the function - fails. + If the document has been modified, prompts the user to ask if the + changes should be changed. If the user replies Yes, the Save function + is called. If No, the document is marked as unmodified and the + function succeeds. If Cancel, the function fails. """ if not self.IsModified(): return True @@ -645,7 +638,7 @@ class Document(wx.EvtHandler): def AddView(self, view): """ If the view is not already in the list of views, adds the view and - calls `OnChangedViewList`. + calls OnChangedViewList. """ if not view in self._documentViews: self._documentViews.append(view) @@ -656,7 +649,7 @@ class Document(wx.EvtHandler): def RemoveView(self, view): """ Removes the view from the document's list of views, and calls - `OnChangedViewList`. + OnChangedViewList. """ if view in self._documentViews: self._documentViews.remove(view) @@ -666,7 +659,7 @@ class Document(wx.EvtHandler): def OnCreate(self, path, flags): """ - The default implementation calls `DeleteContents` (an empty + The default implementation calls DeleteContents (an empty implementation) sets the modified flag to false. Override this to supply additional behaviour when the document is closed with Close. """ @@ -686,7 +679,7 @@ class Document(wx.EvtHandler): def UpdateAllViews(self, sender = None, hint = None): """ - Updates all views. If sender is non-None, does not update this view. + Updates all views. If sender is non-NULL, does not update this view. hint represents optional information to allow a view to optimize its update. """ @@ -706,7 +699,7 @@ class Document(wx.EvtHandler): def SetFilename(self, filename, notifyViews = False): """ Sets the filename for this document. Usually called by the framework. - If notifyViews is true, `View.OnChangeFilename` is called for all + If notifyViews is true, wxView.OnChangeFilename is called for all views. """ self._documentFile = filename @@ -730,19 +723,20 @@ class Document(wx.EvtHandler): def SetWriteable(self, writeable): """ - Set to False if the document can not be saved. This will - disable the ID_SAVE_AS event and is useful for custom - documents that should not be saveable. The ID_SAVE event can - be disabled by never modifying the document. + Set to False if the document can not be saved. This will disable the ID_SAVE_AS + event and is useful for custom documents that should not be saveable. The ID_SAVE + event can be disabled by never Modifying the document. This method has been added + to wxPython and is not in wxWindows. """ self._writeable = writeable class View(wx.EvtHandler): """ - The view class can be used to model the viewing and editing - component of an application's file-based data. It cooperates - with the `Document`, `DocTemplate` and `DocManager` classes. + The view class can be used to model the viewing and editing component of + an application's file-based data. It is part of the document/view + framework supported by wxWindows, and cooperates with the wxDocument, + wxDocTemplate and wxDocManager classes. """ def __init__(self): @@ -789,7 +783,7 @@ class View(wx.EvtHandler): def OnActivateView(self, activate, activeView, deactiveView): """ - Called when a view is activated by means of `View.Activate`. The + Called when a view is activated by means of wxView::Activate. The default implementation does nothing. """ pass @@ -814,15 +808,15 @@ class View(wx.EvtHandler): def OnPrint(self, dc, info): """ Override this to print the view for the printing framework. The - default implementation calls `View.OnDraw`. + default implementation calls View.OnDraw. """ self.OnDraw(dc) def OnUpdate(self, sender, hint): """ - Called when the view should be updated. sender is a reference to the - view that sent the update request, or None if no single view requested + Called when the view should be updated. sender is a pointer to the + view that sent the update request, or NULL if no single view requested the update (for instance, when the document is opened). hint is as yet unused but may in future contain application-specific information for making updating more efficient. @@ -870,7 +864,7 @@ class View(wx.EvtHandler): def GetViewName(self): """ - Gets the name associated with the view (passed to the `DocTemplate` + Gets the name associated with the view (passed to the wxDocTemplate constructor). Not currently used by the framework. """ return self._viewTypeName @@ -883,9 +877,9 @@ class View(wx.EvtHandler): self._viewTypeName = name - def Close(self, deleteWindow = True): + def Close(self, deleteWindow=True): """ - Closes the view by calling `OnClose`. If deleteWindow is true, this + Closes the view by calling OnClose. If deleteWindow is true, this function should delete the window associated with the view. """ if self.OnClose(deleteWindow = deleteWindow): @@ -894,28 +888,28 @@ class View(wx.EvtHandler): return False - def Activate(self, activate = True): + def Activate(self, activate=True): """ - Call this from your view frame's EVT_ACTIVATE handler to tell - the framework which view is currently active. If your - windowing system doesn't support EVT_ACTIVATE, you may need to - call this function from an EVT_MENU handler, or any place - where you know the view must be active, and the framework will - need to get the current view. + Call this from your view frame's OnActivate member to tell the + framework which view is currently active. If your windowing system + doesn't call OnActivate, you may need to call this function from + OnMenuCommand or any place where you know the view must be active, and + the framework will need to get the current view. + + The prepackaged view frame wxDocChildFrame calls wxView.Activate from + its OnActivate member and from its OnMenuCommand member. """ if self.GetDocument() and self.GetDocumentManager(): - self.OnActivateView(activate, - self, - self.GetDocumentManager().GetCurrentView()) + self.OnActivateView(activate, self, self.GetDocumentManager().GetCurrentView()) self.GetDocumentManager().ActivateView(self, activate) - def OnClose(self, deleteWindow = True): + def OnClose(self, deleteWindow=True): """ Implements closing behaviour. The default implementation calls - `Document.Close` to close the associated document. Does not delete the + wxDocument.Close to close the associated document. Does not delete the view. The application may wish to do some cleaning up operations in - this function, if a call to `Document.Close` succeeded. For example, + this function, if a call to wxDocument::Close succeeded. For example, if your application's all share the same window, you need to disassociate the window from the view and perhaps clear the window. If deleteWindow is true, delete the frame associated with the view. @@ -928,11 +922,11 @@ class View(wx.EvtHandler): def OnCreate(self, doc, flags): """ - `DocManager` or `Document` creates a `View` via a `DocTemplate`. Just - after the `DocTemplate` creates the `View`, it calls `View.OnCreate`. - In its `OnCreate` member function, the `View` can create a - `DocChildFrame` or a derived class. This `DocChildFrame` provides user - interface elements to view and/or edit the contents of the `Document`. + wxDocManager or wxDocument creates a wxView via a wxDocTemplate. Just + after the wxDocTemplate creates the wxView, it calls wxView::OnCreate. + In its OnCreate member function, the wxView can create a + wxDocChildFrame or a derived class. This wxDocChildFrame provides user + interface elements to view and/or edit the contents of the wxDocument. By default, simply returns true. If the function returns false, the view will be deleted. @@ -942,14 +936,14 @@ class View(wx.EvtHandler): def OnCreatePrintout(self): """ - Returns a `wx.Printout` object for the purposes of printing. It should + Returns a wxPrintout object for the purposes of printing. It should create a new object every time it is called; the framework will delete objects it creates. - By default, this function returns an instance of `DocPrintout`, which - prints and previews one page by calling `View.OnDraw`. + By default, this function returns an instance of wxDocPrintout, which + prints and previews one page by calling wxView.OnDraw. - Override to return an instance of a class other than `DocPrintout`. + Override to return an instance of a class other than wxDocPrintout. """ return DocPrintout(self) @@ -957,8 +951,9 @@ class View(wx.EvtHandler): def GetFrame(self): """ Gets the frame associated with the view (if any). Note that this - "frame" is not a `wx.Frame` at all in the generic MDI implementation - which uses the notebook pages instead of the frames. + "frame" is not a wxFrame at all in the generic MDI implementation + which uses the notebook pages instead of the frames and this is why + this method returns a wxWindow and not a wxFrame. """ return self._viewFrame @@ -966,7 +961,9 @@ class View(wx.EvtHandler): def SetFrame(self, frame): """ Sets the frame associated with this view. The application should call - this if possible, to tell the view about the frame. + this if possible, to tell the view about the frame. See GetFrame for + the explanation about the mismatch between the "Frame" in the method + name and the type of its parameter. """ self._viewFrame = frame @@ -983,57 +980,51 @@ class View(wx.EvtHandler): class DocTemplate(wx.Object): """ - The `DocTemplate` class is used to model the relationship between - a document class and a view class. + The wxDocTemplate class is used to model the relationship between a + document class and a view class. """ - def __init__(self, manager, description, filter, dir, ext, - docTypeName, viewTypeName, docType, viewType, - flags = DEFAULT_TEMPLATE_FLAGS, icon = None): + def __init__(self, manager, description, filter, dir, ext, docTypeName, viewTypeName, docType, viewType, flags=DEFAULT_TEMPLATE_FLAGS, icon=None): """ Constructor. Create instances dynamically near the start of your - application after creating a `DocManager` instance, and before doing + application after creating a wxDocManager instance, and before doing any document or view operations. - :param manager: the document manager object which manages this template. + manager is the document manager object which manages this template. - :param description: a short description of what the template - is for. This string will be displayed in the file filter - list of Windows file selectors. + description is a short description of what the template is for. This + string will be displayed in the file filter list of Windows file + selectors. - :param filter: an appropriate file filter such as \*.txt. + filter is an appropriate file filter such as *.txt. - :param dir: the default directory to use for file selectors. + dir is the default directory to use for file selectors. - :param ext: the default file extension (such as txt). + ext is the default file extension (such as txt). - :param docTypeName: a name that should be unique for a given - type of document, used for gathering a list of views - relevant to a particular document. + 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. - :param viewTypeName: a name that should be unique for a given view. + viewTypeName is a name that should be unique for a given view. - :param docType: a Python class. If this is not supplied, you - will need to derive a new `DocTemplate` class and override - the `CreateDocument` member to return a new document - instance on demand. + docClass is a Python class. 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. - :param viewType: a Python class. If this is not supplied, you - will need to derive a new `DocTemplate` class and override - the `CreateView` member to return a new view instance on - demand. + viewClass is a Python class. 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. - :param flags: a bit list of the following - - * TEMPLATE_VISIBLE: The template may be displayed to the - user in dialogs. + flags is a bit list of the following: + wx.TEMPLATE_VISIBLE The template may be displayed to the user in + dialogs. - * TEMPLATE_INVISIBLE: The template may not be displayed - to the user in dialogs. + wx.TEMPLATE_INVISIBLE The template may not be displayed to the user in + dialogs. - * DEFAULT_TEMPLATE_FLAGS: Defined as TEMPLATE_VISIBLE. - + wx.DEFAULT_TEMPLATE_FLAGS Defined as wxTEMPLATE_VISIBLE. """ self._docManager = manager self._description = description @@ -1052,8 +1043,8 @@ class DocTemplate(wx.Object): def GetDefaultExtension(self): """ - Returns the default file extension for the document data, as - passed to the document template constructor. + Returns the default file extension for the document data, as passed to + the document template constructor. """ return self._defaultExt @@ -1067,8 +1058,8 @@ class DocTemplate(wx.Object): def GetDescription(self): """ - Returns the text description of this template, as passed to - the document template constructor. + Returns the text description of this template, as passed to the + document template constructor. """ return self._description @@ -1082,8 +1073,8 @@ class DocTemplate(wx.Object): def GetDirectory(self): """ - Returns the default directory, as passed to the document - template constructor. + Returns the default directory, as passed to the document template + constructor. """ return self._directory @@ -1097,8 +1088,8 @@ class DocTemplate(wx.Object): def GetDocumentManager(self): """ - Returns the document manager instance for which this template - was created. + Returns the document manager instance for which this template was + created. """ return self._docManager @@ -1145,14 +1136,16 @@ class DocTemplate(wx.Object): def GetIcon(self): """ Returns the icon, as passed to the document template - constructor. + constructor. This method has been added to wxPython and is + not in wxWindows. """ return self._icon def SetIcon(self, flags): """ - Sets the icon. + Sets the icon. This method has been added to wxPython and is not + in wxWindows. """ self._icon = icon @@ -1218,10 +1211,9 @@ class DocTemplate(wx.Object): def CreateView(self, doc, flags): """ - Creates a new instance of the associated document view. If you - have not supplied a class to the template constructor, you - will need to override this function to return an appropriate - view instance. + Creates a new instance of the associated document view. If you have + not supplied a class to the template constructor, you will need to + override this function to return an appropriate view instance. """ view = self._viewType() view.SetDocument(doc) @@ -1245,25 +1237,24 @@ class DocTemplate(wx.Object): class DocManager(wx.EvtHandler): """ - The `DocManager` class is part of the document/view framework and - cooperates with the `View`, `Document` and `DocTemplate` classes. + The wxDocManager class is part of the document/view framework supported by + wxWindows, and cooperates with the wxView, wxDocument and wxDocTemplate + classes. """ - def __init__(self, flags = DEFAULT_DOCMAN_FLAGS, initialize = True): + def __init__(self, flags=DEFAULT_DOCMAN_FLAGS, initialize=True): """ - Constructor. Create a document manager instance dynamically - near the start of your application before doing any document - or view operations. + Constructor. Create a document manager instance dynamically near the + start of your application before doing any document or view operations. - :param flags: used to indicate whether the document manager is - in DOC_SDI or DOC_MDI mode. + flags is used in the Python version to indicate whether the document + manager is in DOC_SDI or DOC_MDI mode. - :param initialize: if true, the `Initialize` function will be - called to create a default history list object. If you - derive from DocManager, you may wish to call the base - constructor with false, and then call `Initialize` in your - own constructor, to allow your own `Initialize` or - `OnCreateFileHistory` functions to be called. + If initialize is true, the Initialize function will be called to + create a default history list object. If you derive from wxDocManager, + you may wish to call the base constructor with false, and then call + Initialize in your own constructor, to allow your own Initialize or + OnCreateFileHistory functions to be called. """ wx.EvtHandler.__init__(self) @@ -1318,12 +1309,13 @@ class DocManager(wx.EvtHandler): def GetFlags(self): """ - Returns the document manager's flags. + Returns the document manager's flags. This method has been + added to wxPython and is not in wxWindows. """ return self._flags - def CloseDocument(self, doc, force = True): + def CloseDocument(self, doc, force=True): """ Closes the specified document. """ @@ -1335,7 +1327,7 @@ class DocManager(wx.EvtHandler): return False - def CloseDocuments(self, force = True): + def CloseDocuments(self, force=True): """ Closes all currently opened documents. """ @@ -1346,9 +1338,9 @@ class DocManager(wx.EvtHandler): return True - def Clear(self, force = True): + def Clear(self, force=True): """ - Closes all currently opened document by calling `CloseDocuments` and + Closes all currently opened document by callling CloseDocuments and clears the document manager's templates. """ if not self.CloseDocuments(force): @@ -1359,13 +1351,16 @@ class DocManager(wx.EvtHandler): def Initialize(self): """ - Initializes data; currently just calls `OnCreateFileHistory`. Some data + Initializes data; currently just calls OnCreateFileHistory. Some data cannot always be initialized in the constructor because the programmer must be given the opportunity to override functionality. In fact - Initialize is called from the `DocManager` constructor, but this can - be prevented by passing false to the second argument, allowing the + Initialize is called from the wxDocManager constructor, but this can + be vetoed by passing false to the second argument, allowing the derived class's constructor to call Initialize, possibly calling a - different `OnCreateFileHistory` from the default. + different OnCreateFileHistory from the default. + + The bottom line: if you're not deriving from Initialize, forget it and + construct wxDocManager with no arguments. """ self.OnCreateFileHistory() return True @@ -1374,7 +1369,7 @@ class DocManager(wx.EvtHandler): def OnCreateFileHistory(self): """ A hook to allow a derived class to create a different type of file - history. Called from `Initialize`. + history. Called from Initialize. """ self._fileHistory = wx.FileHistory() @@ -1396,7 +1391,7 @@ class DocManager(wx.EvtHandler): """ return self.CloseDocuments(force = False) - + def OnFileNew(self, event): """ Creates a new document and reads in the selected file. @@ -1414,8 +1409,8 @@ class DocManager(wx.EvtHandler): def OnFileRevert(self, event): """ - Reverts the current document by calling `Document.Save` for - the current document. + Reverts the current document by calling wxDocument.Save for the current + document. """ doc = self.GetCurrentDocument() if not doc: @@ -1425,8 +1420,8 @@ class DocManager(wx.EvtHandler): def OnFileSave(self, event): """ - Saves the current document by calling `Document.Save` for the - current document. + Saves the current document by calling wxDocument.Save for the current + document. """ doc = self.GetCurrentDocument() if not doc: @@ -1436,7 +1431,7 @@ class DocManager(wx.EvtHandler): def OnFileSaveAs(self, event): """ - Calls `Document.SaveAs` for the current document. + Calls wxDocument.SaveAs for the current document. """ doc = self.GetCurrentDocument() if not doc: @@ -1446,8 +1441,8 @@ class DocManager(wx.EvtHandler): def OnPrint(self, event): """ - Prints the current document by calling its - `View.OnCreatePrintout` method. + Prints the current document by calling its View's OnCreatePrintout + method. """ view = self.GetCurrentView() if not view: @@ -1479,7 +1474,7 @@ class DocManager(wx.EvtHandler): def OnPreview(self, event): """ - Previews the current document by calling its `View.OnCreatePrintout` + Previews the current document by calling its View's OnCreatePrintout method. """ view = self.GetCurrentView() @@ -1629,11 +1624,9 @@ class DocManager(wx.EvtHandler): def GetLastActiveView(self): """ - Returns the last active view. This is used in the SDI - framework where dialogs can be mistaken for a view and causes - the framework to deactivete the current view. This happens - when something like a custom dialog box used to operate on the - current view is shown. + Returns the last active view. This is used in the SDI framework where dialogs can be mistaken for a view + and causes the framework to deactivete the current view. This happens when something like a custom dialog box used + to operate on the current view is shown. """ if len(self._docs) >= 1: return self._lastActiveView @@ -1643,11 +1636,10 @@ class DocManager(wx.EvtHandler): def ProcessEvent(self, event): """ - Processes an event, searching event tables and calling zero or - more suitable event handler function(s). Note that the - ProcessEvent method is called from the wxPython docview - framework directly since wxPython does not have a virtual - ProcessEvent function. + Processes an event, searching event tables and calling zero or more + suitable event handler function(s). Note that the ProcessEvent + method is called from the wxPython docview framework directly since + wxPython does not have a virtual ProcessEvent function. """ view = self.GetCurrentView() if view: @@ -1696,11 +1688,10 @@ class DocManager(wx.EvtHandler): def ProcessUpdateUIEvent(self, event): """ - Processes a UI event, searching event tables and calling zero - or more suitable event handler function(s). Note that the - ProcessEvent method is called from the wxPython docview - framework directly since wxPython does not have a virtual - ProcessEvent function. + Processes a UI event, searching event tables and calling zero or more + suitable event handler function(s). Note that the ProcessEvent + method is called from the wxPython docview framework directly since + wxPython does not have a virtual ProcessEvent function. """ id = event.GetId() view = self.GetCurrentView() @@ -1747,30 +1738,28 @@ class DocManager(wx.EvtHandler): return False - def CreateDocument(self, path, flags = 0): + def CreateDocument(self, path, flags=0): """ Creates a new document in a manner determined by the flags parameter, which can be: - * DOC_NEW: Creates a fresh document. - * DOC_SILENT: Silently loads the given document file. - - If DOC_NEW is present, a new document will be created and - returned, possibly after asking the user for a template to use - if there is more than one document template. If DOC_SILENT is - present, a new document will be created and the given file - loaded into it. If neither of these flags is present, the user - will be presented with a file selector for the file to load, - and the template to use will be determined by the extension - (Windows) or by popping up a template choice list (other + wx.lib.docview.DOC_NEW Creates a fresh document. + wx.lib.docview.DOC_SILENT Silently loads the given document file. + + If wx.lib.docview.DOC_NEW is present, a new document will be created and returned, + possibly after asking the user for a template to use if there is more + than one document template. If wx.lib.docview.DOC_SILENT is present, a new document + will be created and the given file loaded into it. If neither of these + flags is present, the user will be presented with a file selector for + the file to load, and the template to use will be determined by the + extension (Windows) or by popping up a template choice list (other platforms). - If the maximum number of documents has been reached, this - function will delete the oldest currently loaded document - before creating a new one. + If the maximum number of documents has been reached, this function + will delete the oldest currently loaded document before creating a new + one. - wxPython version supports the document manager's DOC_OPEN_ONCE - flag. + wxPython version supports the document manager's wx.lib.docview.DOC_OPEN_ONCE flag. """ templates = [] for temp in self._templates: @@ -1814,6 +1803,24 @@ class DocManager(wx.EvtHandler): if self.GetFlags() & DOC_OPEN_ONCE: for document in self._docs: if document.GetFilename() == path: + """ check for file modification outside of application """ + if os.path.exists(path) and os.path.getmtime(path) != document.GetDocumentModificationDate(): + msgTitle = wx.GetApp().GetAppName() + if not msgTitle: + msgTitle = _("Warning") + shortName = document.GetPrintableName() + res = wx.MessageBox(_("'%s' has been modified outside of %s. Reload '%s' from file system?") % (shortName, msgTitle, shortName), + msgTitle, + wx.YES_NO | wx.ICON_QUESTION, + self.FindSuitableParent()) + if res == wx.YES: + if not self.CloseDocument(document, False): + wx.MessageBox(_("Couldn't reload '%s'. Unable to close current '%s'.") % (shortName, shortName)) + return None + return self.CreateDocument(path, flags) + elif res == wx.NO: # don't ask again + document.SetDocumentModificationDate() + firstView = document.GetFirstView() if firstView and firstView.GetFrame(): firstView.GetFrame().SetFocus() # Not in wxWindows code but useful nonetheless @@ -1836,7 +1843,7 @@ class DocManager(wx.EvtHandler): return None - def CreateView(self, document, flags = 0): + def CreateView(self, document, flags=0): """ Creates a new view for the given document. If more than one view is allowed for the document (by virtue of multiple templates mentioning @@ -1869,21 +1876,21 @@ class DocManager(wx.EvtHandler): def DeleteTemplate(self, template, flags): """ - Placeholder, not yet implemented + Placeholder, not yet implemented in wxWindows. """ pass def FlushDoc(self, doc): """ - Placeholder, not yet implemented + Placeholder, not yet implemented in wxWindows. """ return False def MatchTemplate(self, path): """ - Placeholder, not yet implemented + Placeholder, not yet implemented in wxWindows. """ return None @@ -1997,7 +2004,7 @@ class DocManager(wx.EvtHandler): self._fileHistory.Save(config) - def FileHistoryAddFilesToMenu(self, menu = None): + def FileHistoryAddFilesToMenu(self, menu=None): """ Appends the files in the history list, to all menus managed by the file history object. @@ -2058,7 +2065,7 @@ class DocManager(wx.EvtHandler): On other platforms, if there is more than one document template a choice list is popped up, followed by a file selector. - This function is used in `DocManager.CreateDocument`. + This function is used in wxDocManager.CreateDocument. """ if wx.Platform == "__WXMSW__" or wx.Platform == "__WXGTK__" or wx.Platform == "__WXMAC__": allfilter = '' @@ -2105,18 +2112,19 @@ class DocManager(wx.EvtHandler): pass - def SelectDocumentType(self, temps, sort = False): + def SelectDocumentType(self, temps, sort=False): """ Returns a document template by asking the user (if there is more than - one template). This function is used in `DocManager.CreateDocument`. + one template). This function is used in wxDocManager.CreateDocument. + + Parameters - :param temps: list of templates from which to choose a desired template. + templates - list of templates from which to choose a desired template. - :param sort: If more than one template is passed in in - templates, then this parameter indicates whether the list - of templates that the user will have to choose from is - sorted or not when shown the choice box dialog. Default - is false. + sort - If more than one template is passed in in templates, then this + parameter indicates whether the list of templates that the user will + have to choose from is sorted or not when shown the choice box dialog. + Default is false. """ templates = [] for temp in temps: @@ -2152,14 +2160,9 @@ class DocManager(wx.EvtHandler): return templates[res] - def SelectViewType(self, temps, sort = False): + def SelectViewType(self, temps, sort=False): """ - Returns a document template by asking the user (if there is - more than one template), displaying a list of valid - views. This function is used in `DocManager.CreateView`. The - dialog normally will not appear because the array of templates - only contains those relevant to the document in question, and - often there will only be one such. + Returns a document template by asking the user (if there is more than one template), displaying a list of valid views. This function is used in wxDocManager::CreateView. The dialog normally will not appear because the array of templates only contains those relevant to the document in question, and often there will only be one such. """ templates = [] strings = [] @@ -2190,7 +2193,8 @@ class DocManager(wx.EvtHandler): def GetTemplates(self): """ - Returns the document manager's template list. + Returns the document manager's template list. This method has been added to + wxPython and is not in wxWindows. """ return self._templates @@ -2226,7 +2230,7 @@ class DocManager(wx.EvtHandler): self._docs.remove(doc) - def ActivateView(self, view, activate = True, deleting = False): + def ActivateView(self, view, activate=True, deleting=False): """ Sets the current view. """ @@ -2265,19 +2269,15 @@ class DocManager(wx.EvtHandler): class DocParentFrame(wx.Frame): """ - The DocParentFrame class provides a default top-level frame for - applications using the document/view framework. This class can - only be used for SDI (not MDI) parent frames. + The wxDocParentFrame class provides a default top-level frame for + applications using the document/view framework. This class can only be + used for SDI (not MDI) parent frames. - It cooperates with the `View`, `Document`, `DocManager` and - `DocTemplate` classes. + It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplates + classes. """ - def __init__(self, manager, frame, id, title, - pos = wx.DefaultPosition, - size = wx.DefaultSize, - style = wx.DEFAULT_FRAME_STYLE, - name = "frame"): + def __init__(self, manager, frame, id, title, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE, name="frame"): """ Constructor. Note that the event table must be rebuilt for the frame since the EvtHandler is not virtual. @@ -2377,17 +2377,17 @@ class DocParentFrame(wx.Frame): class DocChildFrame(wx.Frame): """ - The `DocChildFrame` class provides a default frame for displaying - documents on separate windows. This class can only be used for SDI - (not MDI) child frames. + The wxDocChildFrame class provides a default frame for displaying + documents on separate windows. This class can only be used for SDI (not + MDI) child frames. - The class is part of the document/view framework and cooperates - with the `View`, `Document`, `DocManager` and `DocTemplate` + The class is part of the document/view framework supported by wxWindows, + and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate classes. """ - def __init__(self, doc, view, frame, id, title, pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.DEFAULT_FRAME_STYLE, name = "frame"): + def __init__(self, doc, view, frame, id, title, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE, name="frame"): """ Constructor. Note that the event table must be rebuilt for the frame since the EvtHandler is not virtual. @@ -2524,16 +2524,16 @@ class DocChildFrame(wx.Frame): class DocMDIParentFrame(wx.MDIParentFrame): """ - The `DocMDIParentFrame` class provides a default top-level frame - for applications using the document/view framework. This class can - only be used for MDI parent frames. + The wxDocMDIParentFrame class provides a default top-level frame for + applications using the document/view framework. This class can only be + used for MDI parent frames. - It cooperates with the `View`, `Document`, `DocManager` and - `DocTemplate` classes. + It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate + classes. """ - def __init__(self, manager, frame, id, title, pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.DEFAULT_FRAME_STYLE, name = "frame"): + def __init__(self, manager, frame, id, title, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE, name="frame"): """ Constructor. Note that the event table must be rebuilt for the frame since the EvtHandler is not virtual. @@ -2633,17 +2633,17 @@ class DocMDIParentFrame(wx.MDIParentFrame): class DocMDIChildFrame(wx.MDIChildFrame): """ - The `DocMDIChildFrame` class provides a default frame for - displaying documents on separate windows. This class can only be - used for MDI child frames. + The wxDocMDIChildFrame class provides a default frame for displaying + documents on separate windows. This class can only be used for MDI child + frames. - The class is part of the document/view framework and cooperates - with the `View`, `Document`, `DocManager` and `DocTemplate` + The class is part of the document/view framework supported by wxWindows, + and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate classes. """ - def __init__(self, doc, view, frame, id, title, pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.DEFAULT_FRAME_STYLE, name = "frame"): + def __init__(self, doc, view, frame, id, title, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE, name="frame"): """ Constructor. Note that the event table must be rebuilt for the frame since the EvtHandler is not virtual. @@ -2781,12 +2781,12 @@ class DocMDIChildFrame(wx.MDIChildFrame): class DocPrintout(wx.Printout): """ - `DocPrintout` is a default Printout that prints the first page of - a document view. + DocPrintout is a default Printout that prints the first page of a document + view. """ - def __init__(self, view, title = "Printout"): + def __init__(self, view, title="Printout"): """ Constructor. """ @@ -2851,28 +2851,25 @@ class DocPrintout(wx.Printout): class Command(wx.Object): """ - `Command` is a base class for modelling an application command, - which is an action usually performed by selecting a menu item, - pressing a toolbar button or any other means provided by the - application to change the data or view. + wxCommand is a base class for modelling an application command, which is + an action usually performed by selecting a menu item, pressing a toolbar + button or any other means provided by the application to change the data + or view. """ def __init__(self, canUndo = False, name = None): """ - Constructor. Command is an abstract class, so you will need to - derive a new class and call this constructor from your own - constructor. + Constructor. wxCommand is an abstract class, so you will need to + derive a new class and call this constructor from your own constructor. - :param canUndo: tells the command processor whether this - command is undo-able. You can achieve the same - functionality by overriding the `CanUndo` member function - (if for example the criteria for undoability is context- - dependent). + canUndo tells the command processor whether this command is undo-able. + You can achieve the same functionality by overriding the CanUndo member + function (if for example the criteria for undoability is context- + dependent). - :param name: must be supplied for the command processor to - display the command name in the application's edit menu. - + name must be supplied for the command processor to display the command + name in the application's edit menu. """ self._canUndo = canUndo self._name = name @@ -2894,52 +2891,48 @@ class Command(wx.Object): def Do(self): """ - Override this member function to execute the appropriate - action when called. Return true to indicate that the action - has taken place, false otherwise. Returning false will - indicate to the command processor that the action is not - undoable and should not be added to the command history. + Override this member function to execute the appropriate action when + called. Return true to indicate that the action has taken place, false + otherwise. Returning false will indicate to the command processor that + the action is not undoable and should not be added to the command + history. """ return True def Undo(self): """ - Override this member function to un-execute a previous - `Do`. Return true to indicate that the action has taken place, - false otherwise. Returning false will indicate to the command - processor that the action is not redoable and no change should - be made to the command history. + Override this member function to un-execute a previous Do. Return true + to indicate that the action has taken place, false otherwise. Returning + false will indicate to the command processor that the action is not + redoable and no change should be made to the command history. - How you implement this command is totally application - dependent, but typical strategies include: + How you implement this command is totally application dependent, but + typical strategies include: - * Perform an inverse operation on the last modified piece - of data in the document. When redone, a copy of data - stored in command is pasted back or some operation - reapplied. This relies on the fact that you know the - ordering of Undos; the user can never Undo at an - arbitrary position in he command history. + Perform an inverse operation on the last modified piece of data in the + document. When redone, a copy of data stored in command is pasted back + or some operation reapplied. This relies on the fact that you know the + ordering of Undos; the user can never Undo at an arbitrary position in + he command history. - * Restore the entire document state (perhaps using - document transactioning). Potentially very inefficient, - but possibly easier to code if the user interface and - data are complex, and an 'inverse execute' operation is - hard to write. + Restore the entire document state (perhaps using document + transactioning). Potentially very inefficient, but possibly easier to + code if the user interface and data are complex, and an 'inverse + execute' operation is hard to write. """ return True class CommandProcessor(wx.Object): """ - `CommandProcessor` is a class that maintains a history of - `Command` instancess, with undo/redo functionality - built-in. Derive a new class from this if you want different - behaviour. + wxCommandProcessor is a class that maintains a history of wxCommands, with + undo/redo functionality built-in. Derive a new class from this if you want + different behaviour. """ - def __init__(self, maxCommands = -1): + def __init__(self, maxCommands=-1): """ Constructor. maxCommands may be set to a positive integer to limit the number of commands stored to it, otherwise (and by default) the @@ -3000,11 +2993,10 @@ class CommandProcessor(wx.Object): def SetEditMenu(self, menu): """ - Tells the command processor to update the Undo and Redo items - on this menu as appropriate. Set this to None if the menu is - about to be destroyed and command operations may still be - performed, or the command processor may try to access an - invalid pointer. + Tells the command processor to update the Undo and Redo items on this + menu as appropriate. Set this to NULL if the menu is about to be + destroyed and command operations may still be performed, or the + command processor may try to access an invalid pointer. """ self._editMenu = menu @@ -3037,10 +3029,20 @@ class CommandProcessor(wx.Object): self._redoAccelerator = accel + def SetEditMenu(self, menu): + """ + Tells the command processor to update the Undo and Redo items on this + menu as appropriate. Set this to NULL if the menu is about to be + destroyed and command operations may still be performed, or the + command processor may try to access an invalid pointer. + """ + self._editMenu = menu + + def SetMenuStrings(self): """ - Sets the menu labels according to the currently set menu and - the current command state. + Sets the menu labels according to the currently set menu and the + current command state. """ if self.GetEditMenu() != None: undoCommand = self._GetCurrentCommand() @@ -3085,13 +3087,13 @@ class CommandProcessor(wx.Object): return self._GetCurrentRedoCommand() != None - def Submit(self, command, storeIt = True): + def Submit(self, command, storeIt=True): """ Submits a new command to the command processor. The command processor - calls `Command.Do` to execute the command; if it succeeds, the + calls wxCommand::Do to execute the command; if it succeeds, the command is stored in the history list, and the associated edit menu (if any) updated appropriately. If it fails, the command is deleted - immediately. Once `Submit` has been called, the passed command should + immediately. Once Submit has been called, the passed command should not be deleted directly by the application. storeIt indicates whether the successful command should be stored in