/* This file is part of the KDE project

   Copyright (C) 2008 Ningyu Shi <shiningyu@gmail.com>

   This program is free software; you can redistribute it and/or
   modify it under the terms of the GNU General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.
*/

This file describes how to write a script using the kross interface from
the content fetch plugin.

== API ==

=== Functions ===
Script developer must implement certain functions in the
script to be called by the content fetch plugin.

* startDownload(config) (MUST implement)
  config: SciptConfigAdaptor type
  Descrption:
    KGet will call this function when it gets the url from the user
    input and are ready to start the download process. This is the main
    entry point of the script.

* configureScript(widget, config) (Optional)
  Parameter:
    widget: SettingWidgetAddptor (QWidget) type
    config: SciptConfigAdaptor type
  Description:
    If your script need config options, and you have implement a ui to
  show them (eg. via pyqt/pykde) , you will need this one. General way
  to do this is to implement your own QWidget subclass and call
  widget.setWidget(your_widget) to show it. You might use the config to
  deal with ini style file conveniently.

* configurationAccepted(widget, config) (Optional)
  Parameter:
    widget: SettingWidgetAddptor (QWidget) type
    config: SciptConfigAdaptor type
  Description:
    This function is called when user click 'ok' from the setting ui.
  Generally you should save your options, possibly with the help of
  the 'config' object.

=== Class ===
Some objects are not directly exposed to script, they are passed
in through the function arguments. Here describe their types.

* ScriptConfigAdaptor
  ** void setWidget(widget)
  Parameter:
    widget: QWidget type
  Description:
    The 'widget' should be your own script setting ui widget, once
  you are ready with your widget, call this function to show it.

* SettingWidgetAdaptor


=== Object ===
Objects are pointers exported to script using the kross lib,to use these
objects, you must import them first.
E.g. In python, you do 'import kgetcore'

* kgetcore
  ** void addTransfer(sourceUrl, filename)
  Parameter:
    sourceUrl: QString/string
    filename: QString/string, optional
  Description:
    Add the sourceUrl into the kget transferlist with the download file
    set to 'filename'. If filename is ommitted, then kget will determine
    the filename.
  ** string getSourceUrl()
  Description:
    Return the sourceurl from user input.

== NOTICE ==
* Don't use threading/thread function within python, it will freeze kget
(due to some GIL related issue?). Just write old-styled serialized
program. Same thing for other languages. This might be solved with the
improvement of kross.
