How to store a stack in a custom property

[J. Landman Gay]

Joe Lewis Wilkins wrote:
> 
> I'm obviously missing something, since all of the things you mention can 
> be done with external text files or other stacks that can be read or 
> written to from scripts when their needs arise. I've done some pretty 
> sophisticated data manipulation in this manner.

It's true you can often substitute other methods for the use of custom 
properties, but that can be like using a screwdriver to pound nails. The 
right tool is usually a better option and allows you to do more with 
less work.

> I guess I just don't like the name "custom property" for its being
 > to non-descriptive of what it "is/does/can do".

I think it's fairly well-named. All objects have lots of built-in 
properties -- name, location, ID, etc. A custom property is simply one 
you have defined yourself. You can invent any property you need for an 
object, which is very handy. Once assigned, it acts just like the 
built-in ones.

An example: there is a built-in "version" property that returns the 
version of Rev you are using. There is also a built-in "systemversion" 
property that returns the version of the running OS. But suppose you 
want to know which version of your own stack is running? There's no 
built-in way to do that, and in fact, Rev doesn't even assume stacks 
have version numbers.

You could solve this in any number of ways. You could write a function 
that returns the stack's version number. Every time you update the 
stack, you'll have to revise the function and recompile the script. Or 
you could store the version number in a hidden field. That means if you 
do any kind of field processing in a loop, or anything that relies on 
layering order, you have to work around that hidden field because it 
will get in the way. You could store the version number in a preferences 
file, but then you have to write code to retrieve that.

The best tool for this job is to use a custom property. You can just 
invent your own property and it will act exactly like one of the 
built-in ones. So let's invent a property called "stackVersion". It's 
purpose will be to store the current version of your stack. Like 
variables, all you have to do is set the property and it will be 
created. So let's set it:

  set the stackVersion of this stack to "1.0"

Now the property is created, the value "1.0" is stored and you can use 
it exactly as you do any other property. Here are some stack properties 
for comparison:

put the rect of this stack -- returns 4 numbers in a list
put the backgroundcolor of this stack -- returns an RGB color
put the name of this stack -- returns a string containing the name
put the stackVersion of this stack -- returns "1.0"

You can see that your custom property acts exactly like the native ones 
and has the same syntax.

So now let's say I want to show the stack version in both my About box 
and also on the main stack. In my About stack or card script, I just do 
this:

  put the stackVersion of stack (the mainstack of this stack) into fld 
"version_about"

And in my main stack:

  put the stackVersion of this stack into fld "version_main"

Once you have set up a custom property, it is permanent and survives 
across sessions, unlike variables which are temporary. You don't have to 
create and store a hidden field or hard-code the version into your 
script. When you update your stack and want to change the version, you 
just put the new value into the custom property and all your scripts 
automatically show the newest version without you doing anything else. 
You don't have to remember every script location that needs changing, or 
where you put a hidden field.

Another big advantage is that custom properties can store anything: 
binary data, arrays, whole stacks or standalones, images, anything. I 
have used them to store stack templates, as Sarah mentioned. I certainly 
could have created a separate stack and duplicated that on disk when 
needed, but external files can easily get lost. Users delete them, or 
they get separated from their folder. Or I could have made the template 
into a substack and cloned that, but there's a bit of scripting to do 
for that. But when the stack template is stored directly as a property, 
I can write it to disk in one line of script, and I don't have an extra 
substack hanging around and possibly in the way.

I have used custom properties to store movies for clients who don't want 
their proprietary work to be visible on disk or copied. You can do the 
same with images or any other file that you don't want users to have 
easy access to. Custom properties are like hidden storage without the 
overhead of any extra objects.

-- 
Jacqueline Landman Gay         |     jacque at hyperactivesw.com
HyperActive Software           |     http://www.hyperactivesw.com