[Laszlo-dev] attribute list format: proposal and problems

[P T Withington]

On 2007-10-11, at 19:03 EDT, Benjamin Shine wrote:

> A few of us came up with a proposal for how to handle the attribute  
> list format in the new docs. This email describes the proposal,  
> gives examples, and identifies problems. Please review and comment.
>
> In the 3.4 docs, we listed...
> Name / Usage / Type (tag) / Type (JS) / Default / Category
>
> The current proposal is to collapse Usage and Category into a  
> single column, tentatively named Category, but I suspect there's  
> something better. For the purposes of this discussion, let's call  
> it "Flavor." The Flavor column would contain exactly one of these  
> four choices:
> * tag only

What is tag-only supposed to mean?  Because I think there are two  
uses of tag-only that we need to disambiguate:

1) const (what is incorrectly called final in the 3.4 doc, see my  
comment [*] below in edittext)

These properties must be set at construct time, but there is nothing  
that prevents you from dynamically instantiating the tag and passing  
_initial_ values to these properties (you just can't change them once  
the class/tag is instantiated).  So they are not really 'tag only'.

2) "special" properties that are processed by the compiler at compile  
time

These properties really cannot be manipulated at run time.  An  
example is the canvas.debug property.  This property is looked at by  
the compiler to control whether or not your code is annotated for  
debugging.  You can't set this at run time.  You can't even  
initialize it at run time (if you could dynamically instantiate a  
canvas).

> * read-write
> * read only
> * javascript only

By the same token, I would like to know what javascript-only is  
supposed to mean, because any attribute that is read-write can be set  
in LZX by saying:

   <attribute name="whatever" value="youwant" />

So, I'm thinking the 'flavors' really should be:

special, const, read-only, read/write

> These flavors don't quite capture all the information in the old  
> category + usage. See "Lab Notes" below for intresting/tricky details.
>
> A fundamental underlying problem is that the read-only-ness of  
> anything is just a suggestion; the actual bits of data in the  
> runtime model are not protected. Calling them "read-only" really  
> means "undefined and probably incorrect behavior will result from  
> trying to modify these at runtime." Tucker, is that correct? Do we  
> do any runtime protection against writing?

In nearly all runtimes, saying an attribute is read-only is only  
advisory.  In swf9/js2 you will be able to define a setter method  
that could be used to enforce read-only (to an extent, since nothing  
in the run time prevents a malicious user from removing the setter).   
Nevertheless, I think this is a useful flavor to document, for  
exactly the reasons you state.

> In the next few days, I hope to propose something reasonable and  
> readily implementable with the information currently represented in  
> the markup in lzx and lfc source.
>
> *** Lab Notes from an experiment with attributes of <edittext> ***
>
> Some attributes seem to map easily to a flavor: read-write is  
> relatively uncomplicated.
>
> Name     current "Usage"  current "Category"     ===> Flavor
> maxlength 	Tag & JS	setter		read-write
> pattern		Tag & JS	setter		read-write
>
> The picture quickly gets complicated:
> Name     current "Usage"  current "Category"     ===> Flavor
> multiline	Tag only	final		?
> password	Tag only	final		?
>
> ...but closer inspection reveals problems: in script, one may read  
> the values of myedittext.password and myedittext.multiline; how is  
> it tag only? The password attribute is a current topic of interest,  
> and rather complicated. "Tag only" and "final" don't seem to cover it.

I believe the pedigree of these attributes is tainted by old  
runtimes, no longer supported, that were not amenable to these  
features being changed at run time.

[*] Other languages that I know would call these attributes `const`  
not `final`, I think.  That is, they can be initialized only once at  
instantiation time.  `final` means they cannot be overridden, which  
is not really what you are trying to say.  For instance, I think it  
would be perfectly reasonable to have a `pwedittext` class subclass  
`edittext` and default `password` to `true` (overriding the parent  
class's declaration, but not changing the fact that it cannot be  
changed at run time).

> Name     current "Usage"  current "Category"     ===> Flavor
> focusable	Tag & JS	read only	read only
> id		Tag & JS 	read only	read only
> clip		Tag only	final		tag only
>
> Is focusable really read only? I thought you could change  
> something's focusable-ness at runtime, but how would the doctools  
> or a developer know that? (I would have to actually write a test to  
> figure it out.) On the other hand, I believe that "id" really is  
> read only.

As we disussed in person, the 3.4 documentation is not gospel.  There  
are surely bugs in it, and here are a few.  I'm betting the read- 
onlyness of focusable is a relic from old run times, and really means  
const (aka final, as with clip).

ID is not just read only, it is const (or final in the old  
terminology).  The id of an instance must be set at instantiation time.

> JS only AND readonly seems to require a new flavor:
> Name     current "Usage"  current "Category"     ===> Flavor
> hassetheight	JS only		read only 	?
> totalframes	JS only		read only	?
> classroot	JS only		read only	?
>
> ...this flavor seems to be "never modify these unless you are  
> editing the LFC and you really know what you're doing."

These really are read only.  The first two should probably be private.

> Event handlers are weird -- why are some "eventhandler" and some  
> "setter"? Is there actually a difference in usage between (for  
> instance) onmousedown and onkeydown, or is this just a doc error?
> Name     current "Usage"  current "Category"     ===> Flavor
> onblur		Tag only	eventhandler     ?
> onmousedown	Tag only	eventhandler     ?
> onkeydown	Tag & JS	setter           ?
> ondata		Tag & JS	setter		 ?

These are all events (not eventhandlers).  I suspect this is all old- 
doc-tool wonkiness (because of the multiple sources it tried to glean  
information from).  Probably the ones that are listed as 'tag-only'  
are ones that are declared in the schema (and implicit in  
Javascript), and the ones that are 'setter' are declared in  
Javascript and not the schema.  Remember in the 3.x world, every  
attribute implicitly has an event associated with it, whereas in the  
4.x world, you have to declare events up front for them to work.

> And some fundamental class system things are tricky:
> Name     current "Usage"  current "Category"     ===> Flavor
> class		Tag only	final           ?  (You can examine myview.class in  
> javascript; it's not really tag only.)

No idea what this is trying to say, since you surely can't initialize  
your class!  We really ought to obsolete this altogether because you  
really want to be asking `instanceof` or `is` if you are asking type  
questions, not looking at the string name of your class.