00001
00002
00003
00004
00005
00006
00008
00009
00353 ,
00389 GetMenuBar()));
00390 @endcode
00391
00392 If your application has a frame menu bar, and you pass it to AxShortcutsMenuItem, its labels will be updated appropriately when the user assigns
00393 a different shortcut.
00394
00395 You can use the identifiers defined in ax_menu.h, and you can also use your own identifiers. Many of the standard identifiers are
00396 handled by event handlers in AxAdapter, but you can add your own event handlers to either your main frame class or (if you need them to
00397 be active even when modal dialogs are shown) to your application class.
00398
00399
00400 @section page_using_speech Using text to speech
00401
00402 @subsection page_using_speech_tts wxTextToSpeech
00403
00404 AxTk uses the wxTextToSpeech class, which is implemented separately from core AxTk but is currently included with the AxTk distribution.
00405 wxTextToSpeech does not implement a specific speech engine, but instead supports an extensible handler system that makes
00406 use of existing speech engines. Currently, wxTextToSpeech has handlers for Microsoft SAPI 5.1, Apple Speech Synthesis Manager,
00407 eSpeak, and Cepstral. The handlers for the latter two engines use an external process to drive a command line version of the engine.
00408
00409 @subsection page_using_speech_axtk AxTk and speech
00410
00411 AxTk abstracts its speech capabilities a step further with the AxSpeech class that can handle up to two instances of wxTextToSpeech.
00412 AxSpeech normally processes speech requests in idle time, which allows for utterances to be overridden by more pertinent ones
00413 if necessary, before speech synthesis of the old speech event has started.
00414
00415 To speak some text, you can create an AxSpeechEvent object and pass it to AxSpeech, or you can
00416 use the convenience function AxSpeech::Say to directly pass the text. The AxSpeechEvent objects
00417 are processed (in idle time) by instances of AxSpeechEventHandler which make up an event handler chain.
00418 By default, AxSpeech sets the handler to AxStandardSpeechEventHandler. Your application can call AxSpeech::Push to
00419 insert a different handler at the front of the chain, and process speech events in a custom way by overriding
00420 AxSpeechEventHandler::ProcessSpeechEvent.
00421
00422 An AxSpeechEvent has a string event type, which takes values such as AxSpeechEventActivateItem, AxSpeechEventRefreshMenu,
00423 and AxSpeechEventText. Types such as AxSpeechEventActivateItem require the speech text to be constructed
00424 from current values such as the current menu item, whereas AxSpeechEventText indicates a simple text string.
00425
00426 AxSpeechEvent contains a flag field, which consists of flags as follows:
00427
00428 @li AxSpeechFlagsPurge: purges previous speech events in the speech channel specified by the event.
00429 @li AxSpeechFlagsPurgeAll: purges previous speech events on all channels
00430 @li AxSpeechFlagsInviolate: don't allow this event to be purged
00431 @li AxSpeechFlagsImmediate: start speaking immediately instead of waiting until system is idle
00432 @li AxSpeechFlagsContentChannel: use content channel instead of main channel
00433
00434 You can use the simple AxSpeech::Say function to speak text:
00435
00436 @code
00437 GetViewManager().GetSpeech().Say(_("Welcome to the Eh Ex Tee Kay sample!"),
00438 AxSpeechFlagsInviolate);
00439 @endcode
00440
00441 or you can create and pass an event object:
00442
00443 @code
00444 AxSpeechEvent event;
00445
00446
00447
00448 event.SetVerbosityPolicy(describeAtVerbosity);
00449 event.SetSpeechEventType(AxSpeechEventDescribeItem);
00450 event.SetFlags(AxSpeechFlagsPurge);
00451 event.SetMenu(item->GetParent());
00452 event.SetMenuItem(item);
00453
00454 GetViewManager().GetSpeech().EmitSpeech(event);
00455 @endcode
00456
00457 @subsection page_using_speech_verbosity Controlling verbosity
00458
00459 AxSpeech stores speech policy - that is, high-level speech settings that can be changed by the user - using
00460 a class called AxSpeechPolicy. As well as containing the switch for switching speech on and off,
00461 it stores the current verbosity, which is a number between 1 and 5 and determines how much
00462 speech is emitted. 1 is least verbose, and 5 is most verbose; the default is 3.
00463
00464 AxSpeechEvent also stores a verbosity policy that tells the speech event handlers the threshold
00465 for this particular speech event. So if you specify a verbosity of 2 in the speech event, then
00466 if the global verbosity is 2 or more, it will be spoken. If you specify a verbosity of 1 in the speech event,
00467 it will always be spoken.
00468
00469 @subsection page_using_speech_channels Channels: using multiple voices simultaneously
00470
00471 AxSpeech supports the concept of 'channel'. There are two channels, represented by integers
00472 0 and 1 or AxSpeechMainChannel and AxSpeechContentChannel. Each channel has a corresponding
00473 wxTextToSpeech object and for those engines that support it, they can be used
00474 simultaneously. This is useful when outputting content without interrupting it with
00475 user interface navigation speech. The user can specify parameters such as voice and speed
00476 independently for each channel, and it's likely that you will want to use a different
00477 voice for each channel.
00478
00479 Specify the content channel in a AxSpeechEvent by passing the AxSpeechFlagsContentChannel flag.
00480 Otherwise, the main channel will be used.
00481
00482 Note that not all engines are capable of outputting speech to more than one channel at a time.
00483 Some engines will simply crash, as they are not designed to be re-entrant. wxTextToSpeech
00484 has a function wxTextToSpeech::VoicesAreCompatible and AxTk will use it to try to determine
00485 whether to switch off two channel operation. However it's possible that you may be using a
00486 speech engine that isn't covered; so for SAPI, you can call wxTTSSapiHandler::SetSimultaneousVoiceExclusions
00487 to set the strings that will be matched against SAPI voices to determine whether an engine
00488 can be used multiple times simultaneously. See also todo.txt for notes about problems with
00489 wxTTSProcessHandler::Stop which contribute to problems with simultaneous engine usage.
00490
00491
00492 @section page_using_ax_resource Using AxResourceLibrary
00493
00494 This is an optional layer on top of AxTk, that maintains a library of resources which can be
00495 audio files, ebooks, text documents, utilities, web services, or whatever might be a useful
00496 feature of the application. The motivation is to present users with a uniform and easy way to access their data and
00497 important functionality. Providing this in AxTk means that others can take an already useful
00498 system (in particular with support for popular audio and ebook formats) and build upon it, providing custom solutions.
00499
00500 The intention is to separate out the major functionality from the way it's used in AxTk, where possible. So for example
00501 the guts of Epub manipulation will be done in AxTk-neutral classes, with AxTk-specific classes to
00502 integrate the functionality. This allows programmers to integrate the functionality in different ways, as
00503 well as making maintenance easier.
00504
00505 The sample in @c samples/ax_resource/resource_sample can scan folders containing audio files and Epub files,
00506 and can then play albums and read Epub books (converting the XHTML content to plain text).
00507
00508
00509 */