Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 234 insertions, 0 deletions

diff --git a/kdeui/qxembed.h b/kdeui/qxembed.h
new file mode 100644
index 000000000..40772d801
--- /dev/null
+++ b/kdeui/qxembed.h
@@ -0,0 +1,234 @@
+/****************************************************************************
+    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 <qwidget.h>
+#include <kdelibs_export.h>
+
+#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 QWidget
+{
+    Q_OBJECT
+
+public:
+
+    /**
+     *
+     * Constructs a xembed widget.
+     *
+     * The parent, name and f arguments are passed to the QFrame
+     * constructor.
+     */
+    QXEmbed( QWidget *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( QWidget* 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( QWidget* 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 */
+    QSize sizeHint() const;
+    QSize minimumSizeHint() const;
+    QSizePolicy sizePolicy() const;
+    bool eventFilter( QObject *, QEvent * );
+    bool customWhatsThis() const;
+    void enterWhatsThisMode(); // temporary, fix in Qt (Matthias, Mon Jul 17 15:20:55 CEST 2000  )
+    virtual void reparent( QWidget * parent, WFlags f, const QPoint & p, bool showIt = false );
+
+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( QEvent * );
+    void keyPressEvent( QKeyEvent * );
+    void keyReleaseEvent( QKeyEvent * );
+    void focusInEvent( QFocusEvent * );
+    void focusOutEvent( QFocusEvent * );
+    void resizeEvent(QResizeEvent *);
+    void showEvent( QShowEvent * );
+    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