krdc/remoteview.h

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