Utility functions to simplify STV import

[dflachbart]

Hi everyone,

I don't know if this is true for everyone, but since I started Studio development and writing my own plugins I soon discovered that certain tasks are always tedious and time consuming. To make my life easier I started to factor out certain functionality into java code which has grown to a java library over time. E.g., I found that a quite common task is to find an existing widget in the current STV which one will link to or modify. If it's a theme or a menu this is still relatively easy by using studio widgets (provided the name is unique), but to find arbitray nodes walking through the tree using widget code is quite cumbersome. A function in the library which takes a path to the widget makes this rather pretty easy:

e.g. to get a reference to the 'TV Details' panel of the OSD menu you can simply write

panel = df_sageutils_Import_findExistingWidget("MediaPlayer OSD/DisplayInfo/DetailedInfo/mf = GetCurrentMediaFile()/IsTVFile(mf)/true/TV Details")


The path parameter consists of the names of all widgets along the path. If there is no ambiguity, you can use wildcards to save typing:

panel = df_sageutils_Import_findExistingWidget("MediaPlayer OSD/Disp*/Detail*/mf =*/IsTV*/true/TV Details")


You can even omit the intermediate path altogether (but not recommended for large subtrees which go into breadth instead of depth) :

panel = df_sageutils_Import_findExistingWidget("MediaPlayer OSD//TV Details")


This function alone saves me a lot of time compared to coding the same with Studio widgets. The library also contains a bunch of other useful functions like automatic linking of imported widgets (e.g. themes) to existing ones, a tree deletion routine which can handle loops and does not leave any orphaned nodes behind, or simple one-line calls to retrieve existing/imported menus, hooks, and themes by name.


Just wanted to throw this out here in case anyone would be interested to use it. I haven't written any documentation yet, but I could generate some javadoc if there is demand for that.

Dirk

[BobPhoenix]

Sound real good to me. I had to walk down 8 levels in my plugin for SageMC because that was the only unique widget available and I needed to apply a change there.

BobP.

[dflachbart]

Well, if someone is interested, I uploaded the library including javadoc and template STVi to the Download section.

Dirk

[BobPhoenix]

Thank you will try this out in a few days.

BobP.

[BobPhoenix]

OK have one question for you on this.

How does deleteWidgetTree handle code in other menus that the imported menu may be linked too? In otherwords does it stop the deletion when it gets to the link or should we unlink this prior to calling your deleteWidgetTree routine?

BobP.

[dflachbart]

Originally Posted by BobPhoenix

OK have one question for you on this.

How does deleteWidgetTree handle code in other menus that the imported menu may be linked too? In otherwords does it stop the deletion when it gets to the link or should we unlink this prior to calling your deleteWidgetTree routine?

BobP.

Hi Bob,

as long as you link your code to existing widgets by using the df_sageutils_Import_defineLink() method, this get's handled automatically, you don't have to perform any manual unlinking prior to deleting trees. When the deleteWidgetTree() method encounters a link to existing code, it will stop deletion at this point and simply unlink the widget.

Feel free to post any other questions you might have.

Dirk

[alon24]

Sounds great, I will try it today!

[BobPhoenix]

Originally Posted by flachbar

Hi Bob,

as long as you link your code to existing widgets by using the df_sageutils_Import_defineLink() method, this get's handled automatically, you don't have to perform any manual unlinking prior to deleting trees. When the deleteWidgetTree() method encounters a link to existing code, it will stop deletion at this point and simply unlink the widget.

Feel free to post any other questions you might have.

Dirk

OK still not understanding so will give a more complete example below. I have a menu that I added to the STV that I want to delete for an update. I wont be updating the internal code because it is easier just to import a new version delete the old version. My problem is with deleting the existing menu because it links to other code that I do not want to delete.

ResultsTable (table widget)
+-Airing (table component widget)
   +-Untitled (item widget)
      +-Right (listener widget)
      +-Info (listener widget)
      +-MouseClick (listener widget)
      +-"REM Selected item, so show options for it" (linked action widget don't want to delete this)

What will happen if I call deleteWidgetTree on a menu with this code snippet in it. Will it stop at the "REM..." or will it continue on. How would you handle a situation like this where you want everything deleted in the menu but you just want some of them unlinked rather than deleted. I can see how I would link the new code to this with df_sageutils_Import_defineLink() but what about the existing code from a prior import.

Sorry still a little confused.

BobP.

[dflachbart]

Hi Bob,

Originally Posted by BobPhoenix

What will happen if I call deleteWidgetTree on a menu with this code snippet in it. Will it stop at the "REM..." or will it continue on. How would you handle a situation like this where you want everything deleted in the menu but you just want some of them unlinked rather than deleted. I can see how I would link the new code to this with df_sageutils_Import_defineLink() but what about the existing code from a prior import.

Ahh ok, now I see what you mean. Let's look at this that way:

If you had used my library from the beginning, you would have coded it like this:

My Menu
+...
+-ResultsTable (table widget)
  +-Airing (table component widget)
     +-Untitled (item widget)
        +-Right (listener widget)
        +-Info (listener widget)
        +-MouseClick (listener widget)
        +-LinkToREMSelectedItem  <- dummy widget
        
df_sageutils_Import_defineLink("LinkToREMSelectedItem", PATH_TO_EXISTING_REM_WIDGET)

// delete old existing version
myMenu = df_sageutils_Import_getExistingMenu("My Menu")
df_sageutils_Import_deleteWidgetTree(myMenu)

Now - when you call deleteWidgetTree(myMenu) in your update code to delete the old version, the deletion code automatically knows (because you have called 'defineLink()' before) that the REM widget is part of other code that you have linked to, and will *not* continue deletion, but instead unlink the widget, before continuing the deletion on your New Menu.

The nice thing is that this will also work for the existing code of your plugin that is currently out there. Since you have marked the widget located at PATH_TO_EXISTING_REM_WIDGET as a linked widget (by having called 'defineLink()' before), the deletion code will unlink instead of deleting it.

So the point is that 'defineLink()' serves two purposes:

1) to locate both widgets and perform the actual linking for you
2) to mark the widget the path points to as "linked code", which will not be touched by deleteWidgetTree()


If you cant use this automatic mechanism for any reason, you can always unlink any widgets manually before deleting the tree (which is equivalent):

myWidget = df_sageutils_Import_getExistingWidget("New Menu/.../ResultsTable*/Airing*/Untitled*")
linkedWidget = df_sageutils_Import_getExistingWidget(PATH_TO_EXISTING_REM_WIDGET)
RemoveWidgetChild(myWidget, linkedWidget)

myMenu = df_sageutils_Import_getExistingMenu(My Menu")
df_sageutils_Import_deleteWidgetTree(myMenu)

You see that using defineLink() will do a lot of the work for you ...


Hope this is a little bit more clear now (I know I'm not that great at explaining things), but dont hesitate to ask more questions if you need to. Also have a look at any of my other plugins as an example for the update/deletion code.

Dirk

[BobPhoenix]

That's what I thought. And the code I was thinking of is actually code in the STV by default so no possiblity that it was used before. I just used the example above because it was the easiest one I could find. You explained it fine I just needed to define it better. Still think this will work out better just need to code the unlink points and unlink them manually before I delete a tree.

Thanks.
BobP.

[alon24]

I would add 2 functions:
1. find the location of a widget within a specific parent.
so that if I have:
parent->
child1
child2

and i want to know where to link my code (after child2) and I found child2 and know its the widget, so something like getLocationInParent(widget, parent)

2. a simple debug loop to print the children of a widget:
printChildren(widget), for making sure we select the correct widget (debugging mainly)

[alon24]

Another Idea releated to the ones from before.
1. What about Link at position
2. What about Link After, so that I tell it to link after a widget on its parent
Parent->
widget1
widget2
widget3

LinkAfter (parent, widget2, newWidget)
so now we have
Parent->
widget1
widget2
newWidget
widget3

Edit:
why not LinkAfter ("parentName", widget2, newWidget)

no need to find both the parent widget and the child if u know the child and the parent name.

why not also have findParentByName("parentName", childWidget)

It seems like I am adding a big grocery list here.

Sorry about that.

[dflachbart]

Originally Posted by alon24

I would add 2 functions:
1. find the location of a widget within a specific parent.
so that if I have:
parent->
child1
child2

and i want to know where to link my code (after child2) and I found child2 and know its the widget, so something like getLocationInParent(widget, parent)

So this method should return the index of the child ?

Originally Posted by alon24

2. a simple debug loop to print the children of a widget:
printChildren(widget), for making sure we select the correct widget (debugging mainly)

Good idea, certainly possible ..


Dirk

[alon24]

So this method should return the index of the child ?

Yes sure.
This is a prelude to the next suggestion, which is linkAfter and LinkAfter+delta.

Also another idea is:

findParent(widget,"String parent name, or path starting from widget and going up)

parent1
--subParent1
-----widget1
parent2
--parent3
----subParent2
-------widget1

if I want to find parent3 all I have to do is:
parent=findParent(widget1,"parent3/subParent2")

because the path is from the widget and up)

These are just some examples, and I think It would make an incredible toolkit, because there is a lot of ideas that run through my head, and this is only my first STVI...

[koelec]

Originally Posted by flachbar

Well, if someone is interested, I uploaded the library including javadoc and template STVi to the Download section.

Dirk

Thanks Dirk,
This is exactly what I need. I was having problems with updating the web radio plugin, removing old widget chains and also enabling reimporting the same version. I coudn't get it working correctly.
This code really makes creating STVi's easier.

thanks again,
- Chris

[dflachbart]

Originally Posted by koelec

Thanks Dirk,
This is exactly what I need. I was having problems with updating the web radio plugin, removing old widget chains and also enabling reimporting the same version. I coudn't get it working correctly.
This code really makes creating STVi's easier.

thanks again,
- Chris

Hi Chris,

nice to see that this is useful for someone else.

Especially when it helps further development of the webradio plugin, which is absolutely great, and one of my favorite plugins.
I wanna thank you for that...


Dirk

[koelec]

Originally Posted by flachbar

Hi Chris,

nice to see that this is useful for someone else.

Especially when it helps further development of the webradio plugin, which is absolutely great, and one of my favorite plugins.
I wanna thank you for that...


Dirk

Dirk,
the linkWidget method seems to stop after the first found placeholder. Is it true that when I have multiple Widget references to the same existing widget, I have to create a separate define link for each one of them?
thanks,
-Chris

[dflachbart]

Originally Posted by koelec

Dirk,
the linkWidget method seems to stop after the first found placeholder. Is it true that when I have multiple Widget references to the same existing widget, I have to create a separate define link for each one of them?
thanks,
-Chris

Hi Chris,

well you just discovered a bug, I checked the code and it does indeed only link one widget. I will try to fix this asap, for now as a workaround you can define separate links for each dummy widget (but name them differently, e.g. LinkToMainMenuTheme1, LinkToMainMenuTheme2, etc)

Thanks for the QA,

Dirk

[dflachbart]

Originally Posted by koelec

Dirk,
the linkWidget method seems to stop after the first found placeholder. Is it true that when I have multiple Widget references to the same existing widget, I have to create a separate define link for each one of them?
thanks,
-Chris

Chris,

support for this has been added in v1.3

Dirk

[dflachbart]

I uploaded version 1.3, download it here

Changes in v1.3:

- defineLink() can now handle multiple widgets with the same name
- added the following utility functions:

void print(Object widget):
prints the widget name and type to the debug log

void printChildren(Object parent):
prints the all children to the debug log

void printParents(Object child):
prints the all parents to the debug log

int getPositionInParent(Object parent, Object child):
returns the index of a child widget within its parent

void linkChild(Object parent, Object child):
links a widget to another (equivalent to 'AddWidgetChild()', for sake of completeness)

void linkChildAtPosition(Object parent, Object child, int pos):
links a widget to another at a certain position (equivalent to 'InsertWidgetChild()', for sake of completeness)

void linkChildBefore(String parentName, Object newChild, Object existingChild):
links a widget to another at the position before a specific existing child widget

void linkChildAfter(String parentName, Object newChild, Object existingChild):
links a widget to another at the position after a specific existing child widget


Note that the new 'link' functions are for general purpose linking, they do not affect the automatic linking performed by 'defineLink()', and thus will not automatically get unlinked on 'deleteWidgetTree()'

Dirk