#----------------------------------------------------------------------------
# Name: docview.py
-# Purpose: Port of the wxWindows docview classes
+# Purpose: Port of the wxWidgets docview classes
#
# Author: Peter Yared
#
# License: wxWindows license
#----------------------------------------------------------------------------
+"""
+A port of the wxWidgets doc/view classes to Python.
+
+:see: `pydocview`
+"""
import os
import os.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 supported by wxWindows, and cooperates
- with the wxView, wxDocTemplate and wxDocManager classes.
+ 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.
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
def GetDocumentName(self):
"""
- The document type name given to the wxDocTemplate constructor,
+ The document type name given to the `DocTemplate` 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 wxDocManager::CreateView to collate a list of
+ variable is used in `DocManager.CreateView` to collate a list of
alternative view types that can be used on this kind of document.
"""
return self._documentTypeName
def SetDocumentName(self, name):
"""
- Sets he document type name given to the wxDocTemplate constructor,
+ Sets the document type name given to the `DocTemplate` 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 wxDocManager::CreateView to collate a list of
+ variable is used in `DocManager.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.
"""
def GetDocumentSaved(self):
"""
- Returns True if the document has been saved. This method has been
- added to wxPython and is not in wxWindows.
+ Returns True if the document has been saved.
"""
return self._savedYet
def SetDocumentSaved(self, saved = True):
"""
- Sets whether the document has been saved. This method has been
- added to wxPython and is not in wxWindows.
+ Sets whether the document has been saved.
"""
self._savedYet = saved
"""
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
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
- xTextWindow to view and edit the document).
+ `wx.TextCtrl` to view and edit the document).
"""
self._documentModified = modify
"""
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())
"""
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
def Close(self):
"""
- 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.
+ 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.
"""
if self.OnSaveModified():
if self.OnCloseDocument():
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()
def DeleteAllViews(self):
"""
- 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,
+ 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`,
whose default implemention is to save and delete the document if no
views exist.
"""
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
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
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:
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
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
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
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 wxCommandProcessor.
+ processor to be created when the document is created. By
+ default, it returns an instance of `CommandProcessor`.
"""
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
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)
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)
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.
"""
def UpdateAllViews(self, sender = None, hint = None):
"""
- Updates all views. If sender is non-NULL, does not update this view.
+ Updates all views. If sender is non-None, does not update this view.
hint represents optional information to allow a view to optimize its
update.
"""
def SetFilename(self, filename, notifyViews = False):
"""
Sets the filename for this document. Usually called by the framework.
- If notifyViews is true, wxView.OnChangeFilename is called for all
+ If notifyViews is true, `View.OnChangeFilename` is called for all
views.
"""
self._documentFile = filename
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. This method has been added
- to wxPython and is not in wxWindows.
+ 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.
"""
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 is part of the document/view
- framework supported by wxWindows, and cooperates with the wxDocument,
- wxDocTemplate and wxDocManager classes.
+ 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.
"""
def __init__(self):
def OnActivateView(self, activate, activeView, deactiveView):
"""
- Called when a view is activated by means of wxView::Activate. The
+ Called when a view is activated by means of `View.Activate`. The
default implementation does nothing.
"""
pass
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 pointer to the
- view that sent the update request, or NULL if no single view requested
+ 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
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.
def GetViewName(self):
"""
- Gets the name associated with the view (passed to the wxDocTemplate
+ Gets the name associated with the view (passed to the `DocTemplate`
constructor). Not currently used by the framework.
"""
return self._viewTypeName
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):
def Activate(self, activate = True):
"""
- 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.
+ 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.
"""
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):
"""
Implements closing behaviour. The default implementation calls
- wxDocument.Close to close the associated document. Does not delete the
+ `Document.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 wxDocument::Close succeeded. For example,
+ this function, if a call to `Document.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.
def OnCreate(self, doc, flags):
"""
- 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.
+ `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`.
By default, simply returns true. If the function returns false, the
view will be deleted.
def OnCreatePrintout(self):
"""
- Returns a wxPrintout object for the purposes of printing. It should
+ Returns a `wx.Printout` 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 wxDocPrintout, which
- prints and previews one page by calling wxView.OnDraw.
+ By default, this function returns an instance of `DocPrintout`, which
+ prints and previews one page by calling `View.OnDraw`.
- Override to return an instance of a class other than wxDocPrintout.
+ Override to return an instance of a class other than `DocPrintout`.
"""
return DocPrintout(self)
def GetFrame(self):
"""
Gets the frame associated with the view (if any). Note that this
- "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.
+ "frame" is not a `wx.Frame` at all in the generic MDI implementation
+ which uses the notebook pages instead of the frames.
"""
return self._viewFrame
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. See GetFrame for
- the explanation about the mismatch between the "Frame" in the method
- name and the type of its parameter.
+ this if possible, to tell the view about the frame.
"""
self._viewFrame = frame
class DocTemplate(wx.Object):
"""
- The wxDocTemplate class is used to model the relationship between a
- document class and a view class.
+ The `DocTemplate` 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 wxDocManager instance, and before doing
+ application after creating a `DocManager` instance, and before doing
any document or view operations.
- manager is the document manager object which manages this template.
+ :param manager: the document manager object which manages this template.
- 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 description: a short description of what the template
+ is for. This string will be displayed in the file filter
+ list of Windows file selectors.
- filter is an appropriate file filter such as *.txt.
+ :param filter: an appropriate file filter such as \*.txt.
- dir is the default directory to use for file selectors.
+ :param dir: the default directory to use for file selectors.
- ext is the default file extension (such as txt).
+ :param ext: the default file extension (such as txt).
- 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 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.
- viewTypeName is a name that should be unique for a given view.
+ :param viewTypeName: a name that should be unique for a given view.
- 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 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.
- 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 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.
- flags is a bit list of the following:
- wx.TEMPLATE_VISIBLE The template may be displayed to the user in
- dialogs.
+ :param flags: a bit list of the following
+
+ * TEMPLATE_VISIBLE: The template may be displayed to the
+ user in dialogs.
- wx.TEMPLATE_INVISIBLE The template may not be displayed to the user in
- dialogs.
+ * TEMPLATE_INVISIBLE: The template may not be displayed
+ to the user in dialogs.
- wx.DEFAULT_TEMPLATE_FLAGS Defined as wxTEMPLATE_VISIBLE.
+ * DEFAULT_TEMPLATE_FLAGS: Defined as TEMPLATE_VISIBLE.
+
"""
self._docManager = manager
self._description = description
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
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
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
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
def GetIcon(self):
"""
Returns the icon, as passed to the document template
- constructor. This method has been added to wxPython and is
- not in wxWindows.
+ constructor.
"""
return self._icon
def SetIcon(self, flags):
"""
- Sets the icon. This method has been added to wxPython and is not
- in wxWindows.
+ Sets the icon.
"""
self._icon = icon
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)
class DocManager(wx.EvtHandler):
"""
- The wxDocManager class is part of the document/view framework supported by
- wxWindows, and cooperates with the wxView, wxDocument and wxDocTemplate
- classes.
+ The `DocManager` class is part of the document/view framework and
+ cooperates with the `View`, `Document` and `DocTemplate` classes.
"""
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.
- flags is used in the Python version to indicate whether the document
- manager is in DOC_SDI or DOC_MDI mode.
+ :param flags: used to indicate whether the document manager is
+ in DOC_SDI or DOC_MDI mode.
- 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.
+ :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.
"""
wx.EvtHandler.__init__(self)
def GetFlags(self):
"""
- Returns the document manager's flags. This method has been
- added to wxPython and is not in wxWindows.
+ Returns the document manager's flags.
"""
return self._flags
def Clear(self, force = True):
"""
- Closes all currently opened document by callling CloseDocuments and
+ Closes all currently opened document by calling `CloseDocuments` and
clears the document manager's templates.
"""
if not self.CloseDocuments(force):
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 wxDocManager constructor, but this can
- be vetoed by passing false to the second argument, allowing the
+ Initialize is called from the `DocManager` constructor, but this can
+ be prevented by passing false to the second argument, allowing the
derived class's constructor to call Initialize, possibly calling a
- different OnCreateFileHistory from the default.
-
- The bottom line: if you're not deriving from Initialize, forget it and
- construct wxDocManager with no arguments.
+ different `OnCreateFileHistory` from the default.
"""
self.OnCreateFileHistory()
return True
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()
def OnFileRevert(self, event):
"""
- Reverts the current document by calling wxDocument.Save for the current
- document.
+ Reverts the current document by calling `Document.Save` for
+ the current document.
"""
doc = self.GetCurrentDocument()
if not doc:
def OnFileSave(self, event):
"""
- Saves the current document by calling wxDocument.Save for the current
- document.
+ Saves the current document by calling `Document.Save` for the
+ current document.
"""
doc = self.GetCurrentDocument()
if not doc:
def OnFileSaveAs(self, event):
"""
- Calls wxDocument.SaveAs for the current document.
+ Calls `Document.SaveAs` for the current document.
"""
doc = self.GetCurrentDocument()
if not doc:
def OnPrint(self, event):
"""
- Prints the current document by calling its View's OnCreatePrintout
- method.
+ Prints the current document by calling its
+ `View.OnCreatePrintout` method.
"""
view = self.GetCurrentView()
if not view:
def OnPreview(self, event):
"""
- Previews the current document by calling its View's OnCreatePrintout
+ Previews the current document by calling its `View.OnCreatePrintout`
method.
"""
view = self.GetCurrentView()
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
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:
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()
Creates a new document in a manner determined by the flags parameter,
which can be:
- 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
+ * 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
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 wx.lib.docview.DOC_OPEN_ONCE flag.
+ wxPython version supports the document manager's DOC_OPEN_ONCE
+ flag.
"""
templates = []
for temp in self._templates:
def DeleteTemplate(self, template, flags):
"""
- Placeholder, not yet implemented in wxWindows.
+ Placeholder, not yet implemented
"""
pass
def FlushDoc(self, doc):
"""
- Placeholder, not yet implemented in wxWindows.
+ Placeholder, not yet implemented
"""
return False
def MatchTemplate(self, path):
"""
- Placeholder, not yet implemented in wxWindows.
+ Placeholder, not yet implemented
"""
return None
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 wxDocManager.CreateDocument.
+ This function is used in `DocManager.CreateDocument`.
"""
if wx.Platform == "__WXMSW__" or wx.Platform == "__WXGTK__" or wx.Platform == "__WXMAC__":
allfilter = ''
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 wxDocManager.CreateDocument.
+ one template). This function is used in `DocManager.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.
-
- 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.
+ :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.
"""
templates = []
for temp in temps:
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 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.
+ 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.
"""
templates = []
strings = []
def GetTemplates(self):
"""
- Returns the document manager's template list. This method has been added to
- wxPython and is not in wxWindows.
+ Returns the document manager's template list.
"""
return self._templates
class DocParentFrame(wx.Frame):
"""
- 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.
+ 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.
- It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplates
- classes.
+ It cooperates with the `View`, `Document`, `DocManager` and
+ `DocTemplate` 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.
class DocChildFrame(wx.Frame):
"""
- 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 `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 class is part of the document/view framework supported by wxWindows,
- and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
+ The class is part of the document/view framework and cooperates
+ with the `View`, `Document`, `DocManager` and `DocTemplate`
classes.
"""
class DocMDIParentFrame(wx.MDIParentFrame):
"""
- 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.
+ 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.
- It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
- classes.
+ It cooperates with the `View`, `Document`, `DocManager` and
+ `DocTemplate` classes.
"""
class DocMDIChildFrame(wx.MDIChildFrame):
"""
- The wxDocMDIChildFrame class provides a default frame for displaying
- documents on separate windows. This class can only be used for MDI child
- frames.
+ The `DocMDIChildFrame` 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 supported by wxWindows,
- and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
+ The class is part of the document/view framework and cooperates
+ with the `View`, `Document`, `DocManager` and `DocTemplate`
classes.
"""
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.
"""
class Command(wx.Object):
"""
- 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.
+ `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.
"""
def __init__(self, canUndo = False, name = None):
"""
- Constructor. wxCommand is an abstract class, so you will need to
- derive a new class and call this constructor from your own constructor.
+ Constructor. Command is an abstract class, so you will need to
+ derive a new class and call this constructor from your own
+ constructor.
- 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 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).
- name must be supplied for the command processor to display the command
- name in the application's edit menu.
+ :param 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
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):
"""
- 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.
+ `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.
"""
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.
+ 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.
"""
self._editMenu = menu
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()
def Submit(self, command, storeIt = True):
"""
Submits a new command to the command processor. The command processor
- calls wxCommand::Do to execute the command; if it succeeds, the
+ calls `Command.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
# --------------------------------------------------------------------------- #
-"""Description:
-
-The FoldPanelBar is a control that contains multiple panels (FoldPanel items)
-that can be expanded or collapsed. The captionbar of the FoldPanel can be
-customized by setting it to a horizontal gradient style, vertical gradient style,
-a single color, a rectangle or filled rectangle. The FoldPanel items can be
-collapsed in place or to the bottom of the control. The wxWindow derived controls
-can be added dynamically, and separated by separator lines.
-FoldPanelBar is freeware and distributed under the wxPython license.
+"""
+The `FoldPanelBar` is a control that contains multiple panels (of type
+`FoldPanelItem`) that can be expanded or collapsed. The captionbar of
+the FoldPanel can be customized by setting it to a horizontal gradient
+style, vertical gradient style, a single color, a rectangle or filled
+rectangle. The FoldPanel items can be collapsed in place or to the
+bottom of the control. `wx.Window` derived controls can be added
+dynamically, and separated by separator lines. FoldPanelBar is
+freeware and distributed under the wxPython license.
-- How does it work:
+How does it work
+----------------
The internals of the FoldPanelBar is a list of FoldPanelItem objects. Through
the reference of FoldPanel these panels can be controlled by adding new controls
involved in the panels, everything is purely x-y positioning.
-- What can it do and what not?
+What can it do and what not?
+----------------------------
a) What it can do:
- Run-time addition of panels (no deletion just yet)
- Run time addition of controls to the panel (it will be resized accordingly)
- Creating panels in collapsed mode or expanded mode
- Various modes of caption behaviour and filling to make it more appealing
- Panels can be folded and collapsed (or all of them) to allow more space
+ * Run-time addition of panels (no deletion just yet)
+ * Run time addition of controls to the panel (it will be resized accordingly)
+ * Creating panels in collapsed mode or expanded mode
+ * Various modes of caption behaviour and filling to make it more appealing
+ * Panels can be folded and collapsed (or all of them) to allow more space
b) What it cannot do:
- Selection of a panel like in a list ctrl
- Dragging and dropping the panels
- Re-ordering the panels (not yet)
+ * Selection of a panel like in a list ctrl
+ * Dragging and dropping the panels
+ * Re-ordering the panels (not yet)
-- Supported platforms
+Supported platforms
+-------------------
FoldPanelBar is supported on the following platforms:
-Windows (Verified on Windows XP, 2000)
-Linux/Unix (GTK2) (Thanks To Toni Brkic And Robin Dunn)
-Mac OSX (Thanks To Robin Dunn For The CaptionBar Size Patch)
+ * Windows (Verified on Windows XP, 2000)
+ * Linux/Unix (GTK2) (Thanks To Toni Brkic And Robin Dunn)
+ * Mac OSX (Thanks To Robin Dunn For The CaptionBar Size Patch)
Latest Revision: Andrea Gavana @ 30 Mar 2005, 22.30 CET
# ------------------------------------------------------------------------------ #
# class CaptionBarStyle
-# This class encapsulates the styles you wish to set for the CaptionBar
-# (this is the part of the FoldPanel where the caption is displayed). It can
-# either be applied at creation time be reapplied when styles need to be
-# changed.
-#
-# At construction time, all styles are set to their default transparency.
-# This means none of the styles will be applied to the CaptionBar in question,
-# meaning it will be created using the default internals. When setting i.e
-# the color, font or panel style, these styles become active to be used.
# ------------------------------------------------------------------------------ #
class CaptionBarStyle:
+ """
+ This class encapsulates the styles you wish to set for the
+ `CaptionBar` (this is the part of the FoldPanel where the caption
+ is displayed). It can either be applied at creation time be
+ reapplied when styles need to be changed.
+
+ At construction time, all styles are set to their default
+ transparency. This means none of the styles will be applied to
+ the `CaptionBar` in question, meaning it will be created using the
+ default internals. When setting i.e the color, font or panel
+ style, these styles become active to be used.
+
+ """
def __init__(self):
""" Default constructor for this class."""
def ResetDefaults(self):
- """ Resets Default CaptionBarStyle."""
-
+ """ Resets default CaptionBarStyle."""
self._firstColourUsed = False
self._secondColourUsed = False
self._textColourUsed = False
"""
Sets font for the caption bar.
- If this is not set, the font property is undefined and will not
- be used. Use CaptionFontUsed() to check if this style is used.
- """
-
+ If this is not set, the font property is undefined and will
+ not be used. Use `CaptionFontUsed` to check if this style is
+ used.
+ """
self._captionFont = font
self._captionFontUsed = True
def CaptionFontUsed(self):
- """ Checks if the caption bar font is set. """
-
+ """ Checks if the caption bar font is set. """
return self._captionFontUsed
Please be warned this will result in an assertion failure when
this property is not previously set.
- See also SetCaptionFont(), CaptionFontUsed()
- """
+ :see: `SetCaptionFont`, `CaptionFontUsed`
+ """
return self._captionFont
"""
Sets first colour for the caption bar.
- If this is not set, the colour property is undefined and will not
- be used. Use FirstColourUsed() to check if this style is used.
- """
-
+ If this is not set, the colour property is undefined and will
+ not be used. Use `FirstColourUsed` to check if this style is
+ used.
+ """
self._firstColour = colour
self._firstColourUsed = True
def FirstColourUsed(self):
- """ Checks if the first colour of the caption bar is set."""
-
+ """ Checks if the first colour of the caption bar is set."""
return self._firstColourUsed
"""
Returns the first colour for the caption bar.
- Please be warned this will result in an assertion failure
- when this property is not previously set.
- See also SetCaptionFirstColour(), CaptionFirstColourUsed()
- """
+ Please be warned this will result in an assertion failure when
+ this property is not previously set.
+ :see: `SetFirstColour`, `FirstColourUsed`
+ """
return self._firstColour
"""
Sets second colour for the caption bar.
- If this is not set, the colour property is undefined and will not
- be used. Use SecondColourUsed() to check if this style is used.
- """
-
+ If this is not set, the colour property is undefined and will
+ not be used. Use `SecondColourUsed` to check if this style is
+ used.
+ """
self._secondColour = colour
self._secondColourUsed = True
def SecondColourUsed(self):
- """ Checks if the second colour of the caption bar is set."""
-
+ """ Checks if the second colour of the caption bar is set."""
return self._secondColourUsed
+
def GetSecondColour(self):
"""
Returns the second colour for the caption bar.
- Please be warned this will result in an assertion failure
- when this property is not previously set.
- See also SetCaptionSecondColour(), CaptionSecondColourUsed()
- """
+ Please be warned this will result in an assertion failure when
+ this property is not previously set.
+ :see: `SetSecondColour`, `SecondColourUsed`
+ """
return self._secondColour
"""
Sets caption colour for the caption bar.
- If this is not set, the colour property is undefined and will not
- be used. Use CaptionColourUsed() to check if this style is used.
- """
-
+ If this is not set, the colour property is undefined and will
+ not be used. Use `CaptionColourUsed` to check if this style is
+ used.
+ """
self._textColour = colour
self._textColourUsed = True
def CaptionColourUsed(self):
- """ Checks if the caption colour of the caption bar is set."""
-
+ """ Checks if the caption colour of the caption bar is set."""
return self._textColourUsed
Please be warned this will result in an assertion failure
when this property is not previously set.
See also SetCaptionColour(), CaptionColourUsed()
- """
-
+ """
return self._textColour
"""
Sets caption style for the caption bar.
- If this is not set, the property is undefined and will not
- be used. Use CaptionStyleUsed() to check if this style is used.
+ If this is not set, the property is undefined and will not be
+ used. Use CaptionStyleUsed() to check if this style is used.
The following styles can be applied:
- - CAPTIONBAR_GRADIENT_V: Draws a vertical gradient from top to bottom
- - CAPTIONBAR_GRADIENT_H: Draws a horizontal gradient from left to right
- - CAPTIONBAR_SINGLE: Draws a single filled rectangle to draw the caption
- - CAPTIONBAR_RECTANGLE: Draws a single colour with a rectangle around the caption
- - CAPTIONBAR_FILLED_RECTANGLE: Draws a filled rectangle and a border around it
- """
-
+
+ * CAPTIONBAR_GRADIENT_V: Draws a vertical gradient from top to bottom
+
+ * CAPTIONBAR_GRADIENT_H: Draws a horizontal gradient from
+ left to right
+
+ * CAPTIONBAR_SINGLE: Draws a single filled rectangle to
+ draw the caption
+
+ * CAPTIONBAR_RECTANGLE: Draws a single colour with a
+ rectangle around the caption
+
+ * CAPTIONBAR_FILLED_RECTANGLE: Draws a filled rectangle
+ and a border around it
+
+ """
self._captionStyle = style
self._captionStyleUsed = True
def CaptionStyleUsed(self):
- """ Checks if the caption style of the caption bar is set."""
-
+ """ Checks if the caption style of the caption bar is set."""
return self._captionStyleUsed
Please be warned this will result in an assertion failure
when this property is not previously set.
- See also SetCaptionStyle(), CaptionStyleUsed()
- """
+ :see: `SetCaptionStyle`, `CaptionStyleUsed`
+ """
return self._captionStyle
# ---------------------------------------------------------------------------- #
# class CaptionBarEvent
-# This event will be sent when a EVT_CAPTIONBAR is mapped in the parent.
-# It is to notify the parent that the bar is now in collapsed or expanded
-# state. The parent should re-arrange the associated windows accordingly
# ---------------------------------------------------------------------------- #
class CaptionBarEvent(wx.PyCommandEvent):
-
+ """
+ This event will be sent when a EVT_CAPTIONBAR is mapped in the parent.
+ It is to notify the parent that the bar is now in collapsed or expanded
+ state. The parent should re-arrange the associated windows accordingly
+ """
def __init__(self, evtType):
- """ Default Constructor For This Class."""
-
+ """ Default Constructor For This Class."""
wx.PyCommandEvent.__init__(self, evtType)
def GetFoldStatus(self):
- """ Returns Wether The Bar Is Expanded Or Collapsed. True Means Expanded."""
-
+ """
+ Returns whether the bar is expanded or collapsed. True means
+ expanded.
+ """
return not self._bar.IsCollapsed()
def GetBar(self):
- """ Returns The CaptionBar Selected."""
-
+ """ Returns The CaptionBar Selected."""
return self._bar
def SetTag(self, tag):
- """ Assign A Tag To The Selected CaptionBar."""
-
+ """ Assign A Tag To The Selected CaptionBar."""
self._tag = tag
def GetTag(self):
- """ Returns The Tag Assigned To The Selected CaptionBar."""
-
+ """ Returns The Tag Assigned To The Selected CaptionBar."""
return self._tag
def SetBar(self, bar):
"""
- Sets The Bar Associated With This Event.
+ Sets the bar associated with this event.
- Should Not Used By Any Other Then The Originator Of The Event.
- """
-
+ Should not used by any other then the originator of the event.
+ """
self._bar = bar
# -------------------------------------------------------------------------------- #
# class CaptionBar
-# This class is a graphical caption component that consists of a caption and
-# a clickable arrow.
-#
-# The CaptionBar fires an event EVT_CAPTIONBAR which is a CaptionBarEvent.
-# This event can be caught and the parent window can act upon the collapsed
-# or expanded state of the bar (which is actually just the icon which changed).
-# The parent panel can reduce size or expand again.
# -------------------------------------------------------------------------------- #
class CaptionBar(wx.Window):
-
+ """
+ This class is a graphical caption component that consists of a
+ caption and a clickable arrow.
+
+ The CaptionBar fires an event EVT_CAPTIONBAR which is a
+ `CaptionBarEvent`. This event can be caught and the parent window
+ can act upon the collapsed or expanded state of the bar (which is
+ actually just the icon which changed). The parent panel can
+ reduce size or expand again.
+ """
+
# Define Empty CaptionBar Style
EmptyCaptionBarStyle = CaptionBarStyle()
"""
Sets CaptionBar styles with CapionBarStyle class.
- All styles that are actually set, are applied. If you set applyDefault
- to True, all other (not defined) styles will be set to default. If it
- is False, the styles which are not set in the CaptionBarStyle will be
- ignored.
- """
-
+ All styles that are actually set, are applied. If you set
+ applyDefault to True, all other (not defined) styles will be
+ set to default. If it is False, the styles which are not set
+ in the CaptionBarStyle will be ignored.
+ """
self.ApplyCaptionStyle(cbstyle, applyDefault)
self.Refresh()
def GetCaptionStyle(self):
"""
- Returns the current style of the captionbar in a CaptionBarStyle class.
+ Returns the current style of the captionbar in a
+ `CaptionBarStyle` class.
This can be used to change and set back the changes.
- """
-
+ """
return self._style
def IsCollapsed(self):
"""
- Returns wether the status of the bar is expanded or collapsed. """
-
+ Returns wether the status of the bar is expanded or collapsed.
+ """
return self._collapsed
def SetRightIndent(self, pixels):
"""
- Sets the amount of pixels on the right from which the bitmap is trailing.
+ Sets the amount of pixels on the right from which the bitmap
+ is trailing.
- If this is 0, it will be drawn all the way to the right, default is
- equal to FPB_BMP_RIGHTSPACE. Assign this before assigning an image
- list to prevent a redraw.
+ If this is 0, it will be drawn all the way to the right,
+ default is equal to FPB_BMP_RIGHTSPACE. Assign this before
+ assigning an image list to prevent a redraw.
"""
-
assert pixels >= 0
self._rightIndent = pixels
if self._foldIcons:
"""
This sets the internal state / representation to collapsed.
- This does not trigger a CaptionBarEvent to be sent to the parent.
- """
-
+ This does not trigger a `CaptionBarEvent` to be sent to the
+ parent.
+ """
self._collapsed = True
self.RedrawIconBitmap()
"""
This sets the internal state / representation to expanded.
- This does not trigger a CaptionBarEvent to be sent to the parent.
- """
-
+ This does not trigger a `CaptionBarEvent` to be sent to the
+ parent.
+ """
self._collapsed = False
self.RedrawIconBitmap()
def FillCaptionBackground(self, dc):
- """ Fills the background of the caption with either a gradient or a solid color. """
+ """
+ Fills the background of the caption with either a gradient or
+ a solid color.
+ """
style = self._style.GetCaptionStyle()
"""
Catches the mouse click-double click.
- If clicked on the arrow (single) or double on the caption we change state
- and an event must be fired to let this panel collapse or expand.
+ If clicked on the arrow (single) or double on the caption we
+ change state and an event must be fired to let this panel
+ collapse or expand.
"""
send_event = False
def OnChar(self, event):
""" Unused Methods. Any Ideas?!?"""
-
# TODO: Anything here?
event.Skip()
def DoGetBestSize(self):
- """ Returns the best size for this panel, based upon the font assigned
- to this window, and the caption string"""
+ """
+ Returns the best size for this panel, based upon the font
+ assigned to this window, and the caption string
+ """
if self.IsVertical():
x, y = self.GetTextExtent(self._caption)
# ---------------------------------------------------------------------------------- #
# class FoldPanelBar
-# The FoldPanelBar is a class which can maintain a list of collapsable panels.
-# Once a panel is collapsed, only it's panel bar is visible to the user. This
-# will provide more space for the other panels, or allow the user to close
-# panels which are not used often to get the most out of the work area.
-#
-# This control is easy to use. Simply create it as a child for a panel or
-# sash window, and populate panels with FoldPanelBar.AddFoldPanel(). Then use
-# the FoldPanelBar.AddFoldPanelWindow() to add wxWindow derived controls to the
-# current fold panel. Use FoldPanelBar.AddFoldPanelSeparator() to put separators
-# between the groups of controls that need a visual separator to group them
-# together. After all is constructed, the user can fold the panels by
-# doubleclicking on the bar or single click on the arrow, which will indicate
-# the collapsed or expanded state.
# ---------------------------------------------------------------------------------- #
class FoldPanelBar(wx.Panel):
-
+ """
+ The FoldPanelBar is a class which can maintain a list of
+ collapsable panels. Once a panel is collapsed, only it's caption
+ bar is visible to the user. This will provide more space for the
+ other panels, or allow the user to close panels which are not used
+ often to get the most out of the work area.
+
+ This control is easy to use. Simply create it as a child for a
+ panel or sash window, and populate panels with
+ `AddFoldPanel`. Then use the AdddFoldPanelWindow` to add
+ `wx.Window` derived controls to the current fold panel. Use
+ `AddFoldPanelSeparator` to put separators between the groups of
+ controls that need a visual separator to group them
+ together. After all is constructed, the user can fold the panels
+ by doubleclicking on the bar or single click on the arrow, which
+ will indicate the collapsed or expanded state.
+ """
# Define Empty CaptionBar Style
EmptyCaptionBarStyle = CaptionBarStyle()
"""
Adds a fold panel to the list of panels.
- If the flag collapsed is set to True, the panel is collapsed initially.
- The FoldPanel item which is returned, can be used as a reference to
- perform actions upon the fold panel like collapsing it, expanding it,
- or deleting it from the list.
+ If the flag collapsed is set to True, the panel is collapsed
+ initially. The FoldPanel item which is returned, can be used
+ as a reference to perform actions upon the fold panel like
+ collapsing it, expanding it, or deleting it from the list.
Use this foldpanel to add windows to it. Please consult
- FoldPanelBar.AddFoldPanelWindow() and
- FoldPanelBar.AddFoldPanelSeparator() to know how to add wxWindow items
- to the panels.
+ `AddFoldPanelWindow` and `AddFoldPanelSeparator` to know how
+ to add items derived from `wx.Window` to the panels.
"""
# create a fold panel item, which is first only the caption.
leftSpacing=FPB_DEFAULT_LEFTLINESPACING,
rightSpacing=FPB_DEFAULT_RIGHTLINESPACING):
"""
- Adds a wxWindow derived class to the referenced FoldPanel.
+ Adds a `wx.Window` derived instance to the referenced
+ FoldPanel.
- IMPORTANT: Make the to be created window, child of the FoldPanel. See
+ IMPORTANT: Make the window be a child of the FoldPanel. See
example that follows. The flags to be used are:
- - FPB_ALIGN_WIDTH: Which means the wxWindow to be added will be
- aligned to fit the width of the FoldPanel when it is resized.
- Very handy for sizer items, buttons and text boxes.
- - FPB_ALIGN_LEFT: Alligns left instead of fitting the width of
- the child window to be added. Use either this one or
- FPB_ALIGN_WIDTH.
+
+ * FPB_ALIGN_WIDTH: Which means the wxWindow to be added
+ will be aligned to fit the width of the FoldPanel when
+ it is resized. Very handy for sizer items, buttons and
+ text boxes.
- The wxWindow to be added can be slightly indented from left and right
- so it is more visibly placed in the FoldPanel. Use Spacing > 0 to give
- the control an y offset from the previous wxWindow added, use leftSpacing
- to give it a slight indent from the left, and rightSpacing also reserves
- a little space on the right so the wxWindow can be properly placed in
- the FoldPanel.
+ * FPB_ALIGN_LEFT: Alligns left instead of fitting the
+ width of the child window to be added. Use either this
+ one or FPB_ALIGN_WIDTH.
- The following example adds a FoldPanel to the FoldPanelBar and adds two
- wxWindow derived controls to the FoldPanel:
+ The wx.Window to be added can be slightly indented from left
+ and right so it is more visibly placed in the FoldPanel. Use
+ Spacing > 0 to give the control an y offset from the previous
+ wx.Window added, use leftSpacing to give it a slight indent
+ from the left, and rightSpacing also reserves a little space
+ on the right so the wxWindow can be properly placed in the
+ FoldPanel.
- # CODE
+ The following example adds a FoldPanel to the FoldPanelBar and
+ adds two wx.Window derived controls to the FoldPanel::
# create the FoldPanelBar
>>> m_pnl = FoldPanelBar(self, wx.ID_ANY, wx.DefaultPosition,
>>> m_pnl.AddFoldPanelWindow(item, wx.TextCtrl(item, wx.ID_ANY, "Comment"),
FPB_ALIGN_WIDTH, FPB_DEFAULT_SPACING, 20)
- # ENDCODE
"""
try:
"""
Adds a separator line to the current FoldPanel.
- The seperator is a simple line which is drawn and is no real component.
- It can be used to separate groups of controls which belong to each other.
- The colour is adjustable, and it takes the same Spacing, leftSpacing and
- rightSpacing as AddFoldPanelWindow().
+ The seperator is a simple line which is drawn and is no real
+ component. It can be used to separate groups of controls
+ which belong to each other. The colour is adjustable, and it
+ takes the same Spacing, leftSpacing and rightSpacing as
+ `AddFoldPanelWindow`.
"""
try:
def OnSizePanel(self, event):
- """ Handles the EVT_SIZE method for the FoldPanelBar. """
+ """ Handles the EVT_SIZE event for the FoldPanelBar. """
# skip all stuff when we are not initialised yet
pos = self._panels[i].GetItemPos() + self._panels[i].GetPanelLength()
for j in range(i+1, len(self._panels)):
pos = pos + self._panels[j].Reposition(pos)
-
self.Thaw()
-## self.Refresh()
def RedisplayFoldPanelItems(self):
""" Resizes the fold panels so they match the width. """
-
# resize them all. No need to reposition
-
for panels in self._panels:
panels.ResizePanel()
panels.Refresh()
"""
Repositions all the collapsed panels to the bottom.
- When it is not possible to align them to the bottom, stick them behind the
- visible panels. The Rect holds the slack area left between last repositioned
- panel and the bottom panels. This needs to get a refresh.
+ When it is not possible to align them to the bottom, stick
+ them behind the visible panels. The Rect holds the slack area
+ left between last repositioned panel and the bottom
+ panels. This needs to get a refresh.
"""
value = wx.Rect(0,0,0,0)
def GetPanelsLength(self, collapsed, expanded):
"""
- Returns the length of the panels that are expanded and collapsed.
+ Returns the length of the panels that are expanded and
+ collapsed.
- This is useful to determine quickly what size is used to display,
- and what is left at the bottom (right) to align the collapsed panels.
+ This is useful to determine quickly what size is used to
+ display, and what is left at the bottom (right) to align the
+ collapsed panels.
"""
value = 0
def Collapse(self, foldpanel):
"""
- Collapses the given FoldPanel reference, and updates the foldpanel bar.
+ Collapses the given FoldPanel reference, and updates the
+ foldpanel bar.
- In the FPB_COLLAPSE_TO_BOTTOM style, all collapsed captions are put at
- the bottom of the control. In the normal mode, they stay where they are.
+ In the FPB_COLLAPSE_TO_BOTTOM style, all collapsed captions
+ are put at the bottom of the control. In the normal mode, they
+ stay where they are.
"""
try:
def Expand(self, foldpanel):
"""
- Expands the given FoldPanel reference, and updates the foldpanel bar.
+ Expands the given FoldPanel reference, and updates the
+ foldpanel bar.
- In the FPB_COLLAPSE_TO_BOTTOM style, they will be removed from the bottom
- and the order where the panel originally was placed is restored.
+ In the FPB_COLLAPSE_TO_BOTTOM style, they will be removed from
+ the bottom and the order where the panel originally was placed
+ is restored.
"""
foldpanel.Expand()
def ApplyCaptionStyle(self, foldpanel, cbstyle):
"""
- Sets the style of the caption bar (called CaptionBar) of the FoldPanel.
+ Sets the style of the caption bar (`CaptionBar`) of the
+ FoldPanel.
- The changes are applied immediately. All styles not set in the CaptionBarStyle
- class are not applied. Use the CaptionBar reference to indicate what captionbar
- you want to apply the style to. To apply one style to all CaptionBar items, use
- ApplyCaptionStyleAll()
- """
-
+ The changes are applied immediately. All styles not set in the
+ CaptionBarStyle class are not applied. Use the CaptionBar
+ reference to indicate what captionbar you want to apply the
+ style to. To apply one style to all CaptionBar items, use
+ `ApplyCaptionStyleAll`
+ """
foldpanel.ApplyCaptionStyle(cbstyle)
def ApplyCaptionStyleAll(self, cbstyle):
- """ Sets the style of all the caption bars of the FoldPanel.
+ """
+ Sets the style of all the caption bars of the FoldPanel.
- The changes are applied immediately. """
-
+ The changes are applied immediately.
+ """
for panels in self._panels:
self.ApplyCaptionStyle(panels, cbstyle)
"""
Returns the currently used caption style for the FoldPanel.
- It is returned as a CaptionBarStyle class. After modifying it, it can be
- set again.
- """
-
+ It is returned as a CaptionBarStyle class. After modifying it,
+ it can be set again.
+ """
return foldpanel.GetCaptionStyle()
def IsVertical(self):
"""
- Returns wether the CaptionBar Has Default Orientation Or Not.
+ Returns whether the CaptionBar has default orientation or not.
Default is vertical.
- """
-
+ """
return self._isVertical
See the example at the bottom of the module, especially the events
for the "Collapse Me" and "Expand Me" buttons.
"""
-
try:
ind = self._panels[item]
return self._panels[item]
# --------------------------------------------------------------------------------- #
# class FoldPanelItem
-# This class is a child sibling of the FoldPanelBar class. It will contain a
-# CaptionBar class for receiving of events, and a the rest of the area can be
-# populated by a wxPanel derived class.
# --------------------------------------------------------------------------------- #
class FoldPanelItem(wx.Panel):
-
+ """
+ This class is a child sibling of the `FoldPanelBar` class. It will
+ contain a `CaptionBar` class for receiving of events, and a the
+ rest of the area can be populated by a `wx.Panel` derived class.
+ """
# Define Empty CaptionBar Style
EmptyCaptionBarStyle = CaptionBarStyle()
"""
Adds a window item to the list of items on this panel.
- The flags are FPB_ALIGN_LEFT for a non sizing window element, and
- FPB_ALIGN_WIDTH for a width aligned item. The Spacing parameter reserves
- a number of pixels before the window element, and leftSpacing is an indent.
- rightSpacing is only relevant when the style FPB_ALIGN_WIDTH is chosen.
+ The flags are FPB_ALIGN_LEFT for a non sizing window element,
+ and FPB_ALIGN_WIDTH for a width aligned item. The Spacing
+ parameter reserves a number of pixels before the window
+ element, and leftSpacing is an indent. rightSpacing is only
+ relevant when the style FPB_ALIGN_WIDTH is chosen.
"""
wi = FoldWindowItem(self, window, Type="WINDOW", flags=flags, Spacing=Spacing,
def Reposition(self, pos):
- """ Repositions this FoldPanelBar and reports the length occupied for the
- next FoldPanelBar in the list. """
-
+ """
+ Repositions this FoldPanelBar and reports the length occupied
+ for the next FoldPanelBar in the list.
+ """
# NOTE: Call Resize before Reposition when an item is added, because the new
# size needed will be calculated by Resize. Of course the relative position
# of the controls have to be correct in respect to the caption bar
self._itemPos = pos
self.Thaw()
-## self.Refresh()
return self.GetPanelLength()
[size.GetHeight()])[0], vertical)
self.Thaw()
-## self.Refresh()
def OnPaint(self, event):
def IsExpanded(self):
- """ Returns expanded or collapsed status.
-
- If the panel is expanded, True is returned. """
+ """
+ Returns expanded or collapsed status. If the panel is
+ expanded, True is returned.
+ """
return not self._captionBar.IsCollapsed()
def GetCaptionLength(self):
- """ Returns height of caption only. This is for folding calculation purposes. """
+ """
+ Returns height of caption only. This is for folding
+ calculation purposes.
+ """
size = self._captionBar.GetSize()
return (self.IsVertical() and [size.GetHeight()] or [size.GetWidth()])[0]
def GetCaptionStyle(self):
"""
- Returns the current style of the captionbar in a CaptionBarStyle class.
+ Returns the current style of the captionbar in a
+ CaptionBarStyle class.
This can be used to change and set back the changes.
"""
# ----------------------------------------------------------------------------------- #
# class FoldWindowItem
-# This class is a child sibling of the FoldPanelItem class. It will contain
-# wxWindow that can be either a separator (a colored line simulated by a wxWindow)
-# or a wxPython controls (such as a wxButton, a wxListCtrl etc...).
# ----------------------------------------------------------------------------------- #
class FoldWindowItem:
-
+ """
+ This class is a child sibling of the `FoldPanelItem` class. It
+ will contain wx.Window that can be either a separator (a colored
+ line simulated by a wx.Window) or a wxPython controls (such as a
+ wx.Button, a wx.ListCtrl etc...).
+ """
def __init__(self, parent, window=None, **kw):
"""
Default Class Constructor
- Initialize with:
+ Initialize with::
Type = "WINDOW", flags = FPB_ALIGN_WIDTH,
Spacing = FPB_DEFAULT_SPACING,
leftSpacing = FPB_DEFAULT_LEFTSPACING,
rightSpacing = FPB_DEFAULT_RIGHTSPACING
- or:
+ or::
Type = "SEPARATOR"
y, lineColor = wx.BLACK,
def GetWindowLength(self, vertical=True):
- """ Returns space needed by the window if type is FoldWindowItem "WINDOW"
- and returns the total size plus the extra spacing."""
+ """
+ Returns space needed by the window if type is FoldWindowItem
+ "WINDOW" and returns the total size plus the extra spacing.
+ """
value = 0
if self._type == "WINDOW":
projects / wxWidgets.git / commitdiff
