krdc/remoteview.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2002-2003 Tim Jansen <tim@tjansen.de>
   4 ** Copyright (C) 2007-2008 Urs Wolfer <uwolfer @ kde.org>
   5 **
   6 ** This file is part of KDE.
   7 **
   8 ** This program is free software; you can redistribute it and/or modify
   9 ** it under the terms of the GNU General Public License as published by
  10 ** the Free Software Foundation; either version 2 of the License, or
  11 ** (at your option) any later version.
  12 **
  13 ** This program is distributed in the hope that it will be useful,
  14 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16 ** GNU General Public License for more details.
  17 **
  18 ** You should have received a copy of the GNU General Public License
  19 ** along with this program; see the file COPYING. If not, write to
  20 ** the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  21 ** Boston, MA 02110-1301, USA.
  22 **
  23 ****************************************************************************/
  24
  25 #ifndef REMOTEVIEW_H
  26 #define REMOTEVIEW_H
  27
  28 #ifdef QTONLY
  29     #include <QUrl>
  30     #define KUrl QUrl
  31 #else
  32     #include <KUrl>
  33     #include <KWallet/Wallet>
  34 #endif
  35
  36 #include <QWidget>
  37
  38 /**
  39  * Generic widget that displays a remote framebuffer.
  40  * Implement this if you want to add another backend.
  41  *
  42  * Things to take care of:
  43  * @li The RemoteView is responsible for its size. In
  44  *     non-scaling mode, set the fixed size of the widget
  45  *     to the remote resolution. In scaling mode, set the
  46  *     maximum size to the remote size and minimum size to the
  47  *     smallest resolution that your scaler can handle.
  48  * @li if you override mouseMoveEvent()
  49  *     you must ignore the QEvent, because the KRDC widget will
  50  *     need it for stuff like toolbar auto-hide and bump
  51  *     scrolling. If you use x11Event(), make sure that
  52  *     MotionNotify events will be forwarded.
  53  *
  54  */
  55 class RemoteView : public QWidget
  56 {
  57     Q_OBJECT
  58
  59 public:
  60
  61     Q_ENUMS(Quality)
  62
  63     enum Quality {
  64         Unknown,
  65         High,
  66         Medium,
  67         Low
  68     };
  69
  70     /**
  71     * Describes the state of a local cursor, if there is such a concept in the backend.
  72     * With local cursors, there are two cursors: the cursor on the local machine (client),
  73     * and the cursor on the remote machine (server). Because there is usually some lag,
  74     * some backends show both cursors simultanously. In the VNC backend the local cursor
  75     * is a dot and the remote cursor is the 'real' cursor, usually an arrow.
  76     */
  77
  78     Q_ENUMS(DotCursorState)
  79
  80     enum DotCursorState {
  81         CursorOn,  ///< Always show local cursor (and the remote one).
  82         CursorOff, ///< Never show local cursor, only the remote one.
  83         /// Try to measure the lag and enable the local cursor if the latency is too high.
  84         CursorAuto
  85     };
  86
  87     /**
  88     * State of the connection. The state of the connection is returned
  89     * by @ref RemoteView::status().
  90     *
  91     * Not every state transition is allowed. You are only allowed to transition
  92     * a state to the following state, with three exceptions:
  93     * @li You can move from every state directly to Disconnected
  94     * @li You can move from every state except Disconnected to
  95     *     Disconnecting
  96     * @li You can move from Disconnected to Connecting
  97     *
  98     * @ref RemoteView::setStatus() will follow this rules for you.
  99     * (If you add/remove a state here, you must adapt it)
 100     */
 101
 102     Q_ENUMS(RemoteStatus)
 103
 104     enum RemoteStatus {
 105         Connecting     = 0,
 106         Authenticating = 1,
 107         Preparing      = 2,
 108         Connected      = 3,
 109         Disconnecting  = -1,
 110         Disconnected   = -2
 111     };
 112
 113     Q_ENUMS(ErrorCode)
 114
 115     enum ErrorCode {
 116         None = 0,
 117         Internal,
 118         Connection,
 119         Protocol,
 120         IO,
 121         Name,
 122         NoServer,
 123         ServerBlocked,
 124         Authentication
 125     };
 126
 127     RemoteView(QWidget *parent = 0);
 128
 129     virtual ~RemoteView();
 130
 131     /**
 132      * Checks whether the backend supports scaling. The
 133      * default implementation returns false.
 134      * @return true if scaling is supported
 135      * @see scaling()
 136      */
 137     virtual bool supportsScaling() const;
 138
 139     /**
 140      * Checks whether the widget is in scale mode. The
 141      * default implementation always returns false.
 142      * @return true if scaling is activated. Must always be
 143      *         false if @ref supportsScaling() returns false
 144      * @see supportsScaling()
 145      */
 146     virtual bool scaling() const;
 147
 148     /**
 149      * Checks whether the backend supports the concept of local cursors. The
 150      * default implementation returns false.
 151      * @return true if local cursors are supported/known
 152      * @see DotCursorState
 153      * @see showDotCursor()
 154      * @see dotCursorState()
 155      */
 156     virtual bool supportsLocalCursor() const;
 157
 158     /**
 159      * Sets the state of the dot cursor, if supported by the backend.
 160      * The default implementation does nothing.
 161      * @param state the new state (CursorOn, CursorOff or
 162      *        CursorAuto)
 163      * @see dotCursorState()
 164      * @see supportsLocalCursor()
 165      */
 166     virtual void showDotCursor(DotCursorState state);
 167
 168     /**
 169      * Returns the state of the local cursor. The default implementation returns
 170      * always CursorOff.
 171      * @return true if local cursors are supported/known
 172      * @see showDotCursor()
 173      * @see supportsLocalCursor()
 174      */
 175     virtual DotCursorState dotCursorState() const;
 176
 177     /**
 178      * Checks whether the view is in view-only mode. This means
 179      * that all input is ignored.
 180      */
 181     virtual bool viewOnly();
 182
 183     /**
 184      * Checks whether grabbing all possible keys is enabled.
 185      */
 186     virtual bool grabAllKeys();
 187
 188     /**
 189      * Returns the resolution of the remote framebuffer.
 190      * It should return a null @ref QSize when the size
 191      * is not known.
 192      * The backend must also emit a @ref changeSize()
 193      * when the size of the framebuffer becomes available
 194      * for the first time or the size changed.
 195      * @return the remote framebuffer size, a null QSize
 196      *         if unknown
 197      */
 198     virtual QSize framebufferSize();
 199
 200     /**
 201      * Initiate the disconnection. This doesn't need to happen
 202      * immediately. The call must not block.
 203      * @see isQuitting()
 204      */
 205     virtual void startQuitting();
 206
 207     /**
 208      * Checks whether the view is currently quitting.
 209      * @return true if it is quitting
 210      * @see startQuitting()
 211      * @see setStatus()
 212      */
 213     virtual bool isQuitting();
 214
 215     /**
 216      * @return the host the view is connected to
 217      */
 218     virtual QString host();
 219
 220     /**
 221      * @return the port the view is connected to
 222      */
 223     virtual int port();
 224
 225     /**
 226      * Initialize the view (for example by showing configuration
 227      * dialogs to the user) and start connecting. Should not block
 228      * without running the event loop (so displaying a dialog is ok).
 229      * When the view starts connecting the application must call
 230      * @ref setStatus() with the status Connecting.
 231      * @return true if successful (so far), false
 232      *         otherwise
 233      * @see connected()
 234      * @see disconnected()
 235      * @see disconnectedError()
 236      * @see statusChanged()
 237      */
 238     virtual bool start() = 0;
 239
 240     /**
 241      * Called when the configuration is changed.
 242      * The default implementation does nothing.
 243      */
 244     virtual void updateConfiguration();
 245
 246     /**
 247      * Returns the current status of the connection.
 248      * @return the status of the connection
 249      * @see setStatus()
 250      */
 251     RemoteStatus status();
 252
 253     /**
 254      * @return the current url
 255      */
 256     KUrl url();
 257
 258 public slots:
 259     /**
 260      * Called to enable or disable scaling.
 261      * Ignored if @ref supportsScaling() is false.
 262      * The default implementation does nothing.
 263      * @param s true to enable, false to disable.
 264      * @see supportsScaling()
 265      * @see scaling()
 266      */
 267     virtual void enableScaling(bool scale);
 268
 269     /**
 270      * Enables/disables the view-only mode.
 271      * Ignored if @ref supportsScaling() is false.
 272      * The default implementation does nothing.
 273      * @param viewOnly true to enable, false to disable.
 274      * @see supportsScaling()
 275      * @see viewOnly()
 276      */
 277     virtual void setViewOnly(bool viewOnly);
 278
 279     /**
 280      * Enables/disables grabbing all possible keys.
 281      * @param grabAllKeys true to enable, false to disable.
 282      * Default is false.
 283      * @see grabAllKeys()
 284      */
 285     virtual void setGrabAllKeys(bool grabAllKeys);
 286
 287     /**
 288      * Called to let the backend know it when
 289      * we switch from/to fullscreen.
 290      * @param on true when switching to fullscreen,
 291      *           false when switching from fullscreen.
 292      */
 293     virtual void switchFullscreen(bool on);
 294
 295     /**
 296      * Sends a QKeyEvent to the remote server.
 297      * @param event the key to send
 298      */
 299     virtual void keyEvent(QKeyEvent *event);
 300
 301     /**
 302      * Called when the visible place changed so remote
 303      * view can resize itself.
 304      */
 305     virtual void scaleResize(int w, int h);
 306
 307 signals:
 308     /**
 309      * Emitted when the size of the remote screen changes. Also
 310      * called when the size is known for the first time.
 311      * @param x the width of the screen
 312      * @param y the height of the screen
 313      */
 314     void changeSize(int w, int h);
 315
 316     /**
 317      * Emitted when the view connected successfully.
 318      */
 319     void connected();
 320
 321     /**
 322      * Emitted when the view disconnected without error.
 323      */
 324     void disconnected();
 325
 326     /**
 327      * Emitted when the view disconnected with error.
 328      */
 329     void disconnectedError();
 330
 331     /**
 332      * Emitted when the view has a specific error.
 333      */
 334     void errorMessage(const QString &title, const QString &message);
 335
 336     /**
 337      * Emitted when the status of the view changed.
 338      * @param s the new status
 339         */
 340     void statusChanged(RemoteView::RemoteStatus s);
 341
 342     /**
 343      * Emitted when the password dialog is shown or hidden.
 344      * @param b true when the dialog is shown, false when it has been hidden
 345      */
 346     void showingPasswordDialog(bool b);
 347
 348     /**
 349      * Emitted when the mouse on the remote side has been moved.
 350      * @param x the new x coordinate
 351      * @param y the new y coordinate
 352      * @param buttonMask the mask of mouse buttons (bit 0 for first mouse
 353      *                   button, 1 for second button etc)a
 354      */
 355     void mouseStateChanged(int x, int y, int buttonMask);
 356
 357 protected:
 358     void focusInEvent(QFocusEvent *event);
 359     void focusOutEvent(QFocusEvent *event);
 360
 361     /**
 362      * The status of the remote view.
 363      */
 364     RemoteStatus m_status;
 365
 366     /**
 367      * Set the status of the connection.
 368      * Emits a statusChanged() signal.
 369      * Note that the states need to be set in a certain order,
 370      * see @ref Status. setStatus() will try to do this
 371      * transition automatically, so if you are in Connecting
 372      * and call setStatus(Preparing), setStatus() will
 373      * emit a Authenticating and then Preparing.
 374      * If you transition backwards, it will emit a
 375      * Disconnected before doing the transition.
 376      * @param s the new status
 377      */
 378     virtual void setStatus(RemoteStatus s);
 379
 380     QCursor localDotCursor() const;
 381
 382     QString m_host;
 383     int m_port;
 384     bool m_viewOnly;
 385     bool m_grabAllKeys;
 386     bool m_scale;
 387     bool m_keyboardIsGrabbed;
 388     KUrl m_url;
 389
 390 #ifndef QTONLY
 391     QString readWalletPassword(bool fromUserNameOnly = false);
 392     void saveWalletPassword(const QString &password, bool fromUserNameOnly = false);
 393     KWallet::Wallet *m_wallet;
 394 #endif
 395
 396     DotCursorState m_dotCursorState;
 397 };
 398
 399 #endif