kde-extraapps/kget/transfer-plugins/contentfetch

/* 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
  Description:
    This class is a helper class to provide a parser for the convenience
    to load/save the configuration file.
  Functions:
  ** void setFile(config_file, path = "")
  Parameter:
    config_file: QString/string, config file name
    path: QString/string, optional. The path of the config file, if
  omitted, default value is the $KDEUSERDIR/share/app/kget/contentfetch_scripts_setting/
  Description:
    Initial the file, must be called before any read/write.
  ** void unsetFile()
  Description:
    Free the file resource, ready to call setFile() again.
  ** QVariant read(group, key, default_value)
  Parameters:
    group: string, section name
    key: string, key name
    default_value: int/double/string/list/stringlist
  Description:
    Read specific value from config, if not found, return default_value.
  ** void write()
  Parameters:
    group: string, section name
    key: string, key name
    value: int/double/string/list/stringlist
  Description:
    Change specific value in the config.
  ** void save()
  Description:
    Save the config data into file.
  ** void reset()
    Abandon changes in the config data, reread from file.
  

=== 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.
  ** void finish()
  Description:
    Notify kget the processing of the script finishes, should be called
    at the end of the script.
  ** void abort(error_message = "")
  Parameter:
    error_message: QString/string, optional
  Description:
    Notify kget the script has failed with the error message.

== 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.