README
1/* This file is part of the KDE project
2
3 Copyright (C) 2008 Ningyu Shi <shiningyu@gmail.com>
4
5 This program is free software; you can redistribute it and/or
6 modify it under the terms of the GNU General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9*/
10
11This file describes how to write a script using the kross interface from
12the content fetch plugin.
13
14== API ==
15
16=== Functions ===
17Script developer must implement certain functions in the
18script to be called by the content fetch plugin.
19
20* startDownload(config) (MUST implement)
21 config: SciptConfigAdaptor type
22 Descrption:
23 KGet will call this function when it gets the url from the user
24 input and are ready to start the download process. This is the main
25 entry point of the script.
26
27* configureScript(widget, config) (Optional)
28 Parameter:
29 widget: SettingWidgetAddptor (QWidget) type
30 config: SciptConfigAdaptor type
31 Description:
32 If your script need config options, and you have implement a ui to
33 show them (eg. via pyqt/pykde) , you will need this one. General way
34 to do this is to implement your own QWidget subclass and call
35 widget.setWidget(your_widget) to show it. You might use the config to
36 deal with ini style file conveniently.
37
38* configurationAccepted(widget, config) (Optional)
39 Parameter:
40 widget: SettingWidgetAddptor (QWidget) type
41 config: SciptConfigAdaptor type
42 Description:
43 This function is called when user click 'ok' from the setting ui.
44 Generally you should save your options, possibly with the help of
45 the 'config' object.
46
47=== Class ===
48Some objects are not directly exposed to script, they are passed
49in through the function arguments. Here describe their types.
50
51* ScriptConfigAdaptor
52 ** void setWidget(widget)
53 Parameter:
54 widget: QWidget type
55 Description:
56 The 'widget' should be your own script setting ui widget, once
57 you are ready with your widget, call this function to show it.
58
59* SettingWidgetAdaptor
60 Description:
61 This class is a helper class to provide a parser for the convenience
62 to load/save the configuration file.
63 Functions:
64 ** void setFile(config_file, path = "")
65 Parameter:
66 config_file: QString/string, config file name
67 path: QString/string, optional. The path of the config file, if
68 omitted, default value is the $KDEUSERDIR/share/app/kget/contentfetch_scripts_setting/
69 Description:
70 Initial the file, must be called before any read/write.
71 ** void unsetFile()
72 Description:
73 Free the file resource, ready to call setFile() again.
74 ** QVariant read(group, key, default_value)
75 Parameters:
76 group: string, section name
77 key: string, key name
78 default_value: int/double/string/list/stringlist
79 Description:
80 Read specific value from config, if not found, return default_value.
81 ** void write()
82 Parameters:
83 group: string, section name
84 key: string, key name
85 value: int/double/string/list/stringlist
86 Description:
87 Change specific value in the config.
88 ** void save()
89 Description:
90 Save the config data into file.
91 ** void reset()
92 Abandon changes in the config data, reread from file.
93
94
95=== Object ===
96Objects are pointers exported to script using the kross lib,to use these
97objects, you must import them first.
98E.g. In python, you do 'import kgetcore'
99
100* kgetcore
101 ** void addTransfer(sourceUrl, filename)
102 Parameter:
103 sourceUrl: QString/string
104 filename: QString/string, optional
105 Description:
106 Add the sourceUrl into the kget transferlist with the download file
107 set to 'filename'. If filename is ommitted, then kget will determine
108 the filename.
109 ** string getSourceUrl()
110 Description:
111 Return the sourceurl from user input.
112 ** void finish()
113 Description:
114 Notify kget the processing of the script finishes, should be called
115 at the end of the script.
116 ** void abort(error_message = "")
117 Parameter:
118 error_message: QString/string, optional
119 Description:
120 Notify kget the script has failed with the error message.
121
122== NOTICE ==
123* Don't use threading/thread function within python, it will freeze kget
124(due to some GIL related issue?). Just write old-styled serialized
125program. Same thing for other languages. This might be solved with the
126improvement of kross.
127