lib

KoSpeaker Class Reference

#include <KoSpeaker.h>

List of all members.


Detailed Description

KoSpeaker is a singleton object that provides Text-to-Speech services for KOffice applications.

When activated, it will speak the text of widgets under the mouse pointer and/or the the widget with focus.

It also provides some methods for speaking text from documents.

IMPORTANT: This class will be removed from KOffice when KOffice is converted to KDE4. It will be replaced with a proper screen reading capability using the AT-SPI.

This is quite a hack and doesn't work reliably. The following are current problems: 1. Cannot speak menu items in a QMenuBar (top menu of app). 2. Doesn't understand every possible widget.

This capability is not intended for completely blind users. Such users cannot use KDE 3.x anyway, since it lacks a screen reader. Instead, this capability is intended as an aid to users with other vision disabilities.

KOffice applications can access this object using the kospeaker global.

Definition at line 63 of file KoSpeaker.h.


Public Types

 SpeakFocusWidget = 0x0001
 SpeakPointerWidget = 0x0002
 SpeakWhatsThis = 0x0004
 SpeakTooltip = 0x0008
 SpeakAccelerator = 0x0010
 SpeakDisabled = 0x0020
enum  SpeakFlags {
  SpeakFocusWidget = 0x0001, SpeakPointerWidget = 0x0002, SpeakWhatsThis = 0x0004, SpeakTooltip = 0x0008,
  SpeakAccelerator = 0x0010, SpeakDisabled = 0x0020
}

Signals

void customSpeakNewWidget (QWidget *w, const QPoint &p, uint flags)
void customSpeakWidget (QWidget *w, const QPoint &p, uint flags)

Public Member Functions

 KoSpeaker ()
 ~KoSpeaker ()
bool isEnabled () const
void readConfig (KConfig *config)
bool maybeSayWidget (QWidget *w, const QPoint &pos=QPoint())
bool sayWidget (const QString &msg)
void cancelSpeakWidget ()
void queueSpeech (const QString &msg, const QString &langCode=QString(), bool first=true)
void startSpeech ()

Static Public Member Functions

static bool isKttsdInstalled ()
static KoSpeakerkoSpeaker ()

Static Protected Attributes

static KoSpeakerKSpkr = 0L

Member Enumeration Documentation

Speech Options.

Enumerator:
SpeakFocusWidget  Speak widget with focus.
SpeakPointerWidget  Speak widget under mouse pointer.
SpeakWhatsThis  Speak Whats This if available.
SpeakTooltip  Speak tooltip if available.
SpeakAccelerator  Speak accelerator.
SpeakDisabled  Say 'disabled' if not enabled.

Definition at line 71 of file KoSpeaker.h.


Member Function Documentation

void KoSpeaker::cancelSpeakWidget (  ) 

Cancels speaking of widget.

Usually called by slots that receive customSpeakNewWidget signal when they wish to speak the widget themselves.

void KoSpeaker::customSpeakNewWidget ( QWidget *  w,
const QPoint &  p,
uint  flags 
) [signal]

This signal is emitted whenever a new widget has received focus or the mouse pointer has moved to a new widget.

If a receiver wishes to handle speaking of the widget itself, it should call cancelSpeakWidget() .

Parameters:
w The widget.
p Mouse pointer global coordinates, or in the case of a focus change (0,0).
flags Speech options. SpeakFlags.
IMPORTANT: This signal is emitted from the maybeSayWidget method. Slots who call maybeSayWidget should take care to avoid infinite recursion.

void KoSpeaker::customSpeakWidget ( QWidget *  w,
const QPoint &  p,
uint  flags 
) [signal]

This signal is emitted each polling interval when KoSpeaker did not speak the widget (either because it did not think the widget was a new one or because it did not understand the widget).

If both mouse pointer and focus flags are set, it may emit twice per polling interval.

Parameters:
w The widget.
p Mouse pointer global coordinates, or in the case of a focus change (0,0).
flags Speech options. SpeakFlags.
IMPORTANT: This signal is emitted frequently. Receivers should be coded efficiently.

bool KoSpeaker::isEnabled (  )  const

Returns true if TTS services are available.

If KTTSD daemon is not running, it is started. Will return false if: -- KTTSD daemon is not installed, or -- Was not able to start KTTSD daemon for some reason.

Definition at line 130 of file KoSpeaker.cpp.

bool KoSpeaker::isKttsdInstalled (  )  [static]

Returns whether the KTTSD deamon is installed in the system.

If not, apps should disable or hide options/commands to speak.

Definition at line 476 of file KoSpeaker.cpp.

static KoSpeaker* KoSpeaker::koSpeaker (  )  [inline, static]

Returns the KoSpeaker object singleton.

Apps should use "kospeaker" rather than this function directly.

Definition at line 145 of file KoSpeaker.h.

bool KoSpeaker::maybeSayWidget ( QWidget *  w,
const QPoint &  pos = QPoint() 
)

Given a widget w and its pos screen coordinates, tries to extract the text of the widget and speak it.

If pos is not specified, and the widget has multiple parts (such as a QListView), uses the current part. Call isEnabled to ensure TTS is available before calling this method.

Definition at line 219 of file KoSpeaker.cpp.

void KoSpeaker::queueSpeech ( const QString &  msg,
const QString &  langCode = QString(),
bool  first = true 
)

Queue a msg as a speech text job.

The text is encoded in the langCode language. Examples "en", "es", "en_US". If not specified, defaults to current desktop setting. If first is true and a job is already speaking, cancel it. If first is false, appends to the already queued job. If the KTTSD daemon is not already running, it is started.

Definition at line 157 of file KoSpeaker.cpp.

void KoSpeaker::readConfig ( KConfig *  config  ) 

Reads configuration options from config object and starts TTS if screen reader capability is requested.

If KTTSD daemon is not installed, isEnabled will return false. If screen reader is requested and KTTSD is installed, but not running, it will be started.

Definition at line 196 of file KoSpeaker.cpp.

bool KoSpeaker::sayWidget ( const QString &  msg  ) 

Speak a msg that came from a widget, such as the widget's text label, tool tip, etc.

Speaks using ScreenReaderOutput, which has highest priority, and therefore, should only be be used in very time-sensitive contexts and for short messages. Certain standard substitutions are performed on the message. For example, "Ctrl+" becomes "control plus". "Qt" markup is stripped.

Returns:
true if anything is actually spoken. Call isEnabled to ensure TTS is available before calling this method.

Definition at line 430 of file KoSpeaker.cpp.

void KoSpeaker::startSpeech (  ) 

Start speaking queued text job (if any).

Definition at line 190 of file KoSpeaker.cpp.


The documentation for this class was generated from the following files:
KDE Home | KDE Accessibility Home | Description of Access Keys