1/****************************************************************************
2
3 Copyright (C) 2003 Lubos Lunak <l.lunak@kde.org>
4
5Permission is hereby granted, free of charge, to any person obtaining a
6copy of this software and associated documentation files (the "Software"),
7to deal in the Software without restriction, including without limitation
8the rights to use, copy, modify, merge, publish, distribute, sublicense,
9and/or sell copies of the Software, and to permit persons to whom the
10Software is furnished to do so, subject to the following conditions:
11
12The above copyright notice and this permission notice shall be included in
13all copies or substantial portions of the Software.
14
15THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
18THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
21DEALINGS IN THE SOFTWARE.
22
23****************************************************************************/
24
25#ifndef KMANAGERSELECTION_H
26#define KMANAGERSELECTION_H
27
28#include <kdeui_export.h>
29#include <QtCore/QObject>
30
31#ifdef Q_WS_X11 // FIXME(E)
32
33#include <X11/Xlib.h>
34#include <fixx11h.h>
35
36
37/**
38 This class implements claiming and owning manager selections, as described
39 in the ICCCM, section 2.8. The selection atom is passed to the constructor,
40 claim() attemps to claim ownership of the selection, release() gives up
41 the selection ownership. Signal lostOwnership() is emitted when the selection
42 is claimed by another owner.
43 @short ICCCM manager selection owner
44*/
45class KDEUI_EXPORT KSelectionOwner
46 : public QObject
47 {
48 Q_OBJECT
49 public:
50 /**
51 * This constructor initializes the object, but doesn't perform any
52 * operation on the selection.
53 *
54 * @param selection atom representing the manager selection
55 * @param screen X screen, or -1 for default
56 * @param parent parent object, or NULL if there is none
57 */
58 explicit KSelectionOwner( Atom selection, int screen = -1, QObject* parent = NULL );
59 /**
60 * @overload
61 * This constructor accepts the selection name and creates the appropriate atom
62 * for it automatically.
63 *
64 * @param selection name of the manager selection
65 * @param screen X screen, or -1 for default
66 * @param parent parent object, or NULL if there is none
67 */
68 explicit KSelectionOwner( const char* selection, int screen = -1, QObject* parent = NULL );
69 /**
70 * Destructor. Calls release().
71 */
72 virtual ~KSelectionOwner();
73 /**
74 * This function attemps to claim ownership of the manager selection, using
75 * the current X timestamp. If @p force is false, and the selection is already
76 * owned, the selection is not claimed, and false is returned. If claiming
77 * is forced and the selection is owned by another client, it is waited for up to 1 second
78 * for the previous owner to disown the selection, if @p force_kill is true,
79 * and the previous owner fails to disown the selection in time,
80 * it will be forcibly killed. True is returned after successfully claiming
81 * ownership of the selection.
82 */
83 bool claim( bool force, bool force_kill = true );
84 /**
85 * If the selection is owned, the ownership is given up.
86 */
87 void release();
88 /**
89 * If the selection is owned, returns the window used internally
90 * for owning the selection.
91 */
92 Window ownerWindow() const; // None if not owning the selection
93 /**
94 * @internal
95 */
96 bool filterEvent( XEvent* ev_P ); // internal
97 Q_SIGNALS:
98 /**
99 * This signal is emitted if the selection was owned and the ownership
100 * has been lost due to another client claiming it, this signal is emitted.
101 * IMPORTANT: It's not safe to delete the instance in a slot connected
102 * to this signal.
103 */
104 void lostOwnership();
105 protected:
106 /**
107 * Called for every X event received on the window used for owning
108 * the selection. If true is returned, the event is filtered out.
109 */
110 virtual bool handleMessage( XEvent* ev );
111 /**
112 * Called when a SelectionRequest event is received. A reply should
113 * be sent using the selection handling mechanism described in the ICCCM
114 * section 2.
115 *
116 * @param target requested target type
117 * @param property property to use for the reply data
118 * @param requestor requestor window
119 */
120 virtual bool genericReply( Atom target, Atom property, Window requestor );
121 /**
122 * Called to announce the supported targets, as described in the ICCCM
123 * section 2.6. The default implementation announces the required targets
124 * MULTIPLE, TIMESTAMP and TARGETS.
125 */
126 virtual void replyTargets( Atom property, Window requestor );
127 /**
128 * Called to create atoms needed for claiming the selection and
129 * communication using the selection handling mechanism. The default
130 * implementation must be called if reimplemented. This method
131 * may be called repeatedly.
132 */
133 virtual void getAtoms();
134 /**
135 * Sets extra data to be sent in the message sent to root window
136 * after successfully claiming a selection. These extra data
137 * are in data.l[3] and data.l[4] fields of the XClientMessage.
138 */
139 void setData( long extra1, long extra2 );
140 private:
141 void filter_selection_request( XSelectionRequestEvent& ev_P );
142 bool handle_selection( Atom target_P, Atom property_P, Window requestor_P );
143
144 class Private;
145 Private* const d;
146 };
147
148/**
149 This class implements watching manager selections, as described in the ICCCM
150 section 2.8. It emits signal newOwner() when a new owner claim the selection,
151 and emits lostOwner() when the selection ownership is given up. To find
152 out current owner of the selection, owner() can be used.
153 @short ICCCM manager selection watching
154*/
155class KDEUI_EXPORT KSelectionWatcher
156 : public QObject
157 {
158 Q_OBJECT
159 public:
160 /**
161 * This constructor initializes the object, but doesn't perform any
162 * operation on the selection.
163 *
164 * @param selection atom representing the manager selection
165 * @param screen X screen, or -1 for default
166 * @param parent parent object, or NULL if there is none
167 */
168 explicit KSelectionWatcher( Atom selection, int screen = -1, QObject* parent = NULL );
169 /**
170 * @overload
171 * This constructor accepts the selection name and creates the appropriate atom
172 * for it automatically.
173 *
174 * @param selection name of the manager selection
175 * @param screen X screen, or -1 for default
176 * @param parent parent object, or NULL if there is none
177 */
178 explicit KSelectionWatcher( const char* selection, int screen = -1, QObject* parent = NULL );
179 virtual ~KSelectionWatcher();
180 /**
181 * Return the current owner of the manager selection, if any. Note that if the event
182 * informing about the owner change is still in the input queue, newOwner() might
183 * have been emitted yet.
184 */
185 Window owner();
186 /**
187 * @internal
188 */
189 void filterEvent( XEvent* ev_P ); // internal
190 Q_SIGNALS:
191 /**
192 * This signal is emitted when the selection is successfully claimed by a new
193 * owner.
194 * @param owner the new owner of the selection
195 */
196 void newOwner( Window owner );
197 /**
198 * This signal is emitted when the selection is given up, i.e. there's no
199 * owner. Note that the selection may be immediatelly claimed again,
200 * so the newOwner() signal may be emitted right after this one.
201 * It's safe to delete the instance in a slot connected to this signal.
202 */
203 void lostOwner();
204 private:
205 void init();
206
207 class Private;
208 Private* const d;
209 };
210
211#endif
212#endif
213