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

# 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

- AppLnk ()
- AppLnk ( const QString & file )
- AppLnk ( const AppLnk & copy )
- virtual ~AppLnk ()
- bool isValid () const
- QString name () const
- const QPixmap & pixmap () const
- const QPixmap & bigPixmap () const
- QString icon () const
- virtual QString exec () const
- QString type () const
- QString rotation () const
- QString comment () const
- QString file () const
- QString linkFile () const
- QStringList mimeTypes () const
- QStringList mimeTypeIcons () const
- const QArray<int> & categories () const
- int id () const
- bool fileKnown () const
- bool linkFileKnown () const
- void execute () const
- void execute ( const QStringList & args ) const
- void removeFiles ()
- void removeLinkFile ()
- void setName ( const QString & docname )
- void setExec ( const QString & exec )
- void setFile ( const QString & filename )
- void setLinkFile ( const QString & filename )
- void setComment ( const QString & comment )
- void setType ( const QString & type )
- void setIcon ( const QString & iconname )
- void setCategories ( const QArray<int> & c )
- bool writeLink () const
- void setProperty ( const QString & key, const QString & value )
- QString property ( const QString & key ) const
- bool setLocation ( const QString & docPath )
- bool isDocLnk () const
- AppLnk & operator= ( const AppLnk & copy )

## Static Public Members

- void setSmallIconSize ( int small )
- void setBigIconSize ( int big )
- int smallIconSize ()
- int bigIconSize ()

## Protected Members

- virtual void invoke ( const QStringList & args ) const
- bool ensureLinkExists () const

## 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
- Files and Links
- Functionality

### 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.

First availability: Qtopia 1.6

### 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.

First availability: Qtopia 1.6

### 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.

First availability: Qtopia 1.6

### 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 platform, copyright © 1995-2004 Trolltech, all rights reserved.