/** @file
* This file is part of the KDE/KOffice project.
* Copyright (C) 2005, Gary Cramblitt <garycramblitt@comcast.net>
*
* @author Gary Cramblitt <garycramblitt@comcast.net>
* @since KOffice 1.5
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public License
* along with this library; see the file COPYING.LIB. If not, write to
* the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301, USA.
*/
#ifndef __KKBDACCESSEXTENSIONS_H__
#define __KKBDACCESSEXTENSIONS_H__
// TQt includes.
#include <tqobject.h>
// KOffice includes.
#include <koffice_export.h>
class KKbdAccessExtensionsPrivate;
class TQWidgetList;
class TDEMainWindow;
/** KKbdAccessExtensions is an object that improves accessibility for motor impaired users
* who may not be able to easily use a mouse. It adds two new capabilities using the keyboard:
*
* - Resizing and positioning of panel widgets derived from TQSplitter and TQDockWindow.
* - Setting focus to any widget that accepts focus.
*
* @section sizing_mode Sizing Mode
*
* Users may press F8 or Shift-F8 (defaults) to enter sizing mode. A sizing icon appears on the first
* TQSplitter or TQDockWindow handle found in the application (F8) or the last such handle (Shift+F8).
* (A "handle" is the divider bar that appears to the left, right, above, or below each panel
* of a TQSplitter or TQDockArea.)
*
* Once in sizing mode, the following functions are available via the keyboard:
*
* - F8 Moves to the next sizing handle. After the last handle, exits sizing mode.
* - Shift+F8 Moves to the previous sizing handle. After the first handle, exits sizing mode.
* - Esc Exits sizing mode.
* - LeftArrow When on a vertical sizing handle, moves the handle to the left.
* When on a horizontal sizing handle, moves the handle up.
* - RightArrow When on a vertical sizing handle, moves the handle to the right.
* When on a horizontal sizing handle, moves the handle down.
* - UpArrow When on a vertical sizing handle, moves the handle to the left.
* When on a horizontal sizing handle, moves the handle up.
* - DownArrow When on a vertical sizing handle, moves the handle to the right.
* When on a horizontal sizing handle, moves the handle down.
* - PgUp Like LeftArrow or UpArrow, but moves the handle 5X farther to the left or up.
* - PgDn Like RightArrow or DownArrow, but moves the handle 5X farther to the right or down.
* - Enter (On numeric keypad). When on the handle of a TQDockWindow, undocks or docks
* the widget. Ignored when on the handle of a TQSplitter.
*
* The default step size for each arrow key press is 10 pixels.
*
* When a TQDockWindow is undocked, the sizing icon appears in the center of the window.
* The arrow keys and PgUp/PgDn move the undocked window on the screen. Shifted arrow keys
* and PgUp/PgDn decrease/increase the size of the undocked window.
*
* When the sizing icon is on a sizing handle, the mouse may also be used to move the handle
* without having to click and drag. When moving the mouse while sizing icon is on an undocked
* TQDockWindow, the window moves with the mouse. Holding Shift down while moving the mouse
* sizes the TQDockWindow.
*
* @note Users can also move and size undocked windows using the Window Operations Menu (Alt+F3).
*
* Clicking any mouse button exits sizing mode.
*
* When entering sizing mode, the position of the mouse cursor is saved and restored when
* exiting sizing mode.
*
* For a TQSplitter or TQDockWindow to be found, it must be in the kapp::allWidgets() list.
*
* @section focus_setting Focus Setting
*
* Users can press Alt-F8. A small box appears in the upperleft corner of each visible widget
* on the screen that can accept focus. Each box is assigned a single letter or digit.
* User can press the corresponding key to set focus to the widget.
*
* At most 36 such shortcuts are possible. If any application shortcuts are single letters
* or digits, those shortcuts are not in any of the boxes.
*
* Clicking any mouse button exits Focus Setting mode.
*
* @section notes Notes
*
* The F8, Shift+F8, and Alt+F8 keys are TDEShortcuts and therefore user may choose different keys in
* the application's Configure Shortcuts dialog.
*
* @note At present, these shortcuts may not be multi-key. If user sets multi-key
* shortcuts, they will not work.
*
* F8/Shift+F8 are the default shortcuts because these are the keys used for similar
* functionality in GNOME and Java SWT.
*/
class KOFFICECORE_EXPORT KKbdAccessExtensions : public TQObject
{
// TODO: A .moc isn't really needed right now, but see TODO in eventFilter method.
// TQ_PROPERTY(int stepSize READ stepSize WRITE setStepSize)
public:
/** Constructor.
* @param parent TDEMainWindow of the application. Required.
* @param name (optional) Name of this object.
*/
KKbdAccessExtensions(TDEMainWindow* parent, const char* name = 0);
/** Destructor. */
virtual ~KKbdAccessExtensions();
/** Returns number of pixels panel is sized for each arrow key pressed. Default is 10. */
int stepSize() const;
/** Sets number of pixels panel is sized for each arrow key pressed. */
void setStepSize(int s);
protected:
/** Event filter installed on kapp object. */
bool eventFilter( TQObject *o, TQEvent *e );
/** Retrieves a list of all Splitter and DockArea widgets in the application. */
TQWidgetList* getAllPanels();
/** Advances to the next Panel handle. If not currently in resizing mode,
turns it on. */
void nextHandle();
/** Moves to the previous Panel handle. If not currently in resizing mode,
turns it on. */
void prevHandle();
/** Exits Sizing mode. */
void exitSizing();
/** Moves panel handle based on key pressed. */
void resizePanelFromKey(int key, int state);
/** Moves panel handle based on deltaX and deltaY and state of keyboard modifier keys. */
void resizePanel(int dx, int dy, int state);
/** Displays the sizer icon. */
void showIcon();
/** Hides the sizer icon. */
void hideIcon();
/** Displays the access keys. */
void displayAccessKeys();
/** Handles an access keypress. */
bool handleAccessKey( const TQKeyEvent* ev );
private:
KKbdAccessExtensionsPrivate* d;
};
/** Provides a way to sort TQLabelss using a TQValueList based on their screen position. */
class KSortedLabel
{
public:
KSortedLabel(TQLabel* l);
KSortedLabel(); // default constructor
bool operator<( KSortedLabel l);
TQLabel* label() { return m_l; }
private:
TQLabel* m_l;
};
#endif // __KKBDACCESSEXTENSIONS_H__