wxPython 4.3.2__cp315-cp315-win_amd64.whl

wx/lib/agw/persist/__init__.py

@@ -0,0 +1,188 @@
+"""
+Persistent objects are simply the objects which automatically save their state
+when they are destroyed and restore it when they are recreated, even during
+another program invocation.
+
+
+.. _persistent-overview:
+
+Persistent Object Overview
+==========================
+
+Most often, persistent objects are, in fact, persistent windows as it is especially
+convenient to automatically restore the UI state when the program is restarted but
+an object of any class can be made persistent. Moreover, persistence is implemented
+in a non-intrusive way so that the original object class doesn't need to be modified
+at all in order to add support for saving and restoring its properties.
+
+The persistence framework involves:
+
+* **PersistenceManager** which all persistent objects register themselves with. This class
+  handles actual saving and restoring of persistent data as well as various global
+  aspects of persistence, e.g. it can be used to disable restoring the saved data;
+* **PersistentObject** is the base class for all persistent objects or, rather, adaptors
+  for the persistent objects as this class main purpose is to provide the bridge between
+  the original class -- which has no special persistence support -- and PersistenceManager;
+* **PersistentHandlers** which handle different kind of saving/restoring actions depending
+  on the widget kind.
+
+
+Using Persistent Windows
+========================
+
+wxPython has built-in support for a (constantly growing) number of controls. Currently the
+following classes are supported:
+
+* wx.TopLevelWindow (and hence wx.Frame and wx.Dialog, together with their own AUI perspectives);
+* wx.MenuBar, FlatMenuBar;
+* AuiToolBar;
+* wx.Notebook, wx.Toolbook, wx.Treebook, wx.Choicebook, AuiNotebook (together with its own AUI perspective),
+  FlatNotebook, LabelBook, FlatImageBook;
+* wx.CheckBox;
+* wx.ListBox, wx.VListBox, wx.HtmlListBox, wx.SimpleHtmlListBox, wx.adv.EditableListBox;
+* wx.ListCtrl, wx.ListView, UltimateListCtrl;
+* wx.CheckListBox;
+* wx.Choice, wx.ComboBox, wx.adv.OwnerDrawnComboBox;
+* wx.RadioBox;
+* wx.RadioButton;
+* wx.ScrolledWindow, wx.lib.scrolledpanel.ScrolledPanel;
+* wx.Slider, KnobCtrl;
+* wx.SpinButton, wx.SpinCtrl, FloatSpin;
+* wx.SplitterWindow;
+* wx.TextCtrl, wx.SearchCtrl, wx.lib.expando.ExpandoTextCtrl, wx.lib.masked.Ctrl;
+* wx.ToggleButton, wx.lib.buttons.GenToggleButton, wx.lib.buttons.GenBitmapToggleButton,
+  wx.lib.buttons.GenBitmapTextToggleButton, SToggleButton,
+  SBitmapToggleButton, SBitmapTextToggleButton;
+* wx.TreeCtrl, wx.GenericDirCtrl, CustomTreeCtrl;
+* HyperTreeList;
+* wx.lib.calendar.CalendarCtrl, wx.adv.CalendarCtrl;
+* wx.CollapsiblePane, PyCollapsiblePane;
+* wx.adv.DatePickerCtrl, wx.adv.GenericDatePickerCtrl;
+* wx.media.MediaCtrl;
+* wx.ColourPickerCtrl, wx.lib.colourselect.ColourSelect;
+* wx.FilePickerCtrl, wx.DirPickerCtrl;
+* wx.FontPickerCtrl;
+* wx.FileHistory;
+* wx.DirDialog, wx.FileDialog;
+* wx.FindReplaceDialog;
+* wx.FontDialog;
+* wx.ColourDialog, CubeColourDialog;
+* FoldPanelBar;
+* wx.SingleChoiceDialog, wx.MultiChoiceDialog;
+* wx.TextEntryDialog, wx.PasswordEntryDialog.
+
+
+To automatically save and restore the properties of the windows of classes listed
+above you need to:
+
+* Set a unique name for the window using `SetName()`: this step is important as the
+  name is used in the configuration file and so must be unique among all windows of
+  the same class;
+* Call `PersistenceManager.Register(window)` at any moment after creating the window
+  and then `PersistenceManager.Restore(window)` when the settings may be restored
+  (which can't be always done immediately, e.g. often the window needs to be populated
+  first). If settings can be restored immediately after the window creation, as is often
+  the case for wx.TopLevelWindow, for example, then `PersistenceManager.RegisterAndRestore(window)`
+  can be used to do both at once.
+* If you want the settings for the window to be saved when your main frame is destroyed (or your app closes), simply call
+  `PersistenceManager.SaveAndUnregister(window)` with no arguments.
+
+
+Usage
+=====
+
+Example of using a notebook control which automatically remembers the last open page::
+
+    import wx, os
+    import wx.lib.agw.persist as PM
+
+    class MyFrame(wx.Frame):
+
+        def __init__(self, parent):
+
+            wx.Frame.__init__(self, parent, -1, "Persistent Controls Demo")
+
+            self.book = wx.Notebook(self, wx.ID_ANY)
+
+            # Very important step!!
+            self.book.SetName("MyBook") # Do not use the default name!!
+
+            self.book.AddPage(wx.Panel(self.book), "Hello")
+            self.book.AddPage(wx.Panel(self.book), "World")
+            self.Bind(wx.EVT_CLOSE, self.OnClose)
+
+            self._persistMgr = PM.PersistenceManager.Get()
+
+            _configFile = os.path.join(os.getcwd(), self.book.GetName())
+            self._persistMgr.SetPersistenceFile(_configFile)
+
+            if not self._persistMgr.RegisterAndRestoreAll(self.book):
+                # Nothing was restored, so choose the default page ourselves
+                self.book.SetSelection(0)
+
+        def OnClose(self, event):
+            self._persistMgr.SaveAndUnregister(self.book)
+            event.Skip()
+
+    # our normal wxApp-derived class, as usual
+
+    app = wx.App(0)
+
+    frame = MyFrame(None)
+    app.SetTopWindow(frame)
+    frame.Show()
+
+    app.MainLoop()
+
+
+.. _persistent-windows:
+
+Defining Custom Persistent Windows
+==================================
+
+User-defined classes can be easily integrated with PersistenceManager. To add support
+for your custom class MyWidget you just need to:
+
+* Define a MyWidgetHandler class inheriting from `AbstractHandler`;
+* Implement its `GetKind()` method returning a unique string identifying all MyWidget
+  objects, typically something like "widget";
+* Implement its `Save()` and `Restore()` methods to actually save and restore the widget
+  settings using `PersistentObject.SaveValue()` and `PersistentObject.RestoreValue()` methods.
+
+If you want to add persistence support for a class not deriving from wx.Window, you need
+to derive MyPersistentWidget directly from PersistentObject and so implement its
+`PersistentObject.GetName()` method too. Additionally, you must ensure that
+`PersistenceManager.SaveAndUnregister()` is called when your object is destroyed as this
+can be only done automatically for windows.
+
+
+TODOs
+=====
+
+* Find a way to handle :class:`ToolBar` UI settings as it has been done for :class:`~wx.lib.agw.aui.auibar.AuiToolBar`:
+  current :class:`ToolBar` doesn't seem to have easy access to the underlying toolbar tools;
+* Implement handler(s) for :class:`grid.Grid` for row/columns sizes (possibly adding another style
+  to `PersistenceManager` as :class:`grid.Grid` sets up arrays to store individual row and column
+  sizes when non-default sizes are used. The memory requirements for this could become prohibitive
+  if the grid is very large);
+* Find a way to properly save and restore dialog data (:class:`wx.ColourDialog`, :class:`wx.FontDialog` etc...);
+* Add handlers for the remaining widgets not yet wrapped (mostly in :mod:`lib`).
+
+
+License And Version
+===================
+
+`PersistentObjects` library is distributed under the wxPython license.
+
+Latest revision: Andrea Gavana @ 27 Mar 2013, 21.00 GMT
+Version 0.5.
+
+"""
+
+__author__ = "Andrea Gavana <andrea.gavana@gmail.com>"
+__date__ = "16 November 2009"
+
+
+from .persist_constants import *
+from .persistencemanager import *
+from .persist_handlers import *

wx/lib/agw/persist/persist_constants.py

@@ -0,0 +1,283 @@
+# -*- coding: utf-8 -*-
+# --------------------------------------------------------------------------- #
+#
+# Tags:        phoenix-port, unittest, documented, py3-port
+#
+# End Of Comments
+# --------------------------------------------------------------------------- #
+
+"""
+This module contains all the constants used by the persistent objects.
+"""
+
+import wx
+import wx.dataview as dv
+
+# ----------------------------------------------------------------------------------- #
+# PersistenceManager styles
+
+PM_SAVE_RESTORE_AUI_PERSPECTIVES     = 1 << 0
+PM_SAVE_RESTORE_TREE_LIST_SELECTIONS = 1 << 1
+PM_PERSIST_CONTROL_VALUE             = 1 << 2
+PM_RESTORE_CAPTION_FROM_CODE         = 1 << 3
+PM_DEFAULT_STYLE                     = PM_SAVE_RESTORE_AUI_PERSPECTIVES | PM_PERSIST_CONTROL_VALUE
+
+# ----------------------------------------------------------------------------------- #
+CONFIG_PATH_SEPARATOR = "/"
+
+BAD_DEFAULT_NAMES = ["widget", "wxSpinButton", "auiFloating", "AuiTabCtrl", "maskedTextCtrl",
+                     "numctrl", "IpAddrCtrl", "masked.num", "time", "scrolledpanel", "cPanel",
+                     "wxdataviewctrlmainwindow"]
+
+for name in dir(wx):
+    if "NameStr" in name:
+        val = getattr(wx, name)
+        if isinstance(val, bytes):
+            val = val.decode('utf-8')
+        BAD_DEFAULT_NAMES.append(val)
+
+for name in dir(dv):
+    if "NameStr" in name:
+        val = getattr(dv, name)
+        if isinstance(val, bytes):
+            val = val.decode('utf-8')
+        BAD_DEFAULT_NAMES.append(val)
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by BookHandler
+
+PERSIST_BOOK_KIND = "Book"
+PERSIST_BOOK_SELECTION = "Selection"
+
+# To save and restore wx.lib.agw.aui.AuiNotebook perspectives
+PERSIST_BOOK_AGW_AUI_PERSPECTIVE = "AGWAui_Notebook_Perspective"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by TreebookHandler
+
+PERSIST_TREEBOOK_KIND = "TreeBook"
+
+# this key contains the indices of all expanded nodes in the tree book
+# separated by PERSIST_SEP
+PERSIST_TREEBOOK_EXPANDED_BRANCHES = "Expanded"
+PERSIST_SEP = ','
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by TLWHandler
+
+# we use just "Window" to keep configuration files and such short, there
+# should be no confusion with wx.Window itself as we don't have persistent
+# windows, just persistent controls which have their own specific kind strings
+
+PERSIST_TLW_KIND = "Window"
+
+# Names for various persistent options
+PERSIST_TLW_X = "x"
+PERSIST_TLW_Y = "y"
+PERSIST_TLW_W = "w"
+PERSIST_TLW_H = "h"
+
+PERSIST_TLW_MAXIMIZED = "Maximized"
+PERSIST_TLW_ICONIZED = "Iconized"
+
+# To save and restore wx.aui and wx.lib.agw.aui perspectives
+PERSIST_AGW_AUI_PERSPECTIVE = "AGWAui_Perspective"
+PERSIST_AUI_PERSPECTIVE = "Aui_Perspective"
+
+PERSIST_AUIPERSPECTIVE_KIND = "AUI manager"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by CheckBoxHandler
+
+PERSIST_CHECKBOX_KIND = "CheckBox"
+PERSIST_CHECKBOX_3STATE = "3StateValue"
+PERSIST_CHECKBOX = "Value"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by ListBoxHandler
+
+PERSIST_LISTBOX_KIND = "ListBox"
+PERSIST_LISTBOX_SELECTIONS = "Selections"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by ListCtrlHandler
+
+PERSIST_LISTCTRL_KIND = "ListCtrl"
+PERSIST_LISTCTRL_COLWIDTHS = "ColWidths"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by CheckListBoxHandler
+
+PERSIST_CHECKLISTBOX_KIND = "CheckListBox"
+PERSIST_CHECKLIST_CHECKED = "Checked"
+PERSIST_CHECKLIST_SELECTIONS = "Selections"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by ChoiceComboHandler
+
+PERSIST_CHOICECOMBO_KIND = "ComboBox"
+PERSIST_CHOICECOMBO_SELECTION = "Selection"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by RadioBoxHandler
+
+PERSIST_RADIOBOX_KIND = "RadioBox"
+PERSIST_RADIOBOX_SELECTION = "Selection"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by RadioButtonHandler
+
+PERSIST_RADIOBUTTON_KIND = "RadioButton"
+PERSIST_RADIOBUTTON_VALUE = "Value"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by ScrolledWindowHandler
+
+PERSIST_SCROLLEDWINDOW_KIND = "ScrolledWindow"
+PERSIST_SCROLLEDWINDOW_POS_H = "Scroll_H"
+PERSIST_SCROLLEDWINDOW_POS_V = "Scroll_V"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by SliderHandler
+
+PERSIST_SLIDER_KIND = "Slider"
+PERSIST_SLIDER_VALUE = "Value"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by SpinHandler
+
+PERSIST_SPIN_KIND = "Spin"
+PERSIST_SPIN_VALUE = "Value"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by SplitterHandler
+
+PERSIST_SPLITTER_KIND = "Splitter"
+PERSIST_SPLITTER_POSITION = "Position"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by TextCtrlHandler
+
+PERSIST_TEXTCTRL_KIND = "TextCtrl"
+PERSIST_TEXTCTRL_VALUE = "Value"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by ToggleButtonHandler
+
+PERSIST_TOGGLEBUTTON_KIND = "ToggleButton"
+PERSIST_TOGGLEBUTTON_TOGGLED = "Toggled"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by TreeCtrlHandler
+
+PERSIST_TREECTRL_KIND = "TreeCtrl"
+PERSIST_TREECTRL_CHECKED_ITEMS = "Checked"
+PERSIST_TREECTRL_EXPANSION = "Expansion"
+PERSIST_TREECTRL_SELECTIONS = "Selections"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by TreeListCtrlHandler
+
+PERSIST_TREELISTCTRL_KIND = "TreeListCtrl"
+PERSIST_TREELISTCTRL_COLWIDTHS = "ColWidths"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by CalendarCtrlHandler
+
+PERSIST_CALENDAR_KIND = "Calendar"
+PERSIST_CALENDAR_DATE = "Date"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by CollapsiblePaneHandler
+
+PERSIST_COLLAPSIBLE_KIND = "Collapsible"
+PERSIST_COLLAPSIBLE_STATE = "Collapse"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by DatePickerHandler
+
+PERSIST_DATEPICKER_KIND = "DatePicker"
+PERSIST_DATEPICKER_DATE = "Date"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by MediaCtrlHandler
+
+PERSIST_MEDIA_KIND = "MediaCtrl"
+
+PERSIST_MEDIA_POS = "Seek"
+PERSIST_MEDIA_VOLUME = "Volume"
+PERSIST_MEDIA_RATE = "Rate"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by ColourPickerHandler
+
+PERSIST_COLOURPICKER_KIND = "ColourPicker"
+PERSIST_COLOURPICKER_COLOUR = "Colour"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by FileDirPickerHandler
+
+PERSIST_FILEDIRPICKER_KIND = "FileDirPicker"
+PERSIST_FILEDIRPICKER_PATH = "Path"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by FontPickerHandler
+
+PERSIST_FONTPICKER_KIND = "FontPicker"
+PERSIST_FONTPICKER_FONT = "Font"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by FileHistoryHandler
+
+PERSIST_FILEHISTORY_KIND = "FileHistory"
+PERSIST_FILEHISTORY_PATHS = "Paths"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by FindReplaceHandler
+
+PERSIST_FINDREPLACE_KIND = "FindReplace"
+PERSIST_FINDREPLACE_FLAGS = "Flags"
+PERSIST_FINDREPLACE_SEARCH = "Search"
+PERSIST_FINDREPLACE_REPLACE = "Replace"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by FontDialogHandler
+
+PERSIST_FONTDIALOG_KIND = "FontDialog"
+PERSIST_FONTDIALOG_EFFECTS = "Effects"
+PERSIST_FONTDIALOG_SYMBOLS = "Symbols"
+PERSIST_FONTDIALOG_COLOUR = "Colour"
+PERSIST_FONTDIALOG_FONT = "Font"
+PERSIST_FONTDIALOG_HELP = "Help"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by ColourDialogHandler
+
+PERSIST_COLOURDIALOG_KIND = "ColourDialog"
+PERSIST_COLOURDIALOG_COLOUR = "Colour"
+PERSIST_COLOURDIALOG_CHOOSEFULL = "ChooseFull"
+PERSIST_COLOURDIALOG_CUSTOMCOLOURS = "CustomColours"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by ChoiceDialogHandler
+
+PERSIST_CHOICEDIALOG_KIND = "ChoiceDialog"
+PERSIST_CHOICEDIALOG_SELECTIONS = "Selections"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by MenuBarHandler
+
+PERSIST_MENUBAR_KIND = "MenuBar"
+PERSIST_MENUBAR_CHECKRADIO_ITEMS = "Checked"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by ToolBarHandler
+
+PERSIST_TOOLBAR_KIND = "ToolBar"
+PERSIST_TOOLBAR_CHECKRADIO_ITEMS = "Checked"
+
+# ----------------------------------------------------------------------------------- #
+# String constants used by FoldPanelBarHandler
+
+PERSIST_FOLDPANELBAR_KIND = "FoldPanelBar"
+PERSIST_FOLDPANELBAR_EXPANDED = "FoldpPanelExpanded"