Qt API | Qtopia API Qtopia Documentation

AppLnk Class Reference

The AppLnk class represents an application available on the system. More...

#include <qtopia/applnk.h>

Inherited by DocLnk and DocLnk.

List of all member functions.

Public Members

Static Public Members

Protected Members


Detailed Description

The AppLnk class represents an application available on the system.

Every Qtopia application app has a corresponding app.desktop file. When one of these files is read its data is stored as an AppLnk object.

The AppLnk class introduces some Qtopia-specific concepts, and provides a variety of functions, as described in the following sections.

Types

Every AppLnk object has a type. For applications, games and settings the type is Application; for documents the type is the document's MIME type.

Files and Links

When you create an AppLnk (or more likely, a DocLnk), you don't deal directly with filenames in the filesystem. Instead you do this:

    DocLnk d;
    d.setType("text/plain");
    d.setName("My Nicely Named Document / Whatever"); // Yes, "/" is legal.
    
At this point, the file() and linkFile() are unknown. Normally this is uninteresting, and the names become automatically known, and more importantly, becomes reserved, when you ask what they are:

    QString fn = d.file();
    
This invents a filename, and creates the file on disk (an empty reservation file) to prevent the name being used by another application.

In some circumstances, you don't want to create the file if it doesn't already exist (e.g. in the Document tab, some of the DocLnk objects represented by icons are DocLnk's created just for that view - they don't have corresponding .desktop files. To avoid littering empty reservation files around, we check in a few places to see whether the file really needs to exist).

Functionality

AppLnk objects are created by calling the constructor with the name of a .desktop file. The object can be checked for validity using isValid().

The following functions are used to set or retrieve information about the application:

Get Function Set Function Short Description
name() setName() application's name
pixmap() none application's icon
bigPixmap() none application's large icon
none setIcon() sets the icon's filename
type() setType() see Types above
rotation() none 0, 90, 180 or 270 degrees
comment() setComment() text for the Details dialog
exec() setExec() executable's filename
file() none document's filename
linkFile() setLinkFile() .desktop filename
mimeTypes() none the mime types the application can view or edit
categories() setCategories() see the function descriptions
fileKnown() none see Files and Links above
linkFileKnown() none see Files and Links above
property() setProperty() any AppLnk property can be retrieved or set (if writeable) using these

To save an AppLnk to disk use writeLink(). To execute the application that the AppLnk object refers to, use execute().

AppLnk's can be deleted from disk using removeLinkFile(). To remove both the link and the application's executable use removeFiles().

Icon sizes can be globally changed (but only for AppLnk objects created after the calls) with setSmallIconSize() and setBigIconSize().

See also Qtopia Classes.


Member Function Documentation

AppLnk::AppLnk ()

Creates an invalid AppLnk.

See also isValid().

AppLnk::AppLnk ( const QString & file )

Loads file (e.g. app.desktop) as an AppLnk.

See also writeLink().

AppLnk::AppLnk ( const AppLnk & copy )

Copies copy.

AppLnk::~AppLnk () [virtual]

Destroys the AppLnk. Note that if the AppLnk is currently a member of an AppLnkSet, this will produce a run-time warning.

See also AppLnkSet::add() and AppLnkSet::remove().

int AppLnk::bigIconSize () [static]

Returns the size used for large icons.

See also setBigIconSize() and setIcon().

const QPixmap & AppLnk::bigPixmap () const

Returns a large pixmap associated with the application.

See also pixmap() and setIcon().

const QArray<int> & AppLnk::categories () const

Returns a shallow copy of the Categories property.

See the CategoryWidget for more details.

See also setCategories().

QString AppLnk::comment () const

Returns the Comment property.

See also setComment().

bool AppLnk::ensureLinkExists () const [protected]

Attempts to ensure that the link file for this AppLnk exists, including creating any required directories. Returns TRUE if successful; otherwise returns FALSE.

You should not need to use this function.

QString AppLnk::exec () const [virtual]

Returns the Exec property. This is the name of the executable program associated with the AppLnk.

See also setExec().

void AppLnk::execute ( const QStringList & args ) const

Executes the application associated with this AppLnk, with args as arguments.

See also exec().

void AppLnk::execute () const

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Executes the application associated with this AppLnk.

See also exec().

QString AppLnk::file () const

Returns the file associated with the AppLnk.

See also exec() and name().

bool AppLnk::fileKnown () const

Returns TRUE is the file associated with AppLnk is already known. If FALSE, calling file() will generate a file name.

QString AppLnk::icon () const

Returns the Icon property.

See also setIcon().

int AppLnk::id () const

Returns the id of the AppLnk. If the AppLnk is not in an AppLnkSet, this value is 0, otherwise it is a value that is unique for the duration of the current process.

See also AppLnkSet::find().

void AppLnk::invoke ( const QStringList & args ) const [virtual protected]

Invokes the application associated with this AppLnk, with args as arguments. Rotation is not taken into account by this function, so you should not call it directly.

See also execute().

bool AppLnk::isDocLnk () const

Returns TRUE if the AppLnk is a DocLnk.

bool AppLnk::isValid () const

Returns TRUE if this AppLnk is valid; otherwise returns FALSE.

QString AppLnk::linkFile () const

Returns the desktop file corresponding to this AppLnk.

See also file(), exec() and name().

bool AppLnk::linkFileKnown () const

Returns TRUE is the link file associated with AppLnk is already known. If FALSE, calling linkFile() will generate a file name.

QStringList AppLnk::mimeTypeIcons () const

Returns the MimeTypeIcons property of the AppLnk.

QStringList AppLnk::mimeTypes () const

Returns the MimeTypes property. This is the list of MIME types that the application can view or edit.

QString AppLnk::name () const

Returns the Name property. This is the user-visible name for the document or application, not the filename.

See Files and Links.

See also setName().

AppLnk & AppLnk::operator= ( const AppLnk & copy )

Returns an AppLnk that is a deep copy of copy.

const QPixmap & AppLnk::pixmap () const

Returns a small pixmap associated with the application.

See also bigPixmap() and setIcon().

QString AppLnk::property ( const QString & key ) const

Returns the property named key.

See also setProperty().

void AppLnk::removeFiles ()

Deletes both the linkFile() and the file() associated with this AppLnk.

See also removeLinkFile().

void AppLnk::removeLinkFile ()

Deletes the linkFile(), leaving any file() untouched.

See also removeFiles().

QString AppLnk::rotation () const

Returns the Rotation property. The value is 0, 90, 180 or 270 degrees.

void AppLnk::setBigIconSize ( int big ) [static]

Sets the size used for large icons to big pixels. Only affects AppLnk objects created after the call.

See also bigIconSize() and setIcon().

void AppLnk::setCategories ( const QArray<int> & c )

Sets the Categories property to c.

See the CategoryWidget for more details.

See also categories().

void AppLnk::setComment ( const QString & comment )

Sets the Comment property to comment.

This text is displayed in the 'Details Dialog', for example if the user uses the 'press-and-hold' gesture.

See also comment().

void AppLnk::setExec ( const QString & exec )

Sets the Exec property to exec.

See also exec() and name().

void AppLnk::setFile ( const QString & filename )

Sets the File property to filename.

See also file() and name().

void AppLnk::setIcon ( const QString & iconname )

Sets the Icon property to iconname. This is the filename from which the pixmap() and bigPixmap() are obtained.

See also icon(), setSmallIconSize() and setBigIconSize().

void AppLnk::setLinkFile ( const QString & filename )

Sets the LinkFile property to filename.

See also linkFile().

bool AppLnk::setLocation ( const QString & docPath )

This function sets the location for an AppLnk to docPath.

void AppLnk::setName ( const QString & docname )

Sets the Name property to docname.

See also name().

void AppLnk::setProperty ( const QString & key, const QString & value )

Sets the property named key to value.

See also property().

void AppLnk::setSmallIconSize ( int small ) [static]

Sets the size used for small icons to small pixels. Only affects AppLnk objects created after the call.

See also smallIconSize() and setIcon().

void AppLnk::setType ( const QString & type )

Sets the Type property to type.

For applications, games and settings the type should be Application; for documents the type should be the document's MIME type.

See also type().

int AppLnk::smallIconSize () [static]

Returns the size used for small icons.

See also setSmallIconSize() and setIcon().

QString AppLnk::type () const

Returns the type of the AppLnk. For applications, games and settings the type is Application; for documents the type is the document's MIME type.

bool AppLnk::writeLink () const

Commits the AppLnk to disk. Returns TRUE if the operation succeeded; otherwise returns FALSE.

In addition, the "linkChanged(QString)" message is sent to the "QPE/System" QCop channel.


This file is part of the Qtopia , copyright © 1995-2002 Trolltech, all rights reserved.


Copyright © 2001-2002 TrolltechTrademarks
Qtopia version 1.7.0