Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference

Qtopia Data Linking (QDL)

Introduction

Qtopia Data Linking (QDL) provides an API to associate or "link" data items across applications. A QDLLink is conceptually the same as an ordinary anchor on a webpage. A QDLLink has information which uniquely references an object somewhere in the same application, or another Qtopia application. When the user clicks the link the referenced object is accessed. For example, using QDL a user can create a meeting event in Calendar and a link to each person attending the meeting from Contacts. When the event is viewed, hypertext links appear for each linked Contact. Activating a link sends a message to the Contacts application to display that contact.

How it Works

The linking process begins when the user edits a QDL enabled text field such as a QLineEdit or QMultiLineEdit. These text fields are called the client in QDL and interface through an associated QDLWidgetClient object for QDL operations.

The user selects an Insert Link context menu option in the text field which is connected to the QDLClient::requestLink() slot. This displays a dialog listing all applications providing a QDL service. These are called QDL sources. The user selects an application which cotains the data they wish to link to.

QDLClient::requestLink() then sends a request for links over QCop to the selected source. Typically, the source application will present the user with a list of items available for linking and the user then selects the desired items from the list. However, the source may carry out any specific processing required to determine the set of links.

Once a source has determined the items to be linked it creates links for all of the items and sends them back to the client. The client receives the links and inserts them into the text.

The inserted links are displayed in editing mode as superscript numbers to the right of the description for the link. These numbers called link identifiers (LIDs) act as markers to inform the user that the text to the left is internally marked as a link and is treated specially.

When the user views text containing links the link identifier markers are replaced with hypertext anchors. The links work like links on a standard webpage - clicking them accesses the object they refer to.

Enabling Linking in a Text Field

To enable linking from a text field, create a QDLWidgetClient with the text field as its parent, for example:

    QLineEdit *notesLE = new QLineEdit( parent );
    QDLWidgetClient *notesWC = new QDLWidgetClient( notesLE );
#ifdef QTOPIA_PHONE
    //setup a standard context menu item on phone
    notesWC->setupStandardContextMenu();
#endif

QDLWidgetClient::setupStandardContextMenu() automatically creates an Insert Link menu item and connects it to QDLWidgetClient::requestLink().

Loading and Saving Links

Links in QDL are commonly stored in PimRecord custom fields. However, overloaded QDataStream insertion and extraction operators are provided for a QList of QDLClients to permit links to be stored in a user-defined location.

For example: the following loads all links from a PimRecord rec into all QDL clients that are children of parent.

    QDL::loadLinks( rec.customField( QDL::DATA_KEY ), QDL::clients( parent ) );

Saving links is exactly the same, except QDL::saveLinks() is called.

For more information about the convenient loading and saving functions, see General QDL Usage .

Displaying and Activating Links

The following describes the method used to display and activate links.

  1. Convert the superscript link identifiers in txt based on the links stored in the PimRecord rec.

           QDLClient *client = new QDLClient( 0, "qdlNotes" );
           QDL::loadLinks( rec.customField( QDL::DATA_KEY ), client );
           txt = QDL::lidsToAnchors( txt, client );
           delete client;
       

    Note: The base class QDLClient is used instead of the subclass QDLWidgetClient. Unlike QDLWidgetClient, QDLClient is a stand-alone object for handling links.

  2. Activate a link.

Enabling an Application to be a QDL Source

A source is a Qtopia application that provides the QDL Service and responds to particular QCop messages. The two messages a source must respond to are:

When enabling an application as a QDL source, the application must exist as part of the QDL Qtopia Service. See Qtopia Services for more information.

For QDLActivateLink the only argument is the data reference to activate. For QDLRequestLink(QString,QString) the first argument is a unique ID used when responding to the client's request, and the second argument is a hint for which links the user might be interested in (eg. the start of a person's name). The source responds to the client with the QCop message QDLProvideLink(QString,int,...) where the first QString argument is the ID sent in the request, the second int argument is the number of QDLLinks being sent, and the third variable length parameter is a series of QDLLink objects. Responses to a client are sent on the QCop channel specified by QDL::CLIENT_CHANNEL .

These messages should be handled in response to the QPEApplication::appMessage() signal. The following is an example of the typical handling of these messages:

void MyApplication::appMessage( const QCString &msg, const QByteArray &data )
{
    QDataStream stream( data );
    if( msg == "QDLRequestLink(QString,QString)" )
    {
        QCString clientID;
        QString hint;
        stream >> clientID >> hint;

        QDLHeartBeat hb( clientID ); //sends keep alive messages to the client

        MyDataSelector *selDlg = new MyDataSelector( (isVisible() ? this : 0 ) );
        selDlg->setFilter( hint );
        if( QPEApplication::execDialog( selDlg ) )
        {
            //User selected items to link to. Create the link data from 
            //them and send it all back to the client.
            QCopEnvelope e( QDL::CLIENT_CHANNEL, "QDLProvideLink(QString,int,...)" );
            QValueList<MyData> selectedItems = selDlg->selected();
            e << selectedItems.count(); //how many links we have
            QValueList<MyData>::Iterator it;
            for( it = selectedItems.begin() ; it != selectedItems().end() ; ++it )
            {
                QByteArray dataRef;
                QDataStream refStream( dataRef, IO_WriteOnly );
                refStream << (*it).uid().toString();
                QDLLink newLink("myapplication", dataRef, (*it).name(), "MyAppIcon");
                e << newLink;
            }
        }
        delete selDlg;
    }
    else if( msg == "QDLActivateLink(QByteArray)" )
    {
        QByteArray dataRef;
        stream >> dataRef;
        QDataStream refStream( dataRef, IO_ReadOnly );
        QString dataRefStr;
        refStream >> dataRefStr;
        displayItem( dataRefStr );//display the item specified by the dataRef
    }

See also QDL, QDLLink, QDLClient, QDLHeartBeat, and Service.


Copyright © 2005 Trolltech Trademarks
Qtopia version 2.2.0