summaryrefslogtreecommitdiffstats
path: root/kdeui/qxembed.h
blob: c9dcac05dae6decd1d345b94f793b1566f9e193b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
/****************************************************************************
    Definition of QXEmbed class

   Copyright (C) 1999-2000 Troll Tech AS

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.
*****************************************************************************/

#ifndef QXEMBED_H
#define QXEMBED_H

#include <tqwidget.h>
#include <kdelibs_export.h>

#ifdef Q_MOC_RUN
#define Q_WS_X11
#endif // Q_MOC_RUN

#ifdef Q_WS_X11

class QXEmbedData;

/**
 * A QXEmbed widget serves as an embedder that can manage one single embedded
 * X-window. These so-called client windows can be arbitrary Qt or non Qt
 * applications.
 *
 * There are two different ways of using QXEmbed,
 * from the client side or from the embedder's side.
 * 
 * Embedding from the client's side requires that the client knows the
 * window identifier of the respective embedder widget. Use either
 * embedClientIntoWindow() or the high-level wrapper processClientCmdline().
 * This is only possible when the client is a Qt application.
 *
 * When using it from the embedder's side, you must know the window 
 * identifier of the window that should be embedded. Simply call embed() 
 * with this identifier as parameter.  If the client is a Qt application,
 * make sure it has called QXEmbed::initialize(). Otherwise you should
 * probably call setProtocol(XPLAIN) before embed().
 * 
 * Reimplement the change handler windowChanged() to catch embedding or
 * the destruction of embedded windows. In the latter case, the
 * embedder also emits a signal embeddedWindowDestroyed() for
 * convenience.
 *
 * @short The QXEmbed widget is a graphical socket that can embed an external X-Window.
*/
class KDEUI_EXPORT QXEmbed : public TQWidget
{
    Q_OBJECT
    TQ_OBJECT

public:

    /**
     *
     * Constructs a xembed widget.
     *
     * The parent, name and f arguments are passed to the QFrame
     * constructor.
     */
    QXEmbed( TQWidget *parent=0, const char *name=0, WFlags f = 0 );

    /**
     * Destructor. Cleans up the focus if necessary.
     */
    ~QXEmbed();

    /**
     * Embedded applications should call this function to make sure
     * they support the XEMBED protocol. It is called automatically
     * when you use embedClientIntoWindow() or
     * processClientCmdline(). Clients might have to call it
     * manually when you use embed().
     */
    static void initialize();

    enum Protocol { XEMBED, XPLAIN };

    /**
     * Sets the protocol used for embedding windows.
     * This function must be called before embedding a window.
     * Protocol XEMBED provides maximal functionality (focus, tabs, etc)
     * but requires explicit cooperation from the embedded window.
     * Protocol XPLAIN provides maximal compatibility with
     * embedded applications that do not support the XEMBED protocol.
     * The default is XEMBED.
     *
     * Non KDE applications should be embedded with protocol XPLAIN. 
     * This does not happen automatically yet. 
     * You must call setProtocol() explicitly.
     */

    void setProtocol( Protocol proto );

    /**
     * Returns the protocol used for embedding the current window.
     *
     * @return the protocol used by QXEmbed.
     */

    Protocol protocol();

    /**
     * Embeds the window with the identifier w into this xembed widget.
     *
     * This function is useful if the embedder knows about the client window
     * that should be embedded.  Often it is vice versa: the client knows
     * about its target embedder. In that case, it is not necessary to call
     * embed(). Instead, the client will call the static function
     * embedClientIntoWindow().
     *
     * @param w the identifier of the window to embed
     * @see embeddedWinId()
     */
    void embed( WId w );

    /**
     * Returns the window identifier of the embedded window, or 0 if no
     * window is embedded yet.
     *
     * @return the id of the embedded window (0 if no window is embedded)
     */
    WId embeddedWinId() const;

    /**
     * A function for clients that embed themselves. The widget
     * client will be embedded in the window window. The application has
     * to ensure that window is the handle of the window identifier of
     * an QXEmbed widget.
     *
     * @short #processClientCmdline()
     */
    static void embedClientIntoWindow( TQWidget* client, WId window );

    /**
     * A utility function for clients that embed theirselves. The widget
     * client will be embedded in the window that is passed as
     * -embed command line argument.
     *
     * The function returns true on success or false if no such command line
     * parameter is specified.
     *
     * @see embedClientIntoWindow()
     */
    static bool processClientCmdline( TQWidget* client, int& argc, char ** argv );

    /** 
     * Sends a WM_DELETE_WINDOW message to the embedded window.  This is what
     * typically happens when you click on the close button of a window
     * manager decoration.  This should cause the embedded application to
     * cleanly close the window.  Signal embeddedWindowDestroyed() can be used
     * to monitor the status of the embedded window.
     */
    void sendDelete( void );
    
    /**
     * Selects what shoud be done with the embedded window when the embedding
     * window is destroyed.  When the argument is true, the embedded window is
     * kept alive, is hidden, and receives a WM_DELETE_WINDOW message using
     * sendDelete().  This is the default.  Otherwise, the destruction of the
     * QXEmbed object simply destroys the embedded window.
     *
     * @see sendDelete()
     */
    void setAutoDelete( bool );

    /**
     * Returns the value of flag indicating what shoud be done with the
     * embedded window when the embedding window is destroyed.
     * 
     * @see setAutoDelete()
     */
    bool autoDelete() const;

    /* Reimp */
    TQSize tqsizeHint() const;
    TQSize tqminimumSizeHint() const;
    TQSizePolicy sizePolicy() const;
    bool eventFilter( TQObject *, TQEvent * );
    bool customWhatsThis() const;
    void enterWhatsThisMode(); // temporary, fix in Qt (Matthias, Mon Jul 17 15:20:55 CEST 2000  )
    virtual void reparent( TQWidget * parent, WFlags f, const TQPoint & p, bool showIt = false );

    /**
     * @internal
     */
    void updateEmbeddedFocus( bool hasfocus );

signals:
    /**
     * This signal is emitted when the embedded window has been lost (destroyed or reparented away)
     *
     * @see embeddedWinId()
     */
    // KDE4 rename to embeddedWindowLost()
    void embeddedWindowDestroyed();

protected:
    bool event( TQEvent * );
    void keyPressEvent( TQKeyEvent * );
    void keyReleaseEvent( TQKeyEvent * );
    void focusInEvent( TQFocusEvent * );
    void focusOutEvent( TQFocusEvent * );
    void resizeEvent(TQResizeEvent *);
    void showEvent( TQShowEvent * );
    bool x11Event( XEvent* );

    /**
     * A change handler that indicates that the embedded window has been
     * changed.  The window handle can also be retrieved with
     * embeddedWinId().
     *
     * @param w the handle of the window that changed
     */
    virtual void windowChanged( WId w );

    bool focusNextPrevChild( bool next );

private:
    WId window;
    QXEmbedData* d;
    void checkGrab();
    void sendSyntheticConfigureNotifyEvent();
    void handleEmbed();
};


#endif
#endif