"proof-of-concept" Revolution Online Open Dictionary at revcoders.org

[Ken Ray]

On Thu, 1 Nov 2007 01:09:46 -0700, Josh Mellicker wrote:

> Good example!
> 
> I posted a code snippet to do this here:
> 
> http://revcoders.org/vScroll/#comment-32
> 
> Of course, presently, you would have to know to look under 
> "vscroll"... so I am working on a much better search page.
> 
> For someone new to Revolution, the best thing is not reading the term 
> dictionary, but a step-by-step tutorial that introduces the student 
> to Revolution and the foundations of RAD, then guides them through 
> the creation of a complete project, hands-on. Richard's idea of 
> building a word processor is a good one, it covers many commonly used 
> functions.
> 
> The open dictionary is not for learning Revolution, it is for 
> reference on specific terms for someone who has been through the 
> basic tutorials and just needs examples of how to accomplish common 
> tasks.

Sorry to dissent here, Josh, but I think there's a middle-point that's 
not being addressed. You'r correct that someone who is new to Rev needs 
tutorials to walk them through. But I think the "dictionary only" 
approach addresses someone who is very familiar with the language, but 
can't recall the syntax of a particular command, or like "I know 
there's a property for buttons that does ___ but I don't know what it's 
called". 

The "gap" between the two is addressed by the Lexical and Procedural 
indices to the Dictionary - it allows everyone (especially those from 
the "newbie" through "almost intermediate" stages) to locate the 
particular commands/functions/etc. for the task or object that they 
want to work with by looking up synonyms to the tasks/etc. they want to 
accomplish and get redirected back to the actual language to get the 
job done.

Combine this with a handful of short, useful, *applicable* examples for 
each entry (whether initially provided or eventually provided by the 
community), and people can cruise right along without frustration.

For example, suppose someone wants to implement a contextual menu on an 
object. They should be able to look up "right-click", "control-click", 
"contextual menu", "menu", etc. and have them all point back to the 
"popup" command. The the popup command Dictionary entry would have an 
example that shows how to use a contextual popup menu  (which is the 
primary reason for the popup command), including what object(s) need to 
be created, and script(s) are needed, and that (hopefully) could be 
copied and pasted into their code if they want to try it out. 

Something similar to the current docs on the 'popup' command, but 
perhaps more explanatory, like:
-------
You can use the mouse button parameter of the 'mouseDown' message to 
specify that a contextual menu (the menu that is displayed when the 
user right-clicks (on Unix, Windows, or Mac OS/OS X systems), or 
Control-clicks (Mac OS/OS X systems)) should appear.

Example: Displaying a Contextual Menu For a Field
     Scenario: You have a field that has text in it, and you'd like to 
display a menu with "Cut", "Copy", and "Paste" options that is based on 
whether the user has any text selected. This example assumes that the 
field that will display the contextual menu already exists, and that it 
is unlocked (the "Lock text" checkbox in then Inspector is unchecked).
     Approach: (1) Create a popup menu button that will contain the 
menu items for selection and hide it so the user doesn't see it; (2) 
script it so that it will perform the correct actions when a menu item 
is selected; (3) call it from the field using the 'popup' command.
     
     Step 1) Create a popup menu button, and set the following 
properties:
                     Name: EditPop
                     Menu Items: Cut, Copy, Paste (each on its own line)
                     Visible: Unchecked
                     TraversalOn*: False

     Step 2) Set the script of the popup button as follows:

                     on menuPick pChoice
                        switch pChoice
                        case "Cut"
                           cut
                           break
                        case "Copy"
                           copy
                           break
                        case "Paste"
                           paste
                           break
                        end switch
                     end menuPick

     Step 3) Set the script of the field as follows:

                    on mouseDown pButton
                       -- pButton is "3" if the user 
right/control-clicks
                       if pButton is 3 then
                          popup button "EditPop"
                       else
                          -- allow the message to pass
                          pass mouseDown
                       end if
                    end mouseDown

     * In order to display a contextual menu in an unlocked field and 
still maintain the current text selection, you need to make sure that 
the 'traversalOn' property (displayed as "Focusable" on the Inspector 
palette) of the popup menu button is set to 'false'. This is because 
when a button is activated with the 'traversalOn' property set to 
'true', the focus is "stolen" from the object that currently has the 
focus, which would remove the insertion point or any text selection you 
had in the field.
        Currently the Inspector palette does not show "Focusable" as a 
settable property for popup menu buttons (although it's displayed for 
other kinds of buttons), so you will need to do this by using the 
Message Box: Choose "Message Box" from the Tools menu, and type the 
following line of script in the main (top) field and execute it by 
hitting the Enter key:
 
                   set the traversalOn of button "EditPop" to false

      What Happens: 
           When you 'mouseDown' on the field, the contextual menu 
("EditPop") will appear. When you select from that menu, the "EditPop" 
popup button is sent a 'menuPick' message along with the name of the 
menu item you selected. The popup button's script then handles what to 
do based on the selected menu item. 

       Special Considerations: 
            You will most likely need to adjust which items or enabled 
or disabled in the contextual menu based on the current situation (for 
example, you don't want to show "Cut" and "Copy" enabled if there is no 
current text selection, nor do you want to show "Paste" enabled if 
there is no text on the clipboard). A good time to do that is just 
before you execute the 'popup' command. For more on enabling/disabling 
menu items in a popup menu, see the entries for 'disable menu' and 
'enable menu'.
            
         
-------

Of course this is only a proposed section of the full entry (there 
would be the caveats on setting the menuMouseButton, info on using 
'popup' with stacks, syntax, etc.), but you get the idea. I know this 
seems like a lot of description, and that veteran users will not get as 
much (or any) benefit out of the explanations, but it is a *goldmine* 
to anyone who's on the learning curve to Revolution. It gives them 
something concrete to play with, explains why everything works the way 
it does (to eliminate mystery), points them to other related tokens, 
and IMHO gives them a sense of comfort and not trepidation about 
learning the language.

Just my 2 cents (of course),

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