Grun stands for "GUI run'ner".

Grun is a python module helper to help you to build out some simple gtk app, by providing nice things to improve your scripts with GUI "bling bling".

It's clearly the easiest way to put some GUI things in your scripts/commands. It's a kind of gui framework. It provides :

• An easy way to turn your methods into GUI winforms, in one line of code.
• some simple dialogs (messagebox/prompt/progressbar)
• a pynotify wrapper
• a iconapp/tray backend to let your application stay in tray
• a popup generator
• a simple config backend to store configs in a xdg way
• a simple clipboard getter/setter (text only!)

All these things are available in a simple module, thru one magic method : grun() ! And better : it works on all platforms (windows, linux/bsd, mac) with its Tk backend. It uses pygtk if it's available.

Here we start ...

User forms (main feature)

grun is a magic method, and can act as a decorator too, to turn your methods into GUI forms.

from grun import grun

@grun
def ask_login(login, passwd_password):
    """ Just enter your login and password """
    return login, passwd_password

print ask_login(login="marc")

A window, named "Ask Login" will appear. The login will be pre-filled with "marc". When the user hit "ok" button, you'll get back these datas.

Note that if you don't want to use decorators: you can do grun(ask_login)(login="marc"), it's the same thing !

Many things are done under the hood :

• method's arguments are used to declare the entries in the form. (according argument's name or default value : it will create differents widgets)
• method's docstring is displayed in the window too.
• method's name is used to make a title for the window.
• method's return let the window close when hitting "ok". (if the method returns nothing, the window won't close !)

widgets are created according param's name or default value. Here's the rules :

• Combo entry : default's value is a python list (default values will fill the combo)
• Check entries : default's value is a python tuple (default values will be used to create checkbox entries)
• Number entry : name contains "int" or default's value is a number
• File entry : name contains "file"
• Folder entry : name contains "folder"
• Bool entry : name contains "bool" or default's value is a boolean
• Multiline Text entry : name contains "text"
• Password entry : name contains "passwd"
• String entry : if no other rules are true

See <code>test_types.py</code>, to see all kind of widgets in action.

...

Notifications

grun("hello world")

the text "hello world" will be sended to notification system. Note that if pynotify is available, grun will use desktop notifications, else it will show a simple window during 2 seconds.

MessageBox Dialog

Just ends your string with "!".

grun("Finished !")

A message box (of information type) will appear. Add more than one "!" at the end, a message box of error type will pop up.

Prompt dialog

Add a "?" at the end of the string, and it will turn it into a prompt box :

print grun("Do you want to continue ?")

which will display a prompt box, letting you answer by ok or cancel. The grun method return a boolean.

Progress window

By providing a generator to grun, it will display a 'progress window'. The generator should yield a float value between 0 and 1.

def working():
    yield 0.0
    yield 0.4
    yield 0.8
    yield 1.0

grun( working() )

But the generator can provide a textual message too, like that :

def working():
    yield 0.0, "Initialize"
    yield 0.6, "Doing the job"

grun( working() )

Tray Application

This thing works only with pygtk. With Tk, it simulates a window application (see below) with given actions.

grun( (action1, action2) )

For setting your icon, see below.

Window Application

A window application is a window with a button per action.

grun( [action1, action2] )

actions are methods (bound or unbound). If methods contains arguments, it will show a winform (see at the bottom).

...

Popup Generator

Just launch a popup menu providing actions :

grun( popup=[action1, action2] )  # old syntax

or

grun.popup( [action1, action2] )  # new syntax

actions are methods (bound or unbound). If methods contains arguments, it will show a winform (see at the bottom).

But you can show up a popup of selectable values, like that :

print grun.popup( ["hello","marco",42] )

the selected value will be returned by grun.popup. Of course, you can mix actions and selectable values too ! And you can add separator by inserting a None value, like that :

print grun.popup( ["hello",None,action1] )

And better, you can create submenu, by providing a tuple of 2 items : the first will be the label, the seconds a list.

submenu = ( "what color?", ["red","white","blue"] )
grun.popup( ["marco", submenu, None, action1] )

Dynamic form

It's a quick way to make a winform (useful for dynamic forms).

grun( form="text_name, int_age" )()   # old syntax

or

grun.form( "text_name, int_age" )()   # new syntax

It's the simplest form ... But you can give more too (by providing default values) :

grun.form( [("text_name",""), ("int_age","12") ] )()

Clipboard manager

You can have access to your clipboar manager (text only). If you want to put some text in the clipboard :

grun.clipboard = "hello"

If you want to retrieve the content text of the clipboard

print grun.clipboard

You can delete it too :

del grun.clipboard

Config backend

It provides a simple way to store a config dict, for config or persistant datas. Grun called with nothing returns a dict-like, which can be saved with its save method. The conf file is saved in the right place (XDG_CONFIG_HOME for XDG compliant platforms or under APP_DATA under windows).

cfg = grun()
cfg["login"]="marc"
cfg.save()

...

Some little things :

Providing a name for window's title

All windows use the name of the main script in their title. But you can override that by providing a global variable named NAME.

NAME = "hello"
from grun import grun
grun("This window should be named 'hello' !")

Providing an icon for windows/IconApp

You can provide an ICON too (to be displayed in window title or IconApp)

ICON = "gtk-info"
from grun import grun
grun("See the icon !")

When you use pygtk, ICON can refer a gtk icon stock, or an image file.

When you use tk backend (when pygtk is not available), you can give an ICO file under windows, or a xpm file under linux (should be prefixed with '@' !). But, currently, it will not work under tk, and will be corrected soon.

Use pango markups

When using pygtk backend, you can you use Pango Markup Language.

from grun import grun
grun("hello <b>World</b> !")

Not available with Tk backend.

Get Help !

At anytime you can ask help ;-)

This call will print in stdout, a short help :

grun("help")

This call will print in a messagebox, the short help :

grun("help!")

Download

Grun is available on pypy, install it from a terminal with easy_install grun !

Some samples