So, a how-to for converting a working Yahoo widget to an Xwidget in order to obtain a functionally identical widget on an alternative platform. Why bother? That's a question... Well, Yahoo widgets are technically obsolete as Yahoo have withdrawn support though none of the technologies they use are actually in danger of just stopping working, it is just that coding for an obsolete platform is a little depressing. It makes more sense to code for an environment that is technically still alive.
[ The Steampunk Media Player XWidget ]
It also helped that I had previously created an Xwidget version of my media player widget that would form the basis of the conversion. My old Xwidget Media player is a fundamentally flawed widget in that it uses the in-built media player API (core) that Tony, the Xwidget developer created a few years ago now. That API is rubbish and the functionality it provides is flawed and unusable, it makes the widget unusable too. As a result I am a little bit embarassed by how bad the old widget was but at the time there was no alternative.
[ The Yahoo Widget version of the Steampunk Media Player ]
So I have bitten the bullet and determined that my old Xwidget Steampunk Media Player Widget is the basis for the conversion and that I will dump my bastardised old Xwidget code into the bin and instead combine the graphic composition of the Xwidget with the obsolete but better-functioning code from the Yahoo widget shown above.
[ Link to the Yahoo Widget Version ]
In truth I would not have started this conversion if I didn't have a semi-working Xwidget already created, with most of the hard work already done in composing the widget graphically within the Xwidget's IDE. I already have a working Yahoo media player widget and it functions really well. By the way, I run both the Xwidget and Yahoo widget engines simultaneously on all my desktops and they run perfectly well together so I don't need to create an Xwidget version for my own needs, I am perfectly happy with the yahoo widget version on my desktop. In this case my reasons for the conversion are:
a). because the xwidget already partially exists.
b). because a complete Ywidget already exists.
c). it documents the conversion process.
d). it teaches me how to convert widgets for the future.
e). it documents how some undocumented parts of Xwidget are expected to work.
f). it helps to raise bugs/issues that Xwidget currently provides.
g). it gives the steampunk media player out to a wider audience of Xwidgeteers.
h). it might stimulate others to do the same (Jim King?)
i). the Xwidget media player API is very bad and it has to be replaced
j). I am a bit of a tosspot and I like doing stuff like this
What this tutorial does prove is how difficult it would be to create a conversion tool that converted Yahoo widgets to Xwidgets automatically. You'll see that this guide turns to seven pages of description on how to convert just this one widget. I had originally determined to create such a tool but the scope would have to be broad and the logic would be complex. Instead the guide will serve as a process, when you have a widget to convert use the guide, go though it step by step and convert your widget on the fly. By the end of this guide there is a good chance you'll have a working widget. This guide does not cover all of the differences - it can't as its scope is limited to the conversion of just one media player widget, however what is in the guide will get you 85% of the way there. Good luck to you in your first conversion!
The first step was to overcome the problem of a lack of documentation. Xwidget has almost ZERO documentation, a lapse on the part of the developer that is really unforgiveable. The only way to determine how Xwidget does things is from hearsay, gossip, divination, prayer, some digging around with a spade and a bit of trial and error. The forum is of no use whatsoever as it is as dead as a doornail or a Dodo or something else that is equally dead.
When you have zero documentation the problem is doubled as you don't know what the engine actually provides and you can end up assuming it does things it really doesn't.
However, led onward by a new understanding that Xwidget uses the Microsoft Scripting Host at its core allowing the user's logic to be defined in industry-standard Jscript, while the IDE and APIs are already well-known to me, it meant that any issues could be resolved by looking at the jscript documentation provided by Microsoft and others. It also mean that activeX/COM based technologies could be used to bypass Tony's rubbish media player core as Jscript was designed to support these activeX/COM technologies. Basically, it means you can extend any functionality you need by using ActiveX/COM to extract what you need from Windows itself. This is very similar to the Yahoo widget engine that gave you access to ActiveX on Windows or alternatively Apple's actionscript to access core system functions on Mac os/x.
Why am I writing this all down in a DA journal? Well, it documents my thought processes and the steps I took to perform the conversion. I find that when I am writing something for others to read then the quality improves and the guide writes itself... Others may find this conversion guide useful as there are many Yahoo widgets out there that need converting.
[ The XWidget under development ]
The above link will take you to the widget that I am converting now. It is incomplete but every now and then I will update it. By all means download it but lower your expectations as it is still only 99% complete. There will be bugs.
Can I ask each reader a favour? If you think I have any of the following documentation incorrectly stated in any way then please give me some feedback. With programming there are always alternatives to doing anything and I'd be more than happy to hear your suggestions. I have encountered various stumbling blocks but for each I have found a workaround. For those where I have failed you may have a solution - please provide.
Unpacking the Yahoo widget
What you need to do first is to view the source Yahoo widget so you can see how it is constructed. Each widget's code is implemented uniquely accorsing to the whim of the original developer and as you know, in any language there are many methods to obtain the same result. The conversion therefore will be a lesson in understanding the original developer's code and not just a straight conversion. In order to have a look in your chosen Yahoo widget you will need to open it using the widget converter.
Most widgets you will find come packaged up, zipped, so you have to unzip them before you can open them and see the contents. The widget converter that converts widgets back and forth between zip and folder formats is available here:
When you have the widget converter installed and running on your desktop, you simply drag and drop your chosen widget to the widget converter above. It will then decompress and unpackage it for you. Assuming you have decompressed and opened your widget you'll have a widget folder and a few files within.
[ The Yahoo Widget files unpackaged ]
Composing the XWidget graphically
This will be a conversion of an existing Xwidget and as a result some steps will be missed, namely the creation and composition of the graphical widget within the IDE. Normally an Xwidget is created using the graphical components, images, text boxes, buttons, progress bars &c that can be styled within the IDE using the advanced effects provided by Xwidget. This is one of the main advantages of using the Xwidget engine. However, prior to Xwidget coming on the scene there was no dedicated IDE available for creating widgets of any type at all. All widgets were hand-crafted using any available art tool and then the widgets were composed by hand, each object that comprised the widget being described using hand-coded XML. Therefore, there is no easy conversion method that simply takes the graphical layout of an existing yahoo widget and turns it automatically into an Xwidget.
Having said that, the XML that defines the Yahoo widget is more or less compatible with Xwidget, here is an example of the yahoo widget XML and the Xwidget XML following after:
src = "playlistArea.png"
name = "playlistArea"
hOffset = "50"
vOffset = "100"
visible = "true"
onMouseEnter = "playlistAreaOnMouseEnter"
onMouseLeave = "playlistAreaOnMouseLeave"
onMouseDrag = "catchFileDrop"
It can also be expressed in one long line as follows:
<image src = "playlistArea.png" name = "playlistArea" hOffset = "50" vOffset = "100" visible = "true" onMouseEnter = "playlistAreaOnMouseEnter" onMouseLeave = "playlistAreaOnMouseLeave" onMouseDrag = "catchFileDrop"/>
The above code for each Yahoo widget resides in a .KON file that sits in the widget's root. It will have the same name as the widget itself, for example: steampunk mediaplayer.kon
The Xwidget XML always resides within main.xml and is less structured being dumped into one long line, the Yahoo widget XML is typically easier to read but as you can see, the yahoo widget XML could be inserted into the Xwidget's main.xul file with a fair certainty that it will be 90% compatible.
<image name="playlistArea" width="340" height="468" src="playlistArea.png" top="100" left="50" locked="true" onMouseEnter="playlistAreaOnMouseEnter" onMouseLeave="playlistAreaOnMouseLeave" onDragDrop="catchFileDrop" acceptFileDragDrop="true"/>
If the Yahoo widget XML is copied staright over it will be more or less correct in form if not exactly syntactically perfect. Xwidget will more or less accept Yahoo widget XML pasted directly in structured form with no problem. Some property names will need to be changed and some incompatible code will need to be removed - but do note: one syntax error will stop the Xwidget IDE loading at all. If you are happy with coding XML and using text editors then it can be done this way but it might be a hard slog if your widget is complex.
However, this is doing it the hard way and it is not necessary. If you aren't a code slogger then you may prefer to use the Xwidget IDE and merge your code this way. Reading the rest of this conversion guide will show you what needs to be changed within the Yahoo widget XML file in order to shoehorn your yahoo widget into the Xwidget IDE. I suspect however that very few Xwidgeteers will want to do the conversion this way. If you are unhappy with hand-crafting XML I imagine that you will simply use the Xwidget IDE in design mode to re-compose the widget using the original Yahoo widget's parts merely as the new Xwidget's components. Assuming that you will be composing your Xwidget in this manner means that both you and I will be starting out from the same point. Let's assume we have an Xwidget composed graphically composed within the IDE.
[ The XWidget IDE in Design mode showing the widget already composed]
One thing to note is that all the components must have exactly the same names as the yahoo widget version, uppercase and lowercase elements must be identical in all respects. This will make life much easier later. Also, make sure that Xwidget positioning and sizing is identical, look at the hoffsets and voffsets in the Yahoo widget XML to be certain of this. Some characteristics may be undefined in the Yahoo widget version, such as width and height, they are assumed and by default they are the image's actual size.
Something to note: Most of the Yahoo widget images will reside in the Resources folder, simply grab them from there and paste them into your own Xwidget project folder. You may feel the need to group your objects into 'layers' - that is fine. Layers as a concept transpose directly to the YW engine as 'frames'. As long as the image objects retain exactly the same names then the conversion will not be affected.
Note - when you move objects to a layer, make sure the layer is sized correctly first as your image objects will all be bunched together on an incorrectly sized layer.
PS. If you design your widgets in Photoshop you may want to have a look at this tool, it is a script for Photoshop that creates Xwidgets on the fly from your Photoshop design. If all the layers within the PSD file are named correctly it will do the graphic composition of your Xwidget for you automatically.
[ Link to the Photoshop script to create Xwidgets ]
Stripping out the old XWidget
So, the conversion started.
You won't need to do any of this next bit in a straight Yahoo to Xwidget conversion but I'll document it here as it is part of the particular conversion that I was undertaking. I'm taking parts from two widgets to make one new one.
First of all I took my old media player Xwidget and using the Xwidget IDE in code mode, I stripped out all the old code. Easily done by selecting the code window and CTRL+A then delete! Gone.
The next task was then to remove the nasty media player core from the widget. As you build widgets, if you require additional functionality you drop ready-made cores onto your widget, each giving you access to certain system functions. Conversely, to remove an unwanted core you simply open the IDE in design mode, find the cores at the bottom, right click on each core you want to remove, in this case the media player core - and remove it from your widget.
A multitude of controls will be bound to that now-missing core. You need to look at each image object in turn, and look to see which are bound to the core, each will have to be unbound by assigning no core and removing any tags that operated the core. Both fields should be empty. When done, the widget will have no logic and exist purely as a graphical entity that can run - but do nothing at all.
[ The XWidget binding core dropdown ]
Part 2 is here
Guide to converting Yahoo Widgets to Xwidget Pt2Part II of the guide to converting a Yahoo widget to a Xwidget, this guide follows on from Part I which can be found here:
Next step was to pull the code from the Yahoo widget, that was easy enough to do. I use a coder's editor called Context which runs on all flavours of Windows, it is my favourite platform for coding and I have tried a few. Context is a powerful editor which just works with no complications. It doesn't try to be an IDE nor a word processor. During the conversion process I have the context editor open with multiple tabs showing all of my Yahoo widget code, while the Xwidget IDE is open in another adjacent window. It really helps if you have a big screen or even two screens side by side.
[ The Context editor opening files in tabs ]