Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded |

# Qtopia Data Linking - Specification

- Introduction
- Definitions
- Overview
- Services
- Link format
- Client Responsibilities
- Link Resolution
- Global Find
- Questions and answers

## Introduction

People frequently want to associate data from one application with another application. Consider the following cases:

- I create an appointment in my calendar with Joe and Mary. Later when thinking about the meeting, I want to read the notes I've written about Joe.
- I want to associate a contact with my appointment so I can quickly ring them when the alarm goes off.
- I create a todo based on an email I got, so I associate the email with the todo in order to allow a quick reply when the action is complete.

This document attempts to provide a high-level solution to the problem of data linking. This document will be used as a basis for an implementation of data linking in Qtopia. For implementation details, please see The QDL Protocol.

## Definitions

QDL | Qtopia Data Linking is the name given to the protocol/applications that govern data linking in the Qtopia environment.
QDL Source | The application providing the link
QDL Client | The application embedding the link
Link ID | A number of superscript characters (0-9) that are logically connected to the non-user visible Data References.

## Overview

Qtopia needs a consistent, global, application-independent way of associating data from one application with another. The application embedding the link should not need special knowledge of the source application. A typical link embed operation is outlined below:

- User is entering text in a QDL-supported field
- User selects "insert link..." from the context menu
- User selects the application that will provide the link
- The Client requests a link from the Source, optionally sending text to help the Source
- The Source prompts the user for a record to link
- The Source sends the link to the Client

QDL-support is required in a text field since not all fields will be appropriate for data linking. This support will likely be via a flag in the text editing widgets. Support for linking is not likely to be restricted to text editing widgets, however such an implementation is outside the scope of this paper. An application must register itself as a QDL Source with the Qtopia services framework. It is assumed that any text can be sent to the Source as a hint. The Source is responsible for using the data in a sensible way. An example of a hint is typing someone's name before selecting the address book as the Source. Assuming a name was sent to the address book, it may be able to identify the record the user wants. The Source must prompt the user even if the hint makes it obvious what the user wants. A list of choices should be presented, allowing the user to select the desired record. For example, using the address book as the Source, the user would be shown the addresses address book thinks are likely matches (based on the hint) what the user wants. The Source should allow the user to easily select records that did not match the hint. The user will of course want to activate links that have been created. A typical link activation operation is outlined below:

- The user is viewing a record with embedded links
- The user selects a link
- Client sends a message to the Source, requesting the link be displayed
- The Source opens and displays the linked data

## Services

Qtopia has a services mechanism whereby applications can notify the system that they support particular qcop messages. QDL Source applications will need to register as supporting the create link function in order to appear in the list of applications given to the user.

## Link format

The link that is sent to the Client should include the following:

Application Reference | This identifies the Source. It is used when activating a link. This is not shown to the user.
Data Reference | This uniquely identifies some data to the Source. It is used when activating a link. This is not shown to the user.
Descriptive Text | This is added to the text field so the user is able to see what the link is to.
Icon | This is shown in rich text views as part (possibly all) of the link.

## Client Responsibilities

In order to maximise consistency between applications, the Client is expected to act in particular ways with regards to links. While these points are not requirements of using QDL, they are recommended to minimize user confusion.

- When a link is embedded, the Client will place the descriptive text and a generated Link ID into the text widget.
- The user can delete or modify the descriptive text at will without invalidating the link. Only removing the Link ID will remove the link.
- The Client must provide a way to view it's records in rich text controls. (Preview mode)
- When viewing the record in preview mode, the Link ID should be replaced with the appropriate icon and made into a selectable link. If the text before the Link ID matches the descriptive text from the link, it should also be part of the link.
- The Client must ensure Link ID values are unique.
- A Client should check the record's link storage after it's text fields have been edited to ensure links are deleted when their Link ID values are removed.
- The link request must include a reference to the Client so the Source can send the link.
- The Client is responsible for ensuring bogus Link ID values are handled in a sensible way (for example, creating a dummy link to nothing). This prevents link problems when copying/moving text or when the user manually places superscript characters in a text field.

## Link Resolution

When the user selects a link, the Client activates that link by sending a message to the Application Reference with the Data Reference. The Source should open itself and display the indicated record. If the Source cannot find a record to display it will display an error message to the user. The Source should try to minimize the chance that a link will become invalid. Deleting a linked record is an example that would cause a link to become invalid.

## Global Find

It should be obvious that the infrastructure required to support data linking also lends itself to a Global Find function. In this case, the Client is the find application and it requests links from all Sources. It then displays the possible choices to the user. When the user selects a link, the find application activates the link, taking the user to the record they searched for. The biggest problem with QDL for Global Find is the reliance on the Source to present the list of choices to the user. A special link request could be used to obtain a list of links from the Source. The descriptive text and icon should be enough for the user to identify the records. A get all links message will be required of a Source to work with Global Find.

## Questions and answers

- Should Link IDs be prevented from getting on the clipboard? No. Insert a dummy link for each Link ID that is not accounted for. This also prevents issues when users insert superscript characters manually.
- Does Qtopia have a services framework? Yes
- Should the link contain a pixmap or a path to a pixmap or an application name (and the application's icon gets used)? Something that can be passed to Resource::loadIconSet(...);
- Should the clipboard be extended to allow links to be placed on it? No. Moving text in the same field should be possible (since the field checks for Link IDs after the editing operation is complete) but copying a link to another application is not supported.