AWNLib Tutorial Part 1
From AWN Wiki
Contents |
[edit] About This Tutorial
This tutorial is for anyone who wants to write applets for AWN. It'll teach you how to write applets using the AWNLib framework - the framework is very nice and makes it much easier to get up and running with an applet. Most of this part, and to a lesser degree the next few parts, will also be of use to the AWN Applet developer who doesn't use AWNLib (or even Python).
[edit] Prerequisites
This tutorial doesn't assume that much, but it does assume that:
- You know Python. Python isn't that hard a language to learn, and its fun to use, but in any case, AWNLib is Python-only and this tutorial will only use Python. There are also Vala and C bindings for AWN, though, so you can still write applets for AWN. This tutorial just isn't the place for you.
- You either: A) have the source of AWN-Extras-Testing or B) have downloaded AWNLib. There's a link on the AWNLib page. Download from there. If you are running AWN-Extras-Testing, you can go into the src/libawn-extras/binding/python directory and find AWNLib.py in there.
[edit] Starting off
Lets gather our belongings and start a new applet. Here, we'll be making an applet that shows the RSS feed from slashdot. No particular reason for picking slashdot, but why not? BTW, you can get the same functionality by using the aRSS applet. But let's not let that bother us. So to start off, you need a new folder structured as follows:
- / (Applet Folder)
- slashdot
- AWNLib.py
- slashdot
We'll place a file right in the / applet folder that identifies your applet and then we'll put our main python files in the slashdot folder. Its important that you name your other important files slashdot. In particular, name all your files the same as you name your main desktop file, which is our next step.
Note that from now on, all commands are assumed to be run from the mail applet folder.
[edit] What's the Thing Called Again? Tell AWN About Your Applet
The most important part of your applet is about to be created. This is the desktop file. The desktop file explains to AWN what it is and how to run it. Create a new file named slashdot.desktop in the main applet folder and paste this into it:
[Desktop Entry] Type=Python X-AWN-AppletType=Python Encoding=UTF-8 Name=Slashdot Applet Comment=Get /. Updates Exec=slashdot/slashdot.py Icon=slashdot/slashdot.svg X-AWN-AppletCategory=Network,News
Lets look at what we have here. The first line looks the line your average .desktop file should have. The next line identifies your applet as a Python applet for AWN. So does the third line. Why? Basically, if you applet is included into the AWN-Extras trunk or testing, the Type line will be changed to "Type=Application". However, that won't work for the current release of AWN (0.2.1). Since you don't want to lose those users, you use the older (incorrect) line. Hopefully that becomes unnecessary later on. Line 4 does what you'd expect it to. Lines 5 and 6 (Name and Comment) define the title of your applet in AWN-Manager and the description (respectively). Line 7 (Exec) tells AWN what python file to run when it wants to start your applet. Line 8 tells it the icon that shows up in AWN-Manager. This is not necessarily the icon in the bar. The last line describes that categories that your applet falls under. For now this is unused, but at some point in the future it may become used. You can get a list of possible categories at the freedesktop.org spec.
Also note that you don't necessarily need to provide your own applet icon, you can use one from the theme like any old .desktop file. Just remember that not all users might have your icon. For a generic mail icon, its OK. For the Firefox icon in particular, maybe its better not to depend on it. In this case, of course, there's no slashdot icon in most (all?) themes, so we'll be providing our own.
[edit] A Setting Up Your Work Environment
You might want to link the folder in which you're writing development to the folder where AWN finds its applets. This means that your changes would be instantly reflected in AWN-Manager. You'll want to do the following in your root applet directory:
cp slashdot.desktop ~/.config/awn/applets/slashdot.desktop ln -s slashdot ~/.config/awn/applets/slashdot
Then, modify ~/.config/awn/applets/slashdot.desktop as such:
Icon=[Home Folder]/.config/awn/applets/slashdot/slashdot.svg
Where [Home Folder] is your home folder. The reason for the change is so that AWN-Manager will find your icon. The Exec field can use a relative path but the Icon Field cannot. The reason we made a separate copy instead of linking it is that the Icon field will be made into a absolute path by AWN-Manager, so you want the "real" copy to be using a relative path, so that end users don't have to modify the file for their home folder.
Also, this lets you change the title to something like "Slashdot Applet (DEVEL)" and distinguish it from the AWN-Extras copy if your applet is ever added to AWN-Extras. (That way you can make local changed to test while you develop).
[edit] Making the Icon
We need a few files we mentioned before but didn't actually include. This is the slashdot.py and the slashdot.svg file. While we're here, we may as well fill the SVG file with something useful, so why don't you paste the following inside a file named slashdot.svg inside the slashdot folder in the main applet folder:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://web.resource.org/cc/"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="256"
height="256"
id="svg2"
sodipodi:version="0.32"
inkscape:version="0.45.1"
version="1.0"
sodipodi:docbase="/home/pavpan/Development/Applets/AWN/Slashdot/slashdot"
sodipodi:docname="slashdot.svg"
inkscape:output_extension="org.inkscape.output.svg.inkscape">
<defs
id="defs4" />
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
gridtolerance="10000"
guidetolerance="10"
objecttolerance="10"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="0.98994949"
inkscape:cx="158.60416"
inkscape:cy="133.39961"
inkscape:document-units="px"
inkscape:current-layer="layer1"
width="256px"
height="256px"
inkscape:window-width="872"
inkscape:window-height="627"
inkscape:window-x="241"
inkscape:window-y="290" />
<metadata
id="metadata7">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1">
<path
style="fill:#006464;fill-rule:evenodd;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:none;fill-opacity:1"
d="M 38.385797,219.6345 L 85.862967,44.878118 L 126.26907,44.878118 L 79.232864,220.41962 L 38.385797,219.6345 z "
id="path2684" />
<path
style="fill:#006464;fill-rule:evenodd;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;fill-opacity:1;stroke-miterlimit:4;stroke-dasharray:none"
d="M 163.64472,143.87306 L 194.95945,175.18779 L 165.15995,204.98729 L 135.86552,175.69287 L 163.64472,143.87306 z "
id="path2686" />
</g>
</svg>
This is just a quick SVG file I made in Inkscape that sort of looks like the Slashdot logo. If you want, have fun making a better one, but for now this will do.
For now, so that we remember to create a Python file, lets create an empty one.
touch slashdot/slashdot.py
The Python file is valid, and useless. If you try to add your applet in the AWN-Manager, you'll get your white line. So onward, to Part 2, where we make the applet actually do something!
