- Qt 5.0
- ToDo Example
- Qt 5.0.0 Reference Documentation

# ToDo Example

The ToDo example shows how to organize todo items using the Qt Organizer framework.

Most organizing software, e.g., calendar applications, lets the user create todo items, which describe an activity that should be completed. Other items may include meetings, notes, and events. A todo item typically includes the following information:

- A timestamp for when the item was created.
- A timestamp for when the activity should be completed.
- A timestamp for when the activity was completed.
- A priority for how important the activity is.
- Information on whether the todo is recurring (i.e., if it should be repeated at regular intervals).
- A description of the activity.

A todo item is represented in Qt with the QOrganizerTodo class. Instances are managed by a QOrganizerManager, which can save todos created by a program and return the todo items it manages. QOrganizerTodo contains the information mentioned in the list above. In Qt, we call this item details. They are represented by QOrganizerItemDetail and its subclasses. For instance, QOrganizerTodo keeps a QOrganizerItemPriority (which inherits QOrganizerItemDetail).

The item details available for a QOrganizerTodo follows a standardized schema, i.e, a todo item has a standard set of item details. Most QOrganizerManager backends will follow this schema. A backend is the implementation of the QOrganizerManager's functionality for a specific platform. Some backends may not support all details, and possibly include others.

The example consists of two classes:

- `Window`: Lets the user select a date and create todo items for the date selected. It also displays a list with todo items for the date selected.
- `TodoEditor`: Lets the user edit a todo item using standard Qt widgets.

We will now look at the definitions and implementations of `Window` and `TodoEditor`.

#### Window Class Definition

The `Window` class is responsible for setting up the GUI of the example. It creates QOrganizerTodo items and send them to the TodoEditor for editing. It saves and retrieves todo items from the organizer item manager.

Let's take a look at its definition.

The slots are connected to the widgets of `Window`, and handles user requests to create a new todo item, edit an existing item, and delete an item. The `saveTodo()` slot is invoked when the user has finished editing a todo item. `refreshList()` updates the Todo Item List when todo items are added, deleted, or edited.

We'll now go through the slots and constructor of `Window`. The only other function, `setupGui()`, initializes and lays out the widgets, and that is treated in other examples.

#### Window Class Implementation

The constructor creates the QOrganizerManager instance:

We here instruct that the manger should use the `memory` backend. This backend implements the default schema and uses the computers memory for storing items. This way, we can be sure that the backend will behave equally on all platforms.

The `editNewTodo()` slot is connected to the New Todo Button, and sets up a new QOrganizerTodo for editing.

Here we set the item details of the new QOrganizerTodo to reasonable defaults. The `editTodo()` slot sets up the widgets of the `TodoEditor` with the data from the new todo. Finally, the stacked widget is set to show the todo editor.

The `editTodo()` slot is invoked when the player double clicks a todo item in the Todo Item List with the mouse.

The slot is invoked with the QListWidgetItem that was double clicked. We have saved the QOrganizerTodo in the list widget item. The list widget item stores data in QVariants, so we need to include the Q_DECLARE_METATYPE() macro, which helps make QOrganizerTodos usable with QVariant.

When we have retrieved the todo item, we send it to the `TodoEditor` for editing, which we show on the screen.

The `saveTodo()` slot is invoked by the `TodoEditor` when the user has finished editing.

Saving a QOrganizerTodo in the QOrganizerManager is easy using the saveItem() function. We call the `refreshList()` slot to update the Todo Item List so that new and edited todos is displayed correctly.

The `deleteTodo()` slot is connected to the Delete Todo Button, and will delete the currently selected todo in the Todo List from the manager.

Here we fetch the selected list widget item from the list. To delete the item in the manager, we send the items id to the manager's removeItem() function. An item's id uniquely identifies it in its manager.

We now move on to the `refreshList()` function, which set's up the Todo List with the todo items currently stored in the manager.

First we remove all items from the list widget, i.e., we set up the list from scratch each time `refreshList()` is called.

The items() functions retrieves QOrganizerItems from the manager. By giving the manager a QOrganizerItemSortOrder, the manager will sort the items for us. The sort order takes the item detail it should sort after. You also need to specify which field of the detail should be used for sorting. Note that all details have a DefinitionName constant declared. They also keep constants for all of their fields. The items() takes a list of sort orders in case one wants to sort by more than one field.

It is also possible to let the manager filter items. You can look up the QOrganizerItemFilter class description for details.

We iterate through the todo items in the manager, keeping the items that are active, i.e., the date selected in the calendar is between the start and due dates of the item.

We create a list widget item for the todo. We set its text to the item's start sate, due date, and displayLabel().

We save the QOrganizerTodo itself in the Qt::UserRole of the list widget item. We have seen previously how to retrieve it.

#### TodoEditor Class Definition

The `TodoEditor` contains widgets for editing a QOrganizerTodo.

Here is the `TodoEditor` class's definition:

The `editTodo()` slot is called by `Window` when a todo item should be edited. `finishEditing()` is connected to `doneButton`, and emits the `editingFinished()` signal. This signal is connected to the `saveTodo()` slot of the `Window`.

The rest of slots are connected to the widgets that edit the todo item's details.

`setupGui()` creates, lays out, and connects the widgets to the slots of `TodoEditor`. `setupCombos()` helps `setupGui()` by creating the comboboxes and by filling their drop-down lists.

#### TodoEditor Class Implementation

We start by taking a quick look at `setupCombos()`, which sets up the QComboBoxes.

As with list widget items, you can also store user data in an item of QComboBox's drop-down list. Here we save a QOrganizerTodo's possible values for its priority() and status() details. The `alarmCombo` helps the user select a time for when to be reminded of the todo.

The `editTodo()` slot is called when a new QOrganizerTodo should be edited.

We set the contents of our widgets to the details of the todo item. The functions we use here are utility functions provided by QOrganizerTodo that accesses the QOrganizerItemDetails for us. We could also have accessed them by using the value() functions of QOrganizerItemDetail.

Many backends support notifying the user when a todo item is due. We can request this by adding a QOrganizerItemRemainder detail to the QOrganizerTodo. We first check whether a remainder detail is present on the todo item. If it is we update the Alarm Combo Box. The secsTo() function returns the difference between two QDateTimes in seconds.

The next two slots update the subject and description of the todo item.

We save the subject in the item's displayLabel(), which is meant for displaying a short description that can be used in item views. The description() is a longer text describing the item.

The `updateDates()` slot is connected to the two QDateTimeEdits that let the user select start and due dates for the todo item.

Note that we need to update the remainder detail when the due date changes because the remainder is calculated relative to the due date. We do that in `updateAlarm()`, which we will come back to later.

The `updateStatus()` and `updatePriority()` functions are connected to the combo boxes that we created in `setupCombos()`.

The only thing to notice here is that enum values are saved as `int`s in the drop-down list items.

The `updateAlarm()` function is connected to the `alarmCombo` as we saw earlier.

We first calculate the time before the todo is due the alarm should go off. We calculate this in seconds because QDateTime's addSecs() function gives us an easy way of finding the time from the todo's due time.

Before we add the new reminder, we need to remove any previously added reminders; if not, the QOrganizerTodo item would have several QOrganizerItemVisualReminders registered with it.

The reminder is not accessible through the convenience functions of QOrganizerTodo, so we add it using the item detail access functions from QOrganizerItem.

Files:

- todo/main.cpp
- todo/todo.pro
- todo/todoeditor.cpp
- todo/todoeditor.h
- todo/window.cpp
- todo/window.h