1/* -*- c++ -*-
2 * Copyright (C)2000 Daniel M. Duley <mosfet@kde.org>
3 *
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 *
15 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 * SUCH DAMAGE.
26 *
27 */
28#ifndef __KRECENTDOCUMENT_H
29#define __KRECENTDOCUMENT_H
30
31#include <kio/kio_export.h>
32
33#include <QtCore/QString>
34#include <kurl.h>
35
36/**
37 * Manage the "Recent Document Menu" entries displayed by
38 * applications such as Kicker and Konqueror.
39 *
40 * These entries are automatically generated .desktop files pointing
41 * to the current application and document. You should call the
42 * static add() method whenever the user opens or saves a new
43 * document if you want it to show up in the menu.
44 *
45 * You don't have to worry about this if you are using any
46 * KFileDialog derived class to open and save documents, as it
47 * already calls this class. User defined limits on the maximum
48 * number of documents to save, etc... are all automatically handled.
49 *
50 * @author Daniel M. Duley <mosfet@kde.org>
51 */
52class KIO_EXPORT KRecentDocument
53{
54public:
55
56 /**
57 *
58 * Return a list of absolute paths to recent document .desktop files,
59 * sorted by date.
60 *
61 */
62 static QStringList recentDocuments();
63
64 /**
65 * Add a new item to the Recent Document menu.
66 *
67 * @param url The url to add.
68 */
69 static void add(const KUrl& url);
70
71 /**
72 * Add a new item to the Recent Document menu, specifying the application to open it with.
73 * The above add() method uses KGlobal::mainComponent().componentName() for the app name,
74 * which isn't always flexible enough.
75 * This method is used when an application launches another one to open a document.
76 *
77 * @param url The url to add.
78 * @param desktopEntryName The desktopEntryName of the service to use for opening this document.
79 */
80 static void add(const KUrl& url, const QString& desktopEntryName);
81
82 /**
83 *
84 * Add a new item to the Recent Document menu. Calls add( url ).
85 *
86 * @param documentStr The full path to the document or URL to add.
87 * @param isURL Set to @p true if @p documentStr is an URL and not a local file path.
88 */
89 static void add(const QString &documentStr, bool isURL = false);
90
91 /**
92 * Clear the recent document menu of all entries.
93 */
94 static void clear();
95
96 /**
97 * Returns the maximum amount of recent document entries allowed.
98 */
99 static int maximumItems();
100
101 /**
102 * Returns the path to the directory where recent document .desktop files
103 * are stored.
104 */
105 static QString recentDocumentDirectory();
106};
107
108#endif
109