New User Doc Whine & What?

[Ken Ray]

On Thu, 3 Jan 2008 13:07:29 -0500, Mike Arnold wrote:

> New user of RR Studio 2.8.1 Build 472 on Mac OS/X 10.4.11 PPC G4.

Hey, Mike... welcome to Revolution!
 
> I have put together the beginnings of an application that uses mySQL, 
> with a mainstack and (so far) 3 substacks.  Things are going slow, 
> but making progress.  Took a while to figure out why my mainstack's 
> openstack & closestack scripts got control when I opened/closed a 
> substack ... almost seems like a bug, but I am getting the hang of 
> it, I think. (added null message handlers to substacks and all was 
> well)  Still trying to figure out what goes in openCard vs openStack 
> ... normal learning curve.  

The reason why the substacks' messages go to the mainstack is due to 
Revolution's message-passing hierarchy; most messages that not trapped 
by the object that gets them travel along the hierarchy until they are 
trapped or finally reach the Revolution engine itself. For more info on 
this, check out the "Message Hierarchy" tutorial (#4) in the Scripting 
Conferences area of the Runtime Revolution site:

   http://support.runrev.com/scriptingconferences/

In fact, I'm sure these tutorial stacks will help in other areas as 
well.

> Then I decided to add a checkbox button.  Spent an inordinate amount 
> of time trying to figure out how to retrieve the check/not-checked 
> status.  Very frustrating.  No where could I find it documented.
> The are both containers ... but 'field "myField"' returns the 
> contents of a field, though 'button "myButton"' does not return the 
> checked status.  I assigned a value of false to the button, and it 
> retained it forever (so a check box _is_ a container, just not 
> related to the check box status).  I finally looked at an example 
> that had a check box to find the hilite property (well keyword, the 
> hilite property in the dictionary says it is used to set the value, 
> not test it).  Who would have thought ...

Good point. In fact I attempted to find the answer to this same 
question, imagining that I was new to Rev. Here's my experience:

1) I assumed this would be documented, so I went to the online 
documentation, which if I was a first time user, would take me to the 
Getting Started screen of the docs.

2) Of the six options there, the most reasonable choice is "Using 
Objects", so I clicked that, which took me to the Tutorial Chooser.

3) I looked at the five options there to see if anything about buttons 
are mentioned, and the first one "Interface objects" mentioned buttons, 
so I clicked it (although it was already highlighted), and the options 
were Download PDF or Download Video. Not sure which one should provide 
the answer, I figured I'd double-click on the line and see if there is 
a default choice. 

4) Turned out there was; the video downloaded and started to play, but 
I could only hear the audio; the area of the QT player didn't redraw 
and so I couldn't figure out what was going on (must be some bug with 
my system - I hope). So I clicked Download PDF.

5) Looked a the PDF and did a search for "checkbox"; although it had a 
handful of hits, there was no help there (no scripts, just interface 
layout). So I closed that and returned to the Tutorial Chooser.

6) I looked to see if there was another tutorial that might help - 
perhaps "Properties: Customizing interface and window objects to suit 
your needs"? So I tried the video for that one (same problem as before) 
and went to the PDF.

7) Opened the PDF and did a search for "checkbox" - no hits. Searches 
on "check" and "checked" (perhaps that's the property?) also resulted 
in no hits.

8) Back to the Docs - perhaps some other area of the docs? Clicked on 
"User Guide", and launched the PDF, did a search for "checkbox" - 
hooray! 14 hits!

9) Clicked through three of them to get to one where there's a line 
that states "This example sets a checkbox in the current stack to have 
the same setting as a checkbox in another stack..." and there's code 
chunks on the page - bingo! This should do it; the script goes to the 
next page, so I followed it...

10) Sure enough, there is an example of getting/setting the "hilite" of 
the button.

As you can see, it took me a lot of back-and-forths and dead ends until 
I finally came up with the answer. 

Suppose I attempted to look in the Dictionary? Nope... a search for 
"checkbox" lists nothing; "check" only lists "checkmark", which isn't 
helpful. Perhaps "button"? OK, well I got a lot of results of keywords 
that apply to buttons, but I'd have to look through them one at a time 
to find the right one.

How about the Glossary? I type in "checkbox" and get a hit, but it's of 
course only a definition with synonyms and not properties, etc. No help 
there.

How about Search? After getting a notice about building databases  
(which I activate and wait until it's done), I did a search on 
"checkbox", which after a long search (took about a minute to complete 
on my MacBookPro) returned 54 related entries doing a "deep search" (it 
didn't return any with a Quick search). The first item in the list is 
"autoHilite", which looks like it might be right, but it's *close* to 
what I'm looking for, although it does state when I read through it: 
"When the button is highlighted, its hilite property is also set to 
true". Bingo!

OK... what did all of this tell me?

1) Search was the best way to go, but it took a long time to do a deep 
search, and I was lucky that the first item at the top of the list had 
my answer. 

2) The User Guide was useful, but I went down an (understandably) wrong 
path to get there. Even so, I had to extrapolate for myself that 
"hilite" was the property since it was only implicitly stated by the 
construct of the script lines and the explanation of what was going on.

3) The Glossary would seem to be a good place for getting a list of 
properties of objects and perhaps adding something simple to the root 
glossary entries for the different object types would help a lot. For 
example if "button" in the Glossary had a list of properties with a 
short one-line description of each property, and clicking the prop 
would link to the proper Dictionary page, that would be a "low hanging 
fruit" benefit to the user.

4) There definitely needs to be a faster way to get to the info, at 
least for basic things like determining what token to use to turn a 
checkbox on and off.

(Also, as a side note, the "Synonyms" for glossary items would make me 
thing I could use these in code somewhere, and of course I can't use 
button's or buttons' in script anywhere. BTW: What are the benefit of 
the Synonyms to the user?)

> A BNF of the language would be most helpful, does one exist?  Or 
> really any complete language reference.

Well, there's a BNF of HyperTalk 
(http://www.jaedworks.com/hypercard/scripts/hypertalk-bnf.html), which 
was the first xTalk language, several generations before Revolution - 
it might help in the interim. 

> Is there a message reference?  In the video about how to find 
> information, it shows (what seems to be) pre-2.8.1 documentation, and 
> just from the short clip, it looks like this documentation could help 
> somewhat (there was a short clip of a message reference too).  After 
> my open/closeStack default message passing incident,  I feel a sudden 
> need to know every message.

See my comment about the scripting conference stacks above.
 
> And just now, my variable watch window decided to not show most 
> variables.  Instead, it shows the variable names in the values. 

This happens when a variable has been used, but has not been defined to 
hold any value. This is because of Revolution's ability to coerce one 
thing into another without having to apply types to it, and sometimes 
without even providing quote marks.

For example, "put Ken into field 1" will put the string "Ken" into 
field 1 unless it has been declared as a variable with the "local" or 
"global" command, or if it has been assigned a value:

   put 10 into Ken
   put Ken into field 1

... will put 10 into field 1.

Hope this helps,

Ken Ray
Sons of Thunder Software, Inc.
Email: kray at sonsothunder.com
Web Site: http://www.sonsothunder.com/