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

[GKusnick]

Will there be a way to jump directly to menus other than Setup? So instead of a boolean gInSetupMode, you might have a string-valued gTargetMenuName that determines which menu to jump to.

[Opus4]

Originally Posted by GKusnick

Will there be a way to jump directly to menus other than Setup? So instead of a boolean gInSetupMode, you might have a string-valued gTargetMenuName that determines which menu to jump to.

Sure... the first post has been updated again.

The gInSetupMode variable has been removed; it wasn't really needed in the first place.

I changed gExitSetupWithoutConfirm to gReloadCustomSTVWithoutConfirm.

And, gTargetMenuName was added. As the first post says: "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." I decided that selecting a random menu if the specified menu name doesn't exist just wasn't a good way to handle it.

So, for setup mode, you only need to set the gCurCustomSTVFilePath variable & the other 2 are optional.

I should call it something other than "Setup Mode" now...

- Andy

[MeInMaui]

Very nice indeed.

When new menus (like online services) are added to the default STV, this could be a great way for users of custom STV's to link to those screens and immediately gain the new functionality.

How would a user return to a custom STV from any given (linked) screen?

In a related (admittedly hair brained) thought, would there be any way to preserve the menu history of the calling STV when linking to a menu in the default STV? The idea is when 'back' is hit within the default STV taking you back to the point where it was originally called (i.e when the menu history in the default STV is exhausted), it would reload the calling custom STV and its menu history. This could make the transition between STV's seamless in both directions.

Aloha,
Mike

[Opus4]

Somehow, I'm not even subscribed to my own thread...

Originally Posted by MeInMaui

How would a user return to a custom STV from any given (linked) screen?

I'm probably going to revisit my previous comment about not using Home for that purpose. I like options, so maybe I should add an option to have Home return to the custom STV (that setting may depend on how much the user is expected to do in the default STV). Between the optional-Home and optional-Comfirm settings, that should allow you to set it up any way you want.

In a related (admittedly hair brained) thought, would there be any way to preserve the menu history of the calling STV when linking to a menu in the default STV? The idea is when 'back' is hit within the default STV taking you back to the point where it was originally called (i.e when the menu history in the default STV is exhausted), it would reload the calling custom STV and its menu history. This could make the transition between STV's seamless in both directions.

Menu history is cleared when a new STV is loaded & I've never tried & even if you kept a list of the menu widgets that were in the history, it wouldn't have the cached version of the menu... at least that's the way I look at it.

To return to the original menu in the custom STV, it could set its own variable to track that & then when it gets reloaded, it could jump to that menu when the variable is set.

- Andy

[MeInMaui]

Originally Posted by Opus4

I'm probably going to revisit my previous comment about not using Home for that purpose. I like options, so maybe I should add an option to have Home return to the custom STV (that setting may depend on how much the user is expected to do in the default STV). Between the optional-Home and optional-Comfirm settings, that should allow you to set it up any way you want.

Sounds good to me.

Menu history is cleared when a new STV is loaded & I've never tried & even if you kept a list of the menu widgets that were in the history, it wouldn't have the cached version of the menu... at least that's the way I look at it.

Doh! I totally forgot about that.

To return to the original menu in the custom STV, it could set its own variable to track that & then when it gets reloaded, it could jump to that menu when the variable is set.

That makes much more sense.

Thanks!

Aloha,
Mike

[Opus4]

I have Home optionally returning to the custom STV with or w/o confirmation.

I was going to use Back to return to the custom STV when the Back history limit was reached, but there are only so many menus stored in the history. The user could go to more menus than the history can hold & then use Back enough times to hit the history limit w/o reaching the menu where everything started. I don't think I'm going to add that one unless you are really sure you want to have Back return to the custom STV.

- Andy

[Opus4]

I have updated the first post of this thread with the latest global variable info and a simple sample STV used to test this feature.

You can update your current default STV for this & other new features by testing the STV updating feature described here:
STV Update Tests for beta v6.4.3

Let me know how it goes.

- Andy

[jusjoken]

How would Themes work in the case where a Custom STV branches out to the default STV? I assume that while in the default STV function, the default STV last selected Theme would be used? Would there be any way for the Custom STV to handle this so the Custom STV could control the Themed elements from the default STV function it is calling (to try and keey a consistent look/feel for the user)?

I hope this question makes sense

[Opus4]

The default STV will use whatever theme it has been set to use. If the custom STV author wants the default UI to look similar, then there needs to be an appropriate theme that the default STV can load & it needs to be set to use that theme.

- Andy

[Opus4]

Note that v6.4.4 has a new API call: GetDefaultSTVFile(). You can use this new call to easily load the default STV w/o needing to worry about whether the file name or path for the default STV ever changes:

LoadSTVFile(GetDefaultSTVFile())

The example STV in the first post has been updated.

- Andy

[Opus4]

Based on a request from flachbar, the next version of the default STV will use new global variables gCustomSTVInit and gCustomSTVInitParams to allow calling a custom init method.

Added to the first post, above:

 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> )

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,...) )

Any comments/requests about this from other developers?

- Andy