uxPython - cross platform GUI Toolkit & IDE in Python open source

Creating a custom widget - Part 2

Note that this tutorial builds on part 1

Welcome to part 2 of creating a custom widget in uxpython.

In this tutorial we will learn:

• Setting and Using Styles
• Observing attributes
• Handling Events
• Using behaviors

Styles

Styles in uxpython is similar to css you might be used to in web development. You use styles to control both appearance and some layout options.

So lets start by modifying our previous widget's constructor to:

class uMyWidget(uBase): def __init__(self,idc,parent = None): uBase.__init__(self,idc,parent) self.style.background = '#FFFFFF' self.style.color = '#BF711D' self.style.text_align = 'center'

You set styles by using the "style" object available in every widget. The properties try to use the equivelent css names. In our example we set the background to white(#FFFFFF) and the text color to burnt orange(#BF711D) while aligning text to center.

You can also use CSS style declarations like this:

self.style.css = """ background: #FFFFFF; color: #BF711D; text_align: center; """

Now to actually use the styles we have to change our rendering method to this:

def renderctx(self,ctx): style = self.style ctx.rectangle(0,0,self.width,self.height) setColour(ctx,style.background) ctx.fill() #built in method displays text according to style self.showText(ctx)

Now we just use the styles in our render method. The showText method is a helper to display text according to the styles we have set. It uses the text property I will explain in the next section.

Observing properties

Sometimes you have important properties that you want to be notified if they change and if they change the user interface should update. In uxpython we have a mechanism to do this. Its called the Observe method and allows an event to be fired when an attribute changes plus it marks the widget as needing rendering.

In your constructor put the following:

self.text = "Hello World!" self.Observe('text') self.addEvent('text_change',self.textchange)

It's not necessary to put Observe in init but it is recommended. Now you need to implement the event handler you specified

def textchange(self): print "The text has changed to ",self.text

Events

In the previous section I lightly touched upon event handling. Event handlers are specified by using addEvent with the type as first parameter eg. "click", 2nd parameter the function callback, 3rd the optional bool if it should be run asynchronously (not block UI updates) and 4th parameters that should be passed to the function callback

Put the following in init:

#event handler self.addEvent('click',self.click) #event handler with variables self.addEvent('click',self.clickB,False,'Silly') #asyncronous event handler self.addEvent('rightclick',self.rclick,True)

and the associated functions:

def click(self): self.text = "Hello Universe!" def clickB(self,var): print "The variable is ",var def rclick(self): self.style.color = '#000000' self.text = "sleeping for 2 seconds." time.sleep(2) self.style.color = '#BB0000' self.text = "Somewhat later..."

Behaviors

Behaviors are classes that add functionality to your widget mainly through using events. Custom behaviours will be covered in a future tutorial.

We will add a hover behaviour to our widget. The hover behaviour will alter the state of our widget. The widget state is a property that describes the state a widget is in. eg: "click","normal","hover"

Styles are affected by the widget state. You can set a specific style for a state by starting your declaration with the state followed by a ":". eg: self.style.background = ":hover #F5F5F5"

Add the following to the constructor:

self.addBehave(uHover) self.style.background = ':hover #F5F5F5' self.style.css = ':hover color: #0000FF;'

As you can see the behaviour automatically toggles the state, and the state switched between the styles you have selected.

Conclusion

That's all for now. In part 3 we look at child widgets and layout managers.

Code for this tutorial

[widget2.py]

from uxGUI.base import * import time class uMyWidget(uBase): def __init__(self,idc,parent = None): uBase.__init__(self,idc,parent) self.style.background = '#FFFFFF' self.style.color = '#BF711D' self.style.text_align = 'center' self.style.css = """ background: #FFFFFF; color: #BF711D; text_align: center; """ self.text = "Hello World!" self.Observe('text') self.addEvent('text_change',self.textchange) #event handler self.addEvent('click',self.click) #event handler with variables self.addEvent('click',self.clickB,False,'Silly') #asyncronous event handler self.addEvent('rightclick',self.rclick,True) self.addBehave(uHover) self.style.background = ':hover #F5F5F5' self.style.css = ':hover color: #0000FF;' def click(self): self.text = "Hello Universe!" def clickB(self,var): print "The variable is ",var def rclick(self): self.style.color = '#000000' self.text = "sleeping for 2 seconds." time.sleep(2) self.style.color = '#BB0000' self.text = "Somewhat later..." def textchange(self): print "The text has changed to ",self.text def renderctx(self,ctx): style = self.style ctx.rectangle(0,0,self.width,self.height) setColour(ctx,style.background) ctx.fill() #built in method displays text according to style self.showText(ctx)

and the window runner: [runner.py]

from uxGUI import * from widget2 import uMyWidget class myWindow(uxWindow): def init(self): self.caption = "Widget Runner" r = uMyWidget(None,self) r.x = 10 r.y = 10 myWindow().app.run()