krdc/kremoteview.h

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