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 // #include <kkeynative.h>
  23 #include "events.h"
  24
  25 typedef enum {
  26   QUALITY_UNKNOWN=0,
  27   QUALITY_HIGH=1,
  28   QUALITY_MEDIUM=2,
  29   QUALITY_LOW=3
  30 } Quality;
  31
  32 /**
  33  * Describes the state of a local cursor, if there is such a concept in the backend.
  34  * With local cursors, there are two cursors: the cursor on the local machine (client),
  35  * and the cursor on the remote machine (server). Because there is usually some lag,
  36  * some backends show both cursors simultanously. In the VNC backend the local cursor
  37  * is a dot and the remote cursor is the 'real' cursor, usually an arrow.
  38  */
  39 enum DotCursorState {
  40         DOT_CURSOR_ON,  ///< Always show local cursor (and the remote one).
  41         DOT_CURSOR_OFF, ///< Never show local cursor, only the remote one.
  42         /// Try to measure the lag and enable the local cursor if the latency is too high.
  43         DOT_CURSOR_AUTO
  44 };
  45
  46 /**
  47  * Generic widget that displays a remote framebuffer.
  48  * Implement this if you want to add another backend.
  49  *
  50  * Things to take care of:
  51  * @li The KRemoteView is responsible for its size. In
  52  *     non-scaling mode, set the fixed size of the widget
  53  *     to the remote resolution. In scaling mode, set the
  54  *     maximum size to the remote size and minimum size to the
  55  *     smallest resolution that your scaler can handle.
  56  * @li if you override mouseMoveEvent()
  57  *     you must ignore the QEvent, because the KRDC widget will
  58  *     need it for stuff like toolbar auto-hide and bump
  59  *     scrolling. If you use x11Event(), make sure that
  60  *     MotionNotify events will be forwarded.
  61  *
  62  */
  63 class KRemoteView : public QWidget
  64 {
  65         Q_OBJECT
  66 public:
  67         KRemoteView(QWidget *parent = 0,
  68                     const char *name = 0,
  69                     Qt::WFlags f = 0);
  70
  71         virtual ~KRemoteView();
  72
  73         /**
  74          * Checks whether the backend supports scaling. The
  75          * default implementation returns false.
  76          * @return true if scaling is supported
  77          * @see scaling()
  78          */
  79         virtual bool supportsScaling() const;
  80
  81         /**
  82          * Checks whether the widget is in scale mode. The
  83          * default implementation always returns false.
  84          * @return true if scaling is activated. Must always be
  85          *         false if @ref supportsScaling() returns false
  86          * @see supportsScaling()
  87          */
  88         virtual bool scaling() const;
  89
  90         /**
  91          * Checks whether the backend supports the concept of local cursors. The
  92          * default implementation returns false.
  93          * @return true if local cursors are supported/known
  94          * @see DotCursorState
  95          * @see showDotCursor()
  96          * @see dotCursorState()
  97          */
  98         virtual bool supportsLocalCursor() const;
  99
 100         /**
 101          * Sets the state of the dot cursor, if supported by the backend.
 102          * The default implementation does nothing.
 103          * @param state the new state (DOT_CURSOR_ON, DOT_CURSOR_OFF or
 104          *        DOT_CURSOR_AUTO)
 105          * @see dotCursorState()
 106          * @see supportsLocalCursor()
 107          */
 108         virtual void showDotCursor(DotCursorState state);
 109
 110         /**
 111          * Returns the state of the local cursor. The default implementation returns
 112          * always DOT_CURSOR_OFF.
 113          * @return true if local cursors are supported/known
 114          * @see showDotCursor()
 115          * @see supportsLocalCursor()
 116          */
 117         virtual DotCursorState dotCursorState() const;
 118
 119         /**
 120          * Checks whether the view is in view-only mode. This means
 121          * that all input is ignored.
 122          */
 123         virtual bool viewOnly() = 0;
 124
 125         /**
 126          * Returns the resolution of the remote framebuffer.
 127          * It should return a null @ref QSize when the size
 128          * is not known.
 129          * The backend must also emit a @ref changeSize()
 130          * when the size of the framebuffer becomes available
 131          * for the first time or the size changed.
 132          * @return the remote framebuffer size, a null QSize
 133          *         if unknown
 134          */
 135         virtual QSize framebufferSize() = 0;
 136
 137         /**
 138          * Initiate the disconnection. This doesn't need to happen
 139          * immediately. The call must not block.
 140          * @see isQuitting()
 141          */
 142         virtual void startQuitting() = 0;
 143
 144         /**
 145          * Checks whether the view is currently quitting.
 146          * @return true if it is quitting
 147          * @see startQuitting()
 148          * @see setStatus()
 149          */
 150         virtual bool isQuitting() = 0;
 151
 152         /**
 153          * Returns the host the view is connected to.
 154          * @return the host the view is connected to
 155          */
 156         virtual QString host() = 0;
 157
 158         /**
 159          * Returns the port the view is connected to.
 160          * @return the port the view is connected to
 161          */
 162         virtual int port() = 0;
 163
 164         /**
 165          * Initialize the view (for example by showing configuration
 166          * dialogs to the user) and start connecting. Should not block
 167          * without running the event loop (so displaying a dialog is ok).
 168          * When the view starts connecting the application must call
 169          * @ref setStatus() with the status REMOTE_VIEW_CONNECTING.
 170          * @return true if successful (so far), false
 171          *         otherwise
 172          * @see connected()
 173          * @see disconnected()
 174          * @see disconnectedError()
 175          * @see statusChanged()
 176          */
 177         virtual bool start() = 0;
 178
 179         /**
 180          * Returns the current status of the connection.
 181          * @return the status of the connection
 182          * @see setStatus()
 183          */
 184         enum RemoteViewStatus status();
 185
 186 public slots:
 187         /**
 188          * Called to enable or disable scaling.
 189          * Ignored if @ref supportsScaling() is false.
 190          * The default implementation does nothing.
 191          * @param s true to enable, false to disable.
 192          * @see supportsScaling()
 193          * @see scaling()
 194          */
 195         virtual void enableScaling(bool s);
 196
 197         /**
 198          * Enables/disables the view-only mode.
 199          * Ignored if @ref supportsScaling() is false.
 200          * The default implementation does nothing.
 201          * @param s true to enable, false to disable.
 202          * @see supportsScaling()
 203          * @see viewOnly()
 204          */
 205         virtual void setViewOnly(bool s) = 0;
 206
 207         /**
 208          * Called to let the backend know it when
 209          * we switch from/to fullscreen.
 210          * @param on true when switching to fullscreen,
 211          *           false when switching from fullscreen.
 212          */
 213         virtual void switchFullscreen(bool on);
 214
 215         /**
 216          * Sends a key to the remote server.
 217          * @param k the key to send
 218          */
 219         virtual void pressKey(XEvent *k) = 0;
 220
 221 signals:
 222         /**
 223          * Emitted when the size of the remote screen changes. Also
 224          * called when the size is known for the first time.
 225          * @param x the width of the screen
 226          * @param y the height of the screen
 227          */
 228         void changeSize(int w, int h);
 229
 230         /**
 231          * Emitted when the view connected successfully.
 232          */
 233         void connected();
 234
 235         /**
 236          * Emitted when the view disconnected without error.
 237          */
 238         void disconnected();
 239
 240         /**
 241          * Emitted when the view disconnected with error.
 242          */
 243         void disconnectedError();
 244
 245         /**
 246          * Emitted when the status of the view changed.
 247          * @param s the new status
 248          */
 249         void statusChanged(RemoteViewStatus s);
 250
 251         /**
 252          * Emitted when the password dialog is shown or hidden.
 253          * @param b true when the dialog is shown, false when it has
 254          *               been hidden
 255          */
 256         void showingPasswordDialog(bool b);
 257
 258         /**
 259          * Emitted when the mouse on the remote side has been moved.
 260          * @param x the new x coordinate
 261          * @param y the new y coordinate
 262          * @param buttonMask the mask of mouse buttons (bit 0 for first mouse
 263          *                   button, 1 for second button etc)a
 264          */
 265         void mouseStateChanged(int x, int y, int buttonMask);
 266
 267 protected:
 268         /**
 269          * The status of the remote view.
 270          */
 271         enum RemoteViewStatus m_status;
 272
 273         /**
 274          * Set the status of the connection.
 275          * Emits a statusChanged() signal.
 276          * Note that the states need to be set in a certain order,
 277          * see @ref RemoteViewStatus. setStatus() will try to do this
 278          * transition automatically, so if you are in REMOTE_VIEW_CONNECTING
 279          * and call setStatus(REMOTE_VIEW_PREPARING), setStatus() will
 280          * emit a REMOTE_VIEW_AUTHENTICATING and then REMOTE_VIEW_PREPARING.
 281          * If you transition backwards, it will emit a
 282          * REMOTE_VIEW_DISCONNECTED before doing the transition.
 283          * @param s the new status
 284          */
 285         virtual void setStatus(RemoteViewStatus s);
 286 };
 287
 288 #endif