Quickly Tutorial Part 1

This part 1 of the Quickly tutorial. This part is will introduce some key quickly commands, editing a user interface in Glade, and editing code in Gedit. This part of the tutorial will familiarize you with these three tools, and how they work together with python and pygtk so that you can quickly build applications.

Creating a Quickly Project

Creating the Empty Project

Creating an empty but working program couldn't be simpler. First, open a terminal window to type commands into. When it's open, type the command:

This will create a jotty sub directory containing a complete directory tree and files for an empty python application. The command finishes by running the newly created empty application.

Testing the Empty Application

They are populated and set up, and you can resize the window. Notice that quickly interfered that the application title is "Jotty". Only a few of menu items do anything in the empty application, Help->About, Edit->Preferences, and File->Quit.

Running the Application

Close the application by closing the window or using the Quit command. Since the empty application isn't installed into Ubuntu yet, you can't start the application from the application menu yet. To start the applicaton, use the terminal to first cd into the new subdirectory, and then use "quickly run" to start the program.

Editing an Application

Edit the User Interface in Glade

Quickly programs use Glade to edit the user interface. Start Glade with quickly in order to set up Glade for editing the empty applicaton. Don't start glade directly, or it won't load the necessary catalogue files for editing the classes that were automaticaly generated by quickly.

We want to create a text area for typing into. There are some default Widgets added to the Window. We won't need these so we'll start with deleting them. Click on the label, and press delete, and it will disappear from the window.

We'll use the bottom slot to add a TextView widget for the user to type into. In the toolbox, click on the TextView widget. Then click in the empty slot.

Make sure you save the file in Glade, or your changes won't take! Then run the application from terminal again. The window now has a place where the user can type.

Now we'll add the entry field for the title, and also a label for it. We'll use the top empty slot for that. First, click on Horizontal Box (HBox) from the "Containers" section of the pallette, and then click on the top slot. A dialog box will open, tell it that you want two items.

The HBox is a container that arranges it's children horizontally. Add a label to the empty left hand box, and a Text Entry to the right hand one.

Before going on, let's clean up the UI just a tad here. Select the new HBox from the treeview in the inspector window. Then go to the Packing tab, and set Expand and Fill to "No".

Select the label. On the general tab, set "Label" to "Name:". Set expand and fill to "no" for the label, but keep it "yes" for the entry. Set the padding for both to 5 (also on the Packing tab).

Add the Save, Open, and New Features

After the user types something, they may want to save it. A File->Save menu item was automatically created when the empty applicaton was created, but it's not hooked up to any code. To make Save work, we need tell the menu item what function to call, and then create a function to actually do the saving.

Set the Signal Handler in Glade

To tell the menu item what function to call. If glade is not still open, open up the application in glade:

In pygtk, menu items are "activated" when a user chooses the item from the menu. Since we want a function to run when the user chooses Save, we want to specify a function to respond to the activate signal from the menu item. We'll call the function "save_file". Simply type the function name into the box for the activate signal.Make sure to save the glade file.

Note that you will need to setup the "open_file" signal and the "new_file" signal as well when you get to those functions later.

Edit the Code in Gedit

Set Up Tabs Correctly

Note a major gotcha here. In python spaces and tabs are totally different, but they look just the same in an editor. So being indented one tab stop is not the same as being indented four spaces, even though they might look the same. And indentation level is very important in python. You will get a lot of errors if you mix tab indentation with space indentation. Your generated project follows the python standard of using four spaces for each indentation level. So you'll either have to hit the space bar four time every time you indent, or set up your editor to use the right number of spaces for tabs.

The upshot is that you should take a moment to set up your Gedit (or whatever editor you are using) to use spaces for tabs. In Gedit, select Preferences from the Edit menu, and choose the Editor tab. Then set Tab width to 4, and turn on "Insert spaces instead of tabs". Your preferences should look like this:

Create the Save File Signal Handler

Now you're ready to write some code. Of course just telling the glade file what signal to emit won't make the file actually save, because we haven't created the "save_file" function yet. The code for JottyWindow is stored in the file jotty. jotty is a special python file that is the entry point for your application. Other python files in your application have the ".py" suffix.

This will open the default Ubuntu text editor "Gedit" with any python files in the python directory.

JottyWindow.ui is now expecting to find a function JottyWindow.save_file(), so we simply add one to the JottyWindow class in the jotty file right under the on_destroy funtion.:

This will print the word "save" to the terminal when run. The method signature is the standard signature expected in a signal handler. If you are new to python, be sure to copy the indentations exactly, as the indentation level is very important in python.

Choose "File->Save" from the menu, and you'll see the word "save" printing out interminal. That's all there is to hookig up the functions!

Implementing Save

Now we'll write a little code in the signal handler to actually save the text. Because we want it to be easy for users to do things like syncronize their Jotty documents between computers, back it up, etc... we'll use couchdb as our backend, and we'll use desktopcouch for our api. Note that if you are not interested in learning about how to save to and read from couchdb, you can just snipe the code. Mostly likely you already have everything you need installed when you installed quickly. But, you may need to install couchdb, desktopcouch, and the desktopcouch records api. The fastest way to do this is from the terminal:

This will install the api, and everything you need for the api to run. After desktopcouch is installed, you can write the code. The code will do the following:

Import the stuff you'll need from python-desktopcouch-records.

Add these import statements along with the other imports to the top of the jotty file:

Get a Reference to the Database

Desktopcouch will set up a database for us, or create a new one if it's needed. We'll use "jotty" for the name of the database. Since we want this line to run every time the Jotty Window is created, put it at the end of the finish_initializing function:

Now that we have an instance-wide reference to the database, we'll add code to the save_file function to run whenever the Save command is issued.

Here's the code to pull the title out of the title entry:

Here's the code to get pull the text out of the TextView:

In pygtk, TextView widgets have a text buffer that stores the text. So you ask the TextView for it's TextBuffer, and then you ask the TextBuffer for the text. You use iters to determine from which part of the text buffer you want text. Since we want all the text, it's easy to just get the start and end iters.

Saving a document to Couchdb

A record in couch is essentially a python dictionary with some extra key/value pairs to make the database work. So we can save the document to couch like this:

The "record_type" field is not strictly required, but among other things, it makes it easy to fetch the documents later. By convention, we use a url to specify the record type. This provides a place for other developers to go to read about the record type. The description only needs to be human readable. Couchdb is not a typed database, so don't expect that the url will have any kind of schema definition or anything. You can use whatever url you want, and put whatever you want at that URL.

Check for a pre-existing note with the same title

Before we just write the new document though, we have to take note of the fact that couch will allow you to create as many documents as you want with the same title. We probably don't want this, so we we'll have to write a little code to check if there is already a document in couch with the same title, and if there is, update that document rather than create a new one.

In CouchDB, you don't do a lot of data processing in the database like you would with a relational database. To be most efficient, we could use the desktopcouch API to create a view in CouchDB, but it's probably simplest just to do the necessary processing on the client for now. To do this, we'll use a desktopcouch function to retrieve all of the records of a specified record type.

So the whole function should look like this:

def save_file(self, widget, data=None):
        #get the title for the note
        title = self.builder.get_object("entry1").get_text()

#get the text to save
        buff = self.builder.get_object("textview1").get_buffer()
        start_iter = buff.get_start_iter()
        end_iter = buff.get_end_iter()
        text = buff.get_text(start_iter,end_iter)

#get all the records
        record_type = "http://wiki.ubuntu.com/Quickly/JottyDoc"
        results = self.database.get_records(record_type = record_type, 
                                            create_view = True)

#update a record that has the same title
        for result in results:
            document = result.value
            if document["title"] == title:
                key = result.key
                self.database.update_fields(key, {"text":text})
                return
        
        #if no records had the title, create it  
        new_rec = Record({"record_type":record_type ,
                            "title":title, "text":text})
        self.database.put_record(new_rec)

Couchdb makes it really easy to see if your save function is working. You can just point your web browser at it and explore the database:

If you are redirected to a page that doesn't work, you probably just need to clear your browser cache and try again.

Implementing Open and New

To open a saved document, the user will type the title of the document that they want to open in the text entry, and choose "Open" from the main menu. If there is no matching document there, it will just clear out the text view, ready for input. This is probably not too intuitive, so we'll add a dialog box for prompting the user for the title, but that's for later in the tutorial. For now, we'll just use the same text entry field.

Implementing Open is essentially the reverse of Save:

Implement New

First, add the new_file signal to the menu item in Glade, then add this code to clear out the text:

To make them work, add these functions to the JottyWindow class, and save. Then go back and connect the functions to the activate signals for the Open and New menu items.

Saving Your Work

When Quickly created your application, it automatically added it to Bazaar, a source code versioning system. You can use Bazaar to roll back mistake, see code history, compare versions, etc... Quickly has a convenience function for backing up your work:

Introduction to Part 1