Creating Simple STVi

[Slugger]

I've read through the sticky talking about how to create an STVi, but after a few reads I'm still not getting it.

What I've done is modified the "Detailed Setup" menu by adding a new option in the left list to allow configuration of my SRE plugin.

The modified STV functions as desired and now I am trying to create an STVi. Will I need to write some kind of STVImported hook or can I just export the modified menu and import it into the base (unmodified) STV?

[GKusnick]

The Import command doesn't have any smart merge capability built in. It just loads the menu definitions from the STVI file as new menus in the target STV. So by exporting a modified menu and then importing it into the stock STV, you'd end up with two versions of the same menu (the original, unmodified version plus the imported, modified version), but only one of them (the original) would be linked up to the other existing menus. The new one would basically be inaccessible deadwood in the STV.

You don't really want to be exporting the entire menu anyway, since that would basically freeze a snapshot of that menu into your code, which you'd then have to keep updating every time the standard STV changes. What you'd really rather do is export just your new code, without any excess baggage from the stock STV, and then have a way of splicing your code back into the stock menu at import time. That's what the STVImported hook is for.

The old-school way of creating an STVI is to put your new code under a dummy menu without actually connecting it up to an existing menu. Then you write a complicated script under STVImported that uses WidgetAPI calls to search the existing widget tree for the connection points and insert the appropriate links to your new code. That's what the sticky thread describes and it's an extremely laborious and error-prone way to do it.

It always seemed to me that there ought to be a more automatic way of converting a modified STV into a working STVI, so I've provided some tools for doing that in the STVI plugin in my Studio Tools package. The approach here is to do basically what you've done, i.e. start by modifying the stock STV, and then rearrange the code using Set As Primary Reference so that all your new code is under a dummy menu, and all the pre-existing code is somewhere else, but with the connections between them still intact. The tools then let you export just your code, automatically encoding links into and out of your code in a way that can be automatically looked up and relinked at import time. So most of the work of creating the STVImported script is automated. There may still be a few cases where you need to remove, rename, or change properties on existing widgets, but there are functions for doing those things in relatively straightforward fashion, using widget path strings (similar to directory paths) to identify the target widgets.

This is all explained in somewhat greater depth, including step-by-step instructions, in the Javadocs that come with my Studio Tools.

[Slugger]

Ok, I've read through your javadocs and the idea seems simple, but I get stuck right away. I understand why we want to contain our changes into placeholder menus, but I'm not sure how to do it in some cases.

For example, the first thing I want to do to add to the Detailed Setup menu is edit the following from the default STV:

Detailed Setup
|
 -- Menu Container
     |
      -- Setup Areas
          |
           -- If GetFocusArea()
               |
                -- false
                    |
                     -- If CurSetupArea
                         |
                          --...

I want to add another branch widget there for the menu I'm adding. So instead I tried to create a new placeholder menu that I would then reference in this menu. However, branch widgets can't be direct children of menu widgets, which makes sense. So now I'm stuck at figuring out what I should be doing instead to allow me to make use of your Export STVi option.

[GKusnick]

Remember that the placeholder menu doesn't have to function as a menu; it's just a vehicle for exporting and importing widget code. So you're free to put any scaffolding you like in there to support your actual code. If you need a dummy If widget beneath your dummy Menu widget to contain your (non-dummy) Branch widget, by all means create one. That If will never get executed (nor will the dummy menu it's under) because the control flow to the Branch will come in from elsewhere, once ProcessImport has hooked everything back up.

So in your case you'd be looking at something like this:

(Menu) Placeholder
    (If) "dummy"
        (Branch) "MyCase"
            ...

(Menu) Target menu
    ...
        (If) CaseVar
            ...
            (Branch) "MyCase"

You can also look at some of my STVIs in the Downloads section for working examples of this sort of thing.