Using the default STV in Custom STV Mode from custom STVs (v6.4 & later)

[Opus4]

Version 6.4 of the default STV has a Custom STV Mode that custom STVs can use for configuration options, such as setting up recording sources, or for use of any other menu in the default STV. This makes sure that users are always using the most up to date setup code and the custom STV authors do not need to worry about that code at all.

I believe SageMC does something like that already, but it provides a customized version of the default STV which could get out of date since the default STV's setup code gets modified often.

To use the default STV in Custom STV Mode, a custom STV would set these global variables:

AddGlobalContext("gCurCustomSTVFilePath", GetCurrentSTVFile())

 Optional variable to reload the custom STV w/o confirmation,
 set to true or false, default false:
AddGlobalContext("gReloadCustomSTVWithoutConfirm", true)

 Optional variable to set name of menu to jump to, default null:
AddGlobalContext("gTargetMenuName", "<name of menu widget>")

 Optional variable to use the Home command to return to the custom STV,
 set to true or false, default false:
AddGlobalContext("gReloadCustomSTVOnHome", true)

 Optional variables used to call a custom init method - set gCustomSTVInit
 to the name of the method to call and gCustomSTVInitParams are the
 parameters:
AddGlobalContext("gCustomSTVInit", <name of method to call> )
AddGlobalContext("gCustomSTVInitParams", <parameters> )

 Use the GetDefaultSTVFile() API call to load the default STV:
LoadSTVFile(GetDefaultSTVFile())

 Optional variable to reload the custom STV after entering 
 the playback menu, set to true or false, default false:
AddGlobalContext("gReloadCustomSTVOnPlayback", true)

Then, it would just load the default STV via the LoadSTVFile() API call. The default STV will initially jump directly to the Setup Menu, where the user can then use any configuration options. Once done using setup, the user can choose the "Exit Setup Mode" button at the bottom of the Setup Menu or Main Menu to return to the custom STV file that was defined in the code shown above.

If gReloadCustomSTVWithoutConfirm has been set to true, then the custom STV is reloaded w/o asking the user to confirm that step.

If gTargetMenuName has been set, then the default STV will attempt to jump directly to the menu widget with the specified name. If the name doesn't exist, then the Main Menu will be used. If this variable is null, the Setup Menu will be loaded.

If gReloadCustomSTVOnHome has been set to true, then the default STV will reload the custom STV when the Home command is used. Use the gReloadCustomSTVWithoutConfirm variable to control whether the action is confirmed or not.

If gReloadCustomSTVOnPlayback has been set to true, then the default STV will reload the custom STV after entering the playback menu.

If gCustomSTVInit has been set to the name of a method to call, then this function is called after the default STV has been loaded and its initial settings are configured -- it gets called as one of the last things to be done in the Main Menu's AfterMenuLoad hook, but before the jump to another menu. gCustomSTVInitParams is sent as the array of parameters. This is done via a call to:
sage_SageTV_apiUI( GetUIContextName(), gCustomSTVInit, gCustomSTVInitParams )

Custom Java code:
package CustomCode;

public class CustomInit {
   public static void initialize(String arg1, String arg2) throws InvocationTargetException {
        [...]
    }
}

Custom STV:
AddGlobalContext("gCustomSTVInit", "CustomCode_CustomInit_initialize" )
AddGlobalContext("gCustomSTVInitParams", CreateArray(param1,param2,...) )

Note: These global variables are cleared before reloading the custom STV. If the custom STV needs to do anything specific when it is reloaded, it should set its own custom global variables before loading the default STV.


I'm looking for comments from custom STV authors regarding anything else they think would be needed.

Nothing else jumps out at me and I don't think the default STV needs to look for or set any other global variables to talk to the custom STV, because the custom STV could set those before loading the default STV so it knows Custom STV Mode was just exited when it gets reloaded.

See the attached STV for sample code used to test jumping between the default & sample STV.

- Andy

[dflachbart]

Originally Posted by Opus4

I'm looking for comments from custom STV authors regarding anything else they think would be needed.

One thing less to worry about. Awesome...


Dirk

[Opus4]

Originally Posted by flachbar

One thing less to worry about. Awesome...

I figured you would like that one. And, it was really easy to implement.

Are you doing anything else in your customized default STV?

Have you run into usability issues that should be considered? ... it doesn't seem too difficult to me: when done, choose "Exit Setup Mode" and confirm.

- Andy

[MeInMaui]

One other feature is that 'Back' and 'Home' both return you to SageMC.

[mightyt]

Not an author, but this sounds awesome. If I am reading this right it will give us a way to keep the original STV "pure" and independent, not have to worry about SageTV3-2, then 3-3, 3-4, etc. Is this true?

[GKusnick]

I've been doing something like this in my own (unreleased) custom STV for some time. In my case I use more than just the Setup menu; I also have menu items that jump into the stock Video Browser and Music Browser screens (since I didn't feel like duplicating that functionality in my STV).

Basically what my code does is this:

1. Remember the name of the currently loaded STV.
2. Load the target STV.
3. Set the STV property in the properties file to the calling STV (so if the user quits and restarts Sage, that's the one that will be loaded).
4. Search for the Standby item on the Main Menu in the target STV.
5. Replace it with a "Return to caller" menu item that reloads the original STV.
6. Jump to the target menu by name.

The interesting thing is that steps 3-6 continue to execute even after the target STV has been loaded, even though the code for those steps is defined in the STV that has just been unloaded. I guess we have Java garbage collection to thank for that.

[Opus4]

Originally Posted by MeInMaui

One other feature is that 'Back' and 'Home' both return you to SageMC.

I don't think I want to do that because I didn't want to limit UI navigation too much -- the user would be free to check out settings on other menus & so on and still easily switch back to the custom STV from the Main Menu or Setup Menu.

Originally Posted by mightyt

Not an author, but this sounds awesome. If I am reading this right it will give us a way to keep the original STV "pure" and independent, not have to worry about SageTV3-2, then 3-3, 3-4, etc. Is this true?

This is different. The default STV already doesn't get modified when you import a customization; that's why there are those -# STV versions created. What I'm talking about has to do with replacement custom STVs needing access to up-to-date configuration options, not the modified-by-imports default STVs, because the modified ones still have the setup code from the default STV.

Originally Posted by GKusnick

I've been doing something like this in my own (unreleased) custom STV for some time. ...

3. Set the STV property in the properties file to the calling STV (so if the user quits and restarts Sage, that's the one that will be loaded).

That's an interesting one that I hadn't thought of. I think I'll add that. There's already an option to exit setup mode and NOT return to the calling STV, so if the user selects that option, I can simply reset the STV property back to the default STV.

- Andy

[Opus4]

Originally Posted by GKusnick

The interesting thing is that steps 3-6 continue to execute even after the target STV has been loaded, even though the code for those steps is defined in the STV that has just been unloaded. I guess we have Java garbage collection to thank for that.

BTW: it is sort of garbage collection related -- the code is released when no more active threads reference those widgets any more.

The same thing applies to any forked threads -- they will continue until they hit an exit point... I think I have one to double check for stopping itself when the STV changes.

- Andy

[Opus4]

Originally Posted by GKusnick

3. Set the STV property in the properties file to the calling STV (so if the user quits and restarts Sage, that's the one that will be loaded).

5. Replace it with a "Return to caller" menu item that reloads the original STV.

Updates:

I've now set the STV property as you mentioned.

I also added a check for an optional variable named "gExitSetupWithoutConfirm", which will change the exit button so that when selected, the user immediately returns to the custom STV instead of being asked whether to return. (First post has been modified.)

- Andy