AWNLib

From AWN Wiki

Jump to: navigation, search

Contents

[edit] About AWNLib

AWNLib is a library that wraps around the default AWN API so that writing applets is easy and fun. The current version is 1.5, which is no longer available for download separately - it is now an official part of libawn-extras (itself part of awn-extras) and may soon be integrated with AWN proper. You can visit the Forum Thread to contact the developer, but IRC (irc.freenode.net/#awn) is prefered.

[edit] AWNLib 2.0

AWNLib is currently in version 1.5. Its developers hope to release a version 2.0 rather soon, which will bring the following changes:

  • Full PEP8 coding style. Overall, this will involve renaming the library and changing a few method names.
    • Limit all lines to a maximum of 79 characters.
    • Function/method names should be lowercase, with words separated by underscores
    • Modules should have short, all-lowercase names
    • See also: PEP8 Checker
  • A stable API, so that updates to AWNLib will not break existing applets
  • A way to test the library, probably in the form of a testing applet
  • A general code review
  • Perhaps other changes

In any case, AWNLib 2.0 will be deployed in such a way so as not to break applets based off of 1.5.

Hopefully, AWNLib can be integrated into AWN proper (not just AWN-Extras) shortly after the release of 2.0.

[edit] Tutorials

I'm beginning to write a set of tutorials on how to make an applet with AWNLib. If you want to learn how to write applets for AWN, this is probably the best place to start. Note: These are not done yet. So, don't expect them to be complete.

There's also a new nice tutorial that shows you how to get started, explains how to use themed icons, storing and saving settings, adding a preferences window, using a Cairo context or just an image as your applet icon, timers, and much more. See Writing Applets With AWNLib

[edit] Examples

AWNLib comes with an example applet that is used both as a test case and as an example of how to use AWNLib. 

#!/usr/bin/env python

import AWNLib
import gtk
import random

class TestClass:
    def __init__(self):
        self.value = 42

if __name__ == "__main__":
    # Test Initiation
    applet = AWNLib.initiate({"name": "AWNLib Test Applet", "short": "awnlib-test"})
    # The dict gives AWNLib info to use in error boxes and such

    # Test Title
    applet.title.set("Test Case Applet") # Need I say more?

    # Test Settings
    rnd = str(int(random.random()*1000000))
    applet.settings["test-key"] = rnd
    applet.settings["object-test"] = TestClass()
    rnd2 = applet.settings["test-key"]
    t = applet.settings["object-test"]
    if rnd == rnd2 and t.value == 42:
        gconf_good = True
    else:
        gconf_good = False

    # Test Icon
    applet.icon.theme("gtk-apply")

    # Test Effects
    applet.effects.launch()
    def testTiming(applet):
        applet.effects.notify()

    # Test Timing
    time = applet.timing.register(lambda: testTiming(applet), 3)
    # 3 seconds. We use the lambda to pass applet as a param

    # Test KeyRing
    applet.keyring.require()
    key = applet.keyring.new("AWNLib-Test Applet Key", "Password1", {"Attr1": "SHINEY"})
    applet.settings["password_token"] = key.token

    key = applet.keyring.new()
    key.token = applet.settings.get("password_token")
    if key.password == "Password1":
        keyring_good = True
    else:
        keyring_good = False
    del key # Stupid key, nobody loved it anyway

    # Test Notify
    applet.notify.send("AWNLib-Test", "Notifications Work!")

    # Test Dialogs
    dlog = applet.dialog.new("main") # Get a dialog
    str = "Results of tests:\n\n"

    if gconf_good:
        str += "Settings: <b>Good</b>\n"
    else:
        str += "Settings: <b>Error</b>\n"

    if keyring_good:
        str += "KeyRing: <b>Good</b>\n"
    else:
        str += "KeyRing: <b>Error</b>\n"
    label = gtk.Label(str)
    label.set_use_markup(True)
    dlog.add(label)

    AWNLib.start(applet) # Start the applet

This can be used as a quick introduction to using AWNLib. Specific examples accompany the API Documentation.

The Example Python Applet can be implemented with AWNLib as such: 

#!/usr/bin/env python

import AWNLib
import gtk

if __name__ == "__main__":
	applet = AWNLib.initiate()
	applet.title.set("Test python applet")
	applet.icon.theme("gtk-apply")

	applet.connect("enter-notify-event", lambda x, y: applet.icon.theme("gtk-apply"))
	applet.connect("leave-notify-event", lambda x, y: applet.icon.theme("gtk-cancel"))
	# BTW, NEVER do this. IE, make stuff other than the title happen on mouse-over/out

	dlog = applet.dialog.new("main")
	button = gtk.Button(stock="gtk-apply")
	dlog.add(button)
	AWNLib.start(applet)

[edit] API Docs

The API documentation is available as a PDF file, as generated by epydoc. These are API docs for 1.5.bugfix. They can also be generated from the python source by running epydoc --pdf src/libawn-extras/bindings/python/AWNLib.py in the source folder (this requires epydoc to be installed). Generating the docs yourself has the benefit of always giving you the most recent docs.

Retrieved from "http://wiki.awn-project.org/AWNLib"
Personal tools