pycious(1)
==========


NAME
----
pycious - Simple and efficient widget library for the awesome window manager written in Python


DESCRIPTION
-----------

*pycious* is a widget library for the "awesome" window manager that allows 
to write widget directly written in Python instead of using Lua language.
The main advantage of this is because with Python it is possible to write 
complex widget using all the available bindings and packages already written 
in Python. Furthermore, the api reference is simpler and more object oriented 
than the corresponding api of awesome.
*pycious* gives also some already written widgets for monitoring system (cpu 
usage, mem usage, ...), gathering web information (mail, rss, ...) and 
applications (dictionary, volume, ...).

*pycious* widget types are a framework for creating your own awesome
widgets. In *pycious* is rewritten the awesome api reference to be used of 
creating your widgets. It's also possible to use some function that gather 
information and can be used to custom the widget as you want. 


INSTALLATION & CONFIGURATION
----------------------------
In order to install *pycious* consider the following steps:

*  Copy and rename the file 'rc-example.py' from the installation 
   directory of *pycious* to your '~/.config/pycious/rc.py' 
*  Put in '~/.xinitrc' the following:
   -----------------------------
   ~/.config/pycious/rc.py &
   -----------------------------


USAGE
-----
After correctly installing *pycious* you must edit 'rc.py' file
You must declare all the widgets you want in awesome directly in 'rc.lua' 
before configuring them in 'rc.py'. Moreover, the widgets have to stay declared
in a wibox as whatever other widgets of awesome. For example, if we want to define a 
widget for mail:

------------------------------------------------------------
mailwidget = widget({ type = "textbox", align = "right" })

-- In the creation of wibox
mywibox[s].widgets{
...
...
mailwidget
}
------------------------------------------------------------

After doing so, you just use it directly in 'rc.py' in two ways.

*  The simplest way is by using the built-in widget of *pycious*.
   You need to hook it with the corresponding object in 'rc.lua' 
   by passing in the argument the name of the widget in lua.
   For example for mail widget:

------------------------------------------
from pycious.widgets.web import MailTextWidget
widget = MailTextWidget('mailwidget')
widget()
------------------------------------------
This create a callable object and every time you call it, it update the 
number of unread mails.

*  The second way is by using the awesome api reference of *pycious*
   creating a TextWidget object:
------------------------------------------
from pycious.api.widget import TextWidget
widget = TextWidget('mailwidget')
------------------------------------------
   In this case you need to implement the mail logic from scratch. 
   *pycious* gives for you some utility function for gather information 
   such as Mail to get the number of unread mail. In this way you can integrate
   both graphcal and logic component to create custom widget as much fast as 
   possible:
--------------------------------------------------
from pycious.lib.web import Mail
mail = Mail(username, password, server, port)
mail() # return number unread mails
--------------------------------------------------

BUILT-IN WIDGETS
----------------
# TODO explain all the available built-in widgets



COPYRIGHT
---------
       Copyright  (C) 2008, 2009, 2010, 2011, 2012 Free  Software 
       Foundation, Inc.

       Permission  is  granted to make and distribute verbatim copies
       of this document provided the copyright notice and  this  per‐
       mission notice are preserved on all copies.

       Permission is granted to copy and distribute modified versions
       of this document under the conditions  for  verbatim  copying,
       provided that the entire resulting derived work is distributed
       under the terms of a permission notice identical to this one.

       Permission is granted to copy and distribute  translations  of
       this  document  into  another language, under the above condi‐
       tions for  modified  versions,  except  that  this  permission
       notice  may  be  stated  in a translation approved by the Free
       Software Foundation.

BUGS
----
	Of course there is no bug in *pycious*. But there may be unexpected behaviors.
	Go to 'https://github.com/fsquillace/pycious/issues' you can report directly
	this unexpected behaviors.

SEE ALSO
--------
*vicious* - Modular widget library for the awesome window manager

AUTHORS
-------
Filippo Squillace <sqoox85@gmail.com>.
Giuseppe Leone <joebew42@gmail.com>

WWW
---
http://github.com/fsquillace/pycious

Last words
----------
[verse, Dante Alighieri, from Divine Comedy]
__________________________________________________
O somma sapïenza, quanta è l'arte
che mostri in cielo, in terra e nel mal mondo,
e quanto giusto tua virtù comparte! 
                            (inferno, XIX, 10-12)
__________________________________________________