home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kkbdaccessextensions.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-30  |  7.4 KB  |  176 lines
  1. /** @file
  2. *   This file is part of the KDE/KOffice project.
  3. *   Copyright (C) 2005, Gary Cramblitt <garycramblitt@comcast.net>
  4. *
  5. *   @author Gary Cramblitt <garycramblitt@comcast.net>
  6. *   @since KOffice 1.5
  7. *
  8. *   This library is free software; you can redistribute it and/or
  9. *   modify it under the terms of the GNU Library General Public
  10. *   License as published by the Free Software Foundation; either
  11. *   version 2 of the License, or (at your option) any later version.
  12. *
  13. *   This library 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 GNU
  16. *   Library General Public License for more details.
  17. *
  18. *   You should have received a copy of the GNU Library General Public License
  19. *   along with this library; see the file COPYING.LIB.  If not, write to
  20. *   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  21. *   Boston, MA 02110-1301, USA.
  22. */
  23.  
  24. #ifndef __KKBDACCESSEXTENSIONS_H__
  25. #define __KKBDACCESSEXTENSIONS_H__
  26.  
  27. // Qt includes.
  28. #include <qobject.h>
  29.  
  30. // KOffice includes.
  31. #include <koffice_export.h>
  32.  
  33. class KKbdAccessExtensionsPrivate;
  34. class QWidgetList;
  35. class KMainWindow;
  36.  
  37. /** KKbdAccessExtensions is an object that improves accessibility for motor impaired users
  38. *   who may not be able to easily use a mouse.  It adds two new capabilities using the keyboard:
  39. *
  40. *     - Resizing and positioning of panel widgets derived from QSplitter and QDockWindow.
  41. *     - Setting focus to any widget that accepts focus.
  42. *
  43. *   @section sizing_mode Sizing Mode
  44. *
  45. *   Users may press F8 or Shift-F8 (defaults) to enter sizing mode.  A sizing icon appears on the first
  46. *   QSplitter or QDockWindow handle found in the application (F8) or the last such handle (Shift+F8).
  47. *   (A "handle" is the divider bar that appears to the left, right, above, or below each panel
  48. *   of a QSplitter or QDockArea.)
  49. *
  50. *   Once in sizing mode, the following functions are available via the keyboard:
  51. *
  52. *     - F8          Moves to the next sizing handle.  After the last handle, exits sizing mode.
  53. *     - Shift+F8    Moves to the previous sizing handle.  After the first handle, exits sizing mode.
  54. *     - Esc         Exits sizing mode.
  55. *     - LeftArrow   When on a vertical sizing handle, moves the handle to the left.
  56. *                   When on a horizontal sizing handle, moves the handle up.
  57. *     - RightArrow  When on a vertical sizing handle, moves the handle to the right.
  58. *                   When on a horizontal sizing handle, moves the handle down.
  59. *     - UpArrow     When on a vertical sizing handle, moves the handle to the left.
  60. *                   When on a horizontal sizing handle, moves the handle up.
  61. *     - DownArrow   When on a vertical sizing handle, moves the handle to the right.
  62. *                   When on a horizontal sizing handle, moves the handle down.
  63. *     - PgUp        Like LeftArrow or UpArrow, but moves the handle 5X farther to the left or up.
  64. *     - PgDn        Like RightArrow or DownArrow, but moves the handle 5X farther to the right or down.
  65. *     - Enter       (On numeric keypad).  When on the handle of a QDockWindow, undocks or docks
  66. *                   the widget.  Ignored when on the handle of a QSplitter.
  67. *
  68. *   The default step size for each arrow key press is 10 pixels.
  69. *
  70. *   When a QDockWindow is undocked, the sizing icon appears in the center of the window.
  71. *   The arrow keys and PgUp/PgDn move the undocked window on the screen.  Shifted arrow keys
  72. *   and PgUp/PgDn decrease/increase the size of the undocked window.
  73. *
  74. *   When the sizing icon is on a sizing handle, the mouse may also be used to move the handle
  75. *   without having to click and drag.  When moving the mouse while sizing icon is on an undocked
  76. *   QDockWindow, the window moves with the mouse.  Holding Shift down while moving the mouse
  77. *   sizes the QDockWindow.
  78. *
  79. *   @note Users can also move and size undocked windows using the Window Operations Menu (Alt+F3).
  80. *
  81. *   Clicking any mouse button exits sizing mode.
  82. *
  83. *   When entering sizing mode, the position of the mouse cursor is saved and restored when
  84. *   exiting sizing mode.
  85. *
  86. *   For a QSplitter or QDockWindow to be found, it must be in the kapp::allWidgets() list.
  87. *
  88. *   @section focus_setting Focus Setting
  89. *
  90. *   Users can press Alt-F8.  A small box appears in the upperleft corner of each visible widget
  91. *   on the screen that can accept focus.  Each box is assigned a single letter or digit.
  92. *   User can press the corresponding key to set focus to the widget.
  93. *
  94. *   At most 36 such shortcuts are possible.  If any application shortcuts are single letters
  95. *   or digits, those shortcuts are not in any of the boxes.
  96. *
  97. *   Clicking any mouse button exits Focus Setting mode.
  98. *
  99. *   @section notes Notes
  100. *
  101. *   The F8, Shift+F8, and Alt+F8 keys are KShortcuts and therefore user may choose different keys in
  102. *   the application's Configure Shortcuts dialog.
  103. *
  104. *   @note At present, these shortcuts may not be multi-key.  If user sets multi-key
  105. *   shortcuts, they will not work.
  106. *
  107. *   F8/Shift+F8 are the default shortcuts because these are the keys used for similar
  108. *   functionality in GNOME and Java SWT.
  109. */
  110. class KOFFICECORE_EXPORT KKbdAccessExtensions : public QObject
  111. {
  112.     // TODO: A .moc isn't really needed right now, but see TODO in eventFilter method.
  113.     // Q_PROPERTY(int stepSize READ stepSize WRITE setStepSize)
  114.  
  115.     public:
  116.         /** Constructor.
  117.         *   @param parent       KMainWindow of the application.  Required.
  118.         *   @param name         (optional) Name of this object.
  119.         */
  120.         KKbdAccessExtensions(KMainWindow* parent, const char* name = 0);
  121.  
  122.         /** Destructor. */
  123.         virtual ~KKbdAccessExtensions();
  124.  
  125.         /** Returns number of pixels panel is sized for each arrow key pressed.  Default is 10. */
  126.         int stepSize() const;
  127.         /** Sets number of pixels panel is sized for each arrow key pressed. */
  128.         void setStepSize(int s);
  129.  
  130.     protected:
  131.         /** Event filter installed on kapp object. */
  132.         bool eventFilter( QObject *o, QEvent *e );
  133.  
  134.         /** Retrieves a list of all Splitter and DockArea widgets in the application. */
  135.         QWidgetList* getAllPanels();
  136.         /** Advances to the next Panel handle.  If not currently in resizing mode,
  137.             turns it on. */
  138.         void nextHandle();
  139.         /** Moves to the previous Panel handle.  If not currently in resizing mode,
  140.             turns it on. */
  141.         void prevHandle();
  142.         /** Exits Sizing mode. */
  143.         void exitSizing();
  144.         /** Moves panel handle based on key pressed. */
  145.         void resizePanelFromKey(int key, int state);
  146.         /** Moves panel handle based on deltaX and deltaY and state of keyboard modifier keys. */
  147.         void resizePanel(int dx, int dy, int state);
  148.         /** Displays the sizer icon. */
  149.         void showIcon();
  150.         /** Hides the sizer icon. */
  151.         void hideIcon();
  152.  
  153.         /** Displays the access keys. */
  154.         void displayAccessKeys();
  155.         /** Handles an access keypress. */
  156.         bool handleAccessKey( const QKeyEvent* ev );
  157.  
  158.     private:
  159.         KKbdAccessExtensionsPrivate* d;
  160. };
  161.  
  162. /** Provides a way to sort QLabelss using a QValueList based on their screen position. */
  163. class KSortedLabel
  164. {
  165. public:
  166.     KSortedLabel(QLabel* l);
  167.     KSortedLabel();    // default constructor
  168.     bool operator<( KSortedLabel l);
  169.     QLabel* label() { return m_l; }
  170.  
  171. private:
  172.     QLabel* m_l;
  173. };
  174.  
  175. #endif              // __KKBDACCESSEXTENSIONS_H__
  176.