What's an Action?

When we fin­ished ses­sion 3 we had a ba­sic to­do ap­pli­ca­tion, with very lim­it­ed func­tion­al­i­ty: you can mark tasks as done, but you can't ed­it them, you can't cre­ate new ones, and you can't re­move them, much less do things like fil­ter­ing them.

To­day we will start writ­ing code and de­sign­ing UI to do those things.

The key con­cept here is Ac­tion­s.

• Help? That's an ac­­tion

• Open File? That's an ac­­tion

• Cut / Copy / Paste? Those are ac­­tions too.

Let's quote The Fine Man­u­al:

The QAc­tion class pro­vides an ab­stract us­er in­ter­face ac­tion that can be in­sert­ed in­to wid­get­s.

In ap­pli­ca­tions many com­mon com­mands can be in­voked via menus, tool bar but­ton­s, and key­board short­cut­s. Since the us­er ex­pects each com­mand to be per­formed in the same way, re­gard­less of the us­er in­ter­face used, it is use­ful to rep­re­sent each com­mand as an ac­tion.

Ac­tions can be added to menus and tool bars, and will au­to­mat­i­cal­ly keep them in sync. For ex­am­ple, in a word pro­ces­sor, if the us­er press­es a Bold tool bar but­ton, the Bold menu item will au­to­mat­i­cal­ly be checked.

A QAc­tion may con­tain an icon, menu tex­t, a short­cut, sta­tus tex­t, "What's This?" tex­t, and a tooltip.

The beau­ty of ac­tions is that you don't have to code things twice. Why add a "Copy" but­ton to a tool bar, then a "Copy" menu en­try, then write two han­dler­s?

Cre­ate ac­tions for ev­ery­thing the us­er can do then plug them in your UI in the right places. If you put them in a menu, it's a menu en­try. If you put it in a tool bar, it's a but­ton. Then write a han­dler for the ac­tion, con­nect it to the right sig­nal, and you are done.

Let's start with a sim­ple ac­tion: Re­move Task. We will be do­ing the first half of the job, cre­at­ing the ac­tion it­self and the UI, us­ing de­sign­er.

Creating Actions in Designer

First, let's go to the Ac­tion Ed­i­tor and ob­vi­ous­ly click on the "New Ac­tion" but­ton and start cre­at­ing it:

A few re­mark­s:

• If you don't know where the "X" icon came from, you have not read ses­­sion 3 ;-)

• The ac­tion­Delete_­Task ob­ject name is au­to­mat­i­cal­ly gen­er­at­ed from the text field. In some cas­es that can lead to aw­ful names. If that's the case, you can just change the ob­ject name.

• The same text is used for the icon­­Text and toolTip prop­er­ties. If that's not cor­rec­t, you can change it lat­er.

Once you cre­ate the ac­tion, it will not be marked as "Used" in the ac­tion ed­i­tor. That's be­cause it ex­ist­s, but has not been made avail­able to the us­er any­where in the win­dow we are cre­at­ing.

There are two ob­vi­ous places for this ac­tion: a tool bar, and a menu bar.

Adding Actions to a Tool Bar

To add an ac­tion to a tool bar, first make sure there is one. If you don't have one in your "Ob­ject In­spec­tor", then right click on Main­Win­dow (ei­ther the ac­tu­al win­dow, or its en­try in the in­spec­tor), and choose "Add Tool Bar".

You can add as many tool bars as you wan­t, but try to want on­ly one, un­less you have a very good rea­son (we will have one in ses­sion 5 ;-)

Af­ter you cre­ate the tool bar, you will see emp­ty space be­tween the menu bar (that says "Type Here") and the task list wid­get. That space is the tool bar.

Drag your ac­tion's icon from the ac­tion ed­i­tor to the tool bar.

That's it!

Adding Actions to a Menu Bar

Again, our menu bar is emp­ty, it has on­ly a sign say­ing "Type Here". While we could just drag our ac­tion to the menu bar, that would place "Delete Task" as a top lev­el menu, which is re­al­ly an un­usu­al choice.

So, let's cre­ate a "Task" menu first:

• Click on the "Type Here".

• Type "Task" (with­­out the quotes)

If you see the last im­age, by do­ing that we cre­at­ed a QMenu ob­ject called menu­Task (a­gain, the ob­ject name is based on what we type­d).

We want to add the delete task ac­tion to that menu. To do that, drag the ac­tion to the "Task" in the menu bar, then to the menu that ap­pears when you do that.

Now we have our ac­tion in the tool bar and in the menu bar. But of course, it does noth­ing. So, let's work on that nex­t.

Save it, run build.sh, let's move forward.

def on_actionDelete_Task_triggered(self,checked=None):
    if checked is None: return
    # First see what task is "current".
    item=self.ui.list.currentItem()

    if not item: # None selected, so we don't know what to delete!
        return
    # Actually delete the task
    item.task.delete()
    todo.saveData()

    # And remove the item. I think that's not pretty. Is it the only way?
    self.ui.list.takeTopLevelItem(self.ui.list.indexOfTopLevelItem(item))

Fine Tuning Your Actions

There are some in­ter­face prob­lems with our work so far:

1. The Task menu and the Delete Task ac­­tion lack key­board short­­­cut­s.

   This is very im­­por­­tan­t. It makes the app work bet­ter for the reg­u­lar us­er. Be­­sides, of­ten they will ex­pect the short­­­cuts to be there and there is no rea­­son to frus­­trate your user!

   Luck­­i­­ly, this is triv­ial to fix, just set the short­­­cut prop­er­­ty for ac­­tion_Delete_­­Task, and change menu­­Task's text prop­er­­ty to "&­­Task".

2. The Delete Task ac­­tion is en­abled even when it does­n't ap­­ply. If you have no task se­lec­t­ed, the us­er can trig­ger it, but it does noth­ing. That's a bit sur­pris­ing, and sur­pris­ing your users is not very nice, IMHO.

   There is some ar­gu­­ment about this, no­tably from Joel Spol­sky so maybe I am just old fash­ioned!

   To se­lec­tive­ly en­able or dis­able your ac­tions when there is/is­n't a se­lect­ed item in our task list, we need to re­act to our list's cur­ren­tItem­Changed sig­nal. Here's the code:

   def   on_list_cur­ren­tItem­Changed(self,cur­rent=None,pre­vi­ous=None):        if   cur­rent:            self.ui.ac­tion­Delete_­Task.setEn­abled(True)        else:            self.ui.ac­tion­Delete_­Task.setEn­abled(False)  

   Al­­so, we need to make Delete Task start dis­­abled be­­cause we start the app with no task se­lec­t­ed. That's done from de­sign­er us­ing its "en­abled" prop­er­­ty.

   Since there is on­­ly one Delete Task ac­­tion, this code af­­fects the task bar and al­­so the menu bar. That helps keep your UI con­­sis­­tent and well-be­haved.