[chippyash]

As some will be aware, I'm developing an addon developers guide to xbmx. I'm coming at it from the stance of a complete Python/Xbmc noob.

you can find the thread and a link to the fledgling doc here http://forum.xbmc.org/showthread.php?tid=68337

The first example script I'm writing is as follows

Code:

# Step 1 - load in xbmc core support and setup the environment
import xbmcplugin
import sys

# magic; id of this plugin - cast to integer
thisPlugin = int(sys.argv[1])

# Step 2 - create the support functions (or classes)

def createListing():
    """
    Creates a listing that XBMC can display as a directory listing

    @return list
    """
    listing = []
    listing.append('The first item')
    listing.append('The second item')
    listing.append('The third item')
    listing.append('The fourth item')
    return listing


def sendToXbmc(listing):
    """
    Sends a listing to XBMC for display as a directory listing
    Plugins always result in a listing

    @param list listing
    @return void
    """
    #access global plugin id
    global thisPlugin

    # send each item to xbmc
    for item in listing:
        xbmcplugin.addDirectoryItem(thisPlugin,'',item)

    # tell xbmc we have finished creating the directory listing
    xbmcplugin.endOfDirectory(thisPlugin))

# Step 3 - run the program
sendToXbmc(createListing())

But the line
xbmcplugin.addDirectoryItem(thisPlugin,'',item)

fails. debug error is
xbmcplugin.addDirectoryItem(thisPlugin,'',item)
SystemError: error return without exception set

I'd appreciate any pointers as to why - as the obviously the error message is about as useful as a fart.

Like I said, that is my first bit of Python scripting ever, so no funny jokes please :-)

[BlueCop]

The python docs are alot more useful then a fart.

You need to create a listitem with xbmcgui.ListItem() to use with addDirectoryItem()

[chippyash]

The python docs are alot more useful then a fart.

Nearly a good joke

OK, I was reading xbmcaddon python docs for xbmcaddons;
addDirectoryItem(handle, url, listitem [,isFolder, totalItems]) -- Callback function to pass directory contents back to XBMC.

It's not clear from that, that you need to create xbmcgui.ListItem() for use in the method call. I'll have another go 2morrow. Thanks for the info

[jmarshall]

Also, int(sys.argv[1]) actually gives the handle of the plugin instance - the same plugin might be running twice, so this handle acts as the go-between to ensure we are adding items to the correct plugin folder and so on.

And please let us know how we could rewrite the docs even at the function level like this - eg in this case we could perhaps add that the listitem should be constructed from xbmcgui.ListItem().

Cheers,
Jonathan

[chippyash]

eg in this case we could perhaps add that the listitem should be constructed from xbmcgui.ListItem().

You took the words right out of my mouth JM!

perhaps a sweep through python docs might be in order to prevent these sorts of gotchas in future . The API doc for getItem should read

Code:

addDirectoryItem(handle, url, listitem [,isFolder, totalItems]) -- Callback function to pass directory contents back to XBMC.
- Returns a bool for successful completion.

handle      : integer - handle the plugin was started with.
url         : string - url of the entry. would be plugin:// for another virtual directory
listitem    : [color=red]xbmcgui.ListItem[/color] - item to add.
isFolder    : [opt] bool - True=folder / False=not a folder(default).
totalItems  : [opt] integer - total number of items that will be passed.(used for progressbar)

Then the example should show usage of method to display listing of a number of different media types and the use of the url to run another plugin.

Also, is the use of the term "Callback function" correct? In my world (PHP these days, but started in 6502 assembler), a callback function is something that is provided to another class/method so it can call back to the calling pattern, not as here, something that is called directly itself

The better the docs, the less support that is needed

[jmarshall]

Thanks - yes, agreed that the better the docs the less support is needed

What were you suggesting in terms of the example usage? Perhaps a simple case where we add 4 items:

1. A directory item in the plugin.
2. A playable media item that XBMC can use directly.
3. A playable media item that calls into the plugin prior to playback (to resolve the play path etc.)
4. A non-playable item that runs the plugin to perform some other function (eg throw up a settings dialog or some such.)

That should make things clearer I think?

Any volunteers to do up a quick test script that can be verified working? Once done, I'll add the docs.

Cheers,
Jonathan

[chippyash]

Thats about right Jonathan. At the end of the day, the more examples you can give, the better the documentation. Then in my document I can really say RTFM!

Cheers
Ashley

[chippyash]

for completeness of this thread;

Code:

for item in listing:
        listItem = xbmcgui.ListItem(item)
        xbmcplugin.addDirectoryItem(thisPlugin,'',listItem)

is what is required to make this script work correctly.

[chippyash]

Just a quick thought; Is the style of commenting I am using correct? If not, can you point me at the resource that tells me how to do it the XBMC/Python way. Thanks.