1 | /**************************************************************************** |
2 | |
3 | Copyright (C) 2003 Lubos Lunak <l.lunak@kde.org> |
4 | |
5 | Permission is hereby granted, free of charge, to any person obtaining a |
6 | copy of this software and associated documentation files (the "Software"), |
7 | to deal in the Software without restriction, including without limitation |
8 | the rights to use, copy, modify, merge, publish, distribute, sublicense, |
9 | and/or sell copies of the Software, and to permit persons to whom the |
10 | Software is furnished to do so, subject to the following conditions: |
11 | |
12 | The above copyright notice and this permission notice shall be included in |
13 | all copies or substantial portions of the Software. |
14 | |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL |
18 | THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
20 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
21 | DEALINGS 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 | */ |
45 | class 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 , long ); |
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 | */ |
155 | class 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 | |