From 35994ca3a4ef6a136a16cac63b4f68540d0434e1 Mon Sep 17 00:00:00 2001 From: Frank Barknecht Date: Fri, 23 Apr 2004 16:22:42 +0000 Subject: This commit was generated by cvs2svn to compensate for changes in r1630, which included commits to RCS files with non-trunk default branches. svn path=/trunk/abstractions/rradical/; revision=1631 --- memento/README.txt | 148 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 memento/README.txt (limited to 'memento/README.txt') diff --git a/memento/README.txt b/memento/README.txt new file mode 100644 index 0000000..7fa3dfa --- /dev/null +++ b/memento/README.txt @@ -0,0 +1,148 @@ +_ Memento _ + +ver. 0.4 + +This is a work-in-progress collection of a unified preset system for Pd +patches. It tries to loosely follow the Memento [1] design pattern from the Gang of +Four book. + +I propose that a Memento here is realised as a directory in a data pool inside +a [pool] object. Currently the pool is hardcoded to be named "RRADICAL". This +could change, but maybe it doesn't need to. Inside the Memento, several +numbered subfolders are created to store the actual substates. + +The Memento is only changed or read through the [originator] abstraction. +[originator] has two arguments: + +1) the name of a Memento +2) $0 + +Methods of [originator]: + + * create Memento-name: creates a new Memento, discards the old. + * set anything: sets all variables to the values currently in the pool. For use + after loading a file with the [caretaker] + * substate management + * right inlet: OSC messages + * some more. Look inside. + +It is not allowed to bypass [originator] to change the values inside the +RRADICAL pool, with one exception: + +The [caretaker] abstraction is responsible for saving and loading pool data from +harddisk. [caretaker] takes a filename to save and load as argument. A GUI for +it is provided in [careGUI]. + +Methods of [caretaker]: + + * file filename: set's filename to save/load. + * save poolname: saves the contents of the pool named "poolname". For rradical + patches this currently has to be "RRADICAL" + * load poolname: loads the contents, same as save, but the other way around. + +Communication between [originator] and anything that wants to save anything is +done through the [commun] abstraction. + +[commun] arguments: + +1) the name of a variable ("key") +2) $0 + +[commun] accepts anything and spits out anything if [originator] tells it too +(with [originator]'s "set" message). + +Both $0 arguments above are mandatory to keep Memento reusable, which is the +first goal all in RRADical patches. + +_ Usage _ + +Every abstraction, that wants to take part in saving its settings with Memento +needs to: +1) include an [originator /Memento $0] objects +2) cross-wrap all variables with [commun /id $0] objects. Because of a bug, + for wrapping symbols a [symbol] objects has to be added after [commun]'s + outlet. +3) The slash is there to allow routing of OSC-messages for remote control. + +A single [caretaker] or [careGUI] in the parent patch then can save and reload +settings in the pool to disk. + +Please follow the tutorial to learn more about Memento-usage. + +_ ChangeLog _ + +0.4 +* Wrote a tutorial, yeah. +* Now uses Cyclone's set-able prepend for setting state. +* originator got a OSC-inlet. +* requires a "pool" with the mkchdir messages (available in CVS since Dec 17 2003) +* some cleanup + +0.3 +* OSC remote control. Useage example is in netcontrol.pd +* copy/paste with messages copy and past to originator. + +0.2 +* Use numbered subfolders as states +* More examples, careGUI.pd + +0.1 +* Initial release + +_ Bugs _ + +* Plenty. +* [prepend] strips off type identifiers like "symbol", so you currently have to + take care of types yourself. Only lists and floats work out of the box + currently. +* The "API" is is bound to change. +* spelling errors + +_ Footnotes _ + +[1] Here's a description of the Memento pattern by Kamal Patel from +http://www.kamalpatel.net/Articles/MementoPattern.htm + +A look at a Design Pattern - Memento: + +A Design Pattern can be thought of as an architectural layout to solve a +problem whose actual implementation could be in millions of ways. The approach +used to solve this problem is by a Design Pattern called Memento. The intent of +a Memento is to capture and externalize an object's internal state so +that the object can be restored to this state later. + +Every Design pattern has a motivation. The Motivation behind the Memento +Pattern arose from the need to store the objects current state and then be able + to restore it when requested. Let us look at an example where a Memento Pattern +could be used. Consider that we want to implement Undo features into our +application. We will need to keep a track of changes as the user works by +capturing each state via a Memento object and then when the user requests an +Undo, we will request the Memento to reset to an the last stored state. We +would achieve this by the two general interfaces exposed by the Memento; +GetState() and SetState(). + +A memento pattern is constructed by three objects: + +Memento +Stores internal state of the Originator object. +Protects against access by objects other than the originator. Mementos +effectively have two interfaces (methods). + +Originator +Creates a Memento containing a snapshot of its current internal state +Uses the Memento to restore its internal state + +CareTaker +Is responsible for the Memento's safekeeping +Never operates on or examines the state of the Memento + +Generally a memento is responsible for storing a snapshot of the internal state +of another object. In our case the Memento was responsible for storing the +state of a grid and restoring the state of the grid upon request. Mementos are +usually dynamic in nature but we used the same concept to store persistent +state of the grids into a VFP table. This is because it was faster an easier to +maintain. + +Remember that Design Patterns provide us with a guidance to solve a problem for +the most commonly occurring software problems. We use this as a basis for our +design and then enhance or extend the design depending on our requirements. -- cgit v1.2.1