KProperty

KPropertyEditorItemEvent.h
1/* This file is part of the KDE project
2 Copyright (C) 2018 Jarosław Staniek <staniek@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 * Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KPROPERTYEDITORITEMEVENT_H
21#define KPROPERTYEDITORITEMEVENT_H
22
23#include "kpropertywidgets_export.h"
24
25#include <QVariant>
26
27#include <QScopedPointer>
28
29class KProperty;
30class QVariant;
31
32/**
33 * @brief The KPropertyEditorItemEvent class describes request for handling a single property
34 * editor widget item's event
35 *
36 * Handling editor events is useful to customize behavior of the property editors.
37 *
38 * For example Url property editor can offer overriding the default file dialog.
39 *
40 * Currently supported events are:
41 * - "getOpenFileUrl" for editors of KProperty::Url. Overrides the default file dialog for files
42 * or directories. For this event own file dialog can be displayed. In this case event's result
43 * should be set to result of the file dialog. Note that even if the dialog has been canceled
44 * result should be set (to empty QUrl), otherwise the property editor will not "realize" that
45 * the dialog has been overriden and will display the built-in dialog.
46 * It is recommended to take values of the "fileMode" and "confirmOverwrites" property options
47 * into account and display file dialog in appropriate mode. See KProperty::setOption() for
48 * documentation of property options.
49 * This event provides the following parameters: "url" equal to QUrl value of the editor for use
50 * in the dialog as default value; "caption" equal to the default window's caption for
51 * the dialog, depending on variant of the dialog, e.g. "Select Existing File" if "fileMode"
52 * option is "existingfile".
53 *
54 * @see KPropertyEditorView::handlePropertyEditorItemEvent()
55 *
56 * @since 3.2
57 */
58class KPROPERTYWIDGETS_EXPORT KPropertyEditorItemEvent
59{
60public:
61 /**
62 * Creates a new request object.
63 *
64 * @param property Property related to the request
65 * @param name Name of the event
66 * @param parameters Parameters of the event
67 */
68 KPropertyEditorItemEvent(const KProperty &property, const QString &name,
69 const QVariantMap &parameters);
70
72
73 /**
74 * @brief Returns property assiciated with editor which requests the override
75 */
76 const KProperty *property() const;
77
78 /**
79 * @brief Returns name of event that requests the override
80 */
81 QString name() const;
82
83 /**
84 * @brief Returns zero or more parameters associated with this specific event
85 *
86 * See description of the KPropertyEditorItemEvent class for parameters supported by given
87 * events.
88 */
89 QVariantMap parameters() const;
90
91 /**
92 * @brief Sets result of the event
93 *
94 * In order to override behavior of the editor users have to call this method even if the
95 * result is null. Editor will note that and accept the override. For example, URL editor will
96 * not attempt to display its built-in file dialog assuming that custom dialog has been used.
97 *
98 * Once setResult() is called for given event object, there is no way to unset the result.
99 * it is only possible to replace the result with other.
100 */
101 void setResult(const QVariant &result);
102
103 /**
104 * @brief Returns result set by the user of the editor
105 *
106 * It is null until user sets result with setResult().
107 *
108 * @see hasResult()
109 */
110 QVariant result() const;
111
112 /**
113 * @brief Returns @c true if event's result has been set with setResult()
114 *
115 * @see result()
116 */
117 bool hasResult() const;
118
119private:
120 Q_DISABLE_COPY(KPropertyEditorItemEvent)
121 class Private;
123};
124
125#endif
The KPropertyEditorItemEvent class describes request for handling a single property editor widget ite...
The base class representing a single property.
Definition KProperty.h:96
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:41:55 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.