=============================
README: GooeyPy
=============================

:Author: Joey Marshall
:Contact: web@joey101.net

Please don't contact me about bugs with the OpenGL rendering (unless you have a fix), I already know about them!

Who is GooeyPy for?
-------------------
GooeyPy is designed for smaller SDL games that need a light GUI implemented easily and fast. It can be used, but isn't really designed for, larger games that need large complex GUIs.

Description
-----------

GooeyPy is the result of my need for a flexible and easy to use gui for pygame. Yes, I realize there are already guis for pygame out there. But with each one there is something I don't like. GooeyPy simply has everything the way I like it. So I'm not going to say it's the best one out there, because everyone has their own opinions. Here are some things that are different about GooeyPy:

Styling:
    I didn't like the way styling worked with other guis. Maybe I'm just spoiled by CSS in web development, but wouldn't it be nice if you could have CSS like styling for a gui? Oh woops, now you can! With GooeyPy, all widgets are stylable with CSS like attributes. Also, at any time during the application run time you can change the styling dynamically (and it will update itself)! All information related to displaying widgets are stored in the styling (that includes positioning; relative or absolute)

    .. sourcecode:: python

        l = gui.Label("Text", x=395, y=30, font_size=25, color=(0,255,0))

    Any additional arguments passed when creating a widget are taken as styling options.

Integration:
    With all the guis I've tried, you have to figure out how to integrate the gui into an already made game. Sometimes that's impossible. And if it is possible, until you figure out how the gui works, it's very hard to do. GooeyPy doesn't steal your pygame events and doesn't interfear with your bliting (well, actually it can. Setting up the surfaces can be a little hairy, but there is some nice documentation to explain it all).

Dependencies:
    First of all, this isn't what you think. I'm not meaning other libs that GooeyPy depends on, but the dependencies within GooeyPy. Ok, that doesn't make a whole lot of sense... let me put it another way. You have a widget and all of the sudden you want to change the value. so you do widget.value = "hi". And it works! GooeyPy automatically knows when something changes that effects another part of itself. In this case, the value effects how the widget displays, so it will redraw itself. It works that way with everything! You never have to worry about redrawing a widget when it's dirty (and nither do I within GooeyPy, so that means a whole lot less bugs). All the dependencies are also cached.

Linking:
    Another cool thing I have is you can link values from one widget to another. So if the value of widget A changes, so does the value it's linked to in widget B.

    .. sourcecode:: pycon

        >>> l1 = gui.Label("Text")
        >>> linked_l = gui.Label(l1.link("value"))
        >>> linked_label.value
        Text
        >>> l1.vale = "Something else"
        >>> linked_label.value
        Something else

    Be carefull not to do **l1.value** as that will put the actual string value!

    You can also link with functions!

    .. sourcecode:: pycon

        >>> x = 1
        >>> y = 2
        >>> l = gui.Label(lambda:x+y)
        >>> l.value
        3
        >>> x = 6
        >>> l.value
        8

    Actually you'll need to do app.run() before it will recalculate the values sense x and y aren't cellulose cells, but you'll be doing that every frame anyways. :)

Effects:
    I like the ability to have cool effects applied to my widgets. Now I have them.


Documentation
-------------

You can open up ipython, import gooeypy, and find allot of documentation in the doc strings... or you can look at docs/index.html with all the doc strings nice and organized.

If you would like somewhat of a quickstart guide, you can look at examples/example1.py. It has lots of helpfull comments and the actual example program displays a lot of the cool stuff in GooeyPy.