::SapiTop, Main, Index

proc ::Sapi::GetEnum {enumOrString} {

    # Get numeric value of an enumeration.
    #
    # enumOrString - Enumeration name
    #
    # Returns the numeric value of an enumeration.
    #
    # See also: GetEnumName GetEnumTypes GetEnumVal GetEnumNames

    set retVal [catch { expr int($enumOrString) } enumInt]
    if { $retVal == 0 } {
        return $enumInt
    } else {
        return [GetEnumVal $enumOrString]
    }
}

proc ::Sapi::GetEnumName {enumType enumVal} {

    # Get name of a given enumeration type and numeric value.
    #
    # enumType - Enumeration type
    # enumVal  - Enumeration numeric value.
    #
    # Returns the list of names of a given enumeration type.
    #
    # See also: GetEnumNames GetEnumTypes GetEnumVal GetEnum

    variable enums

    set enumName ""
    if { [info exists enums($enumType)] } {
        foreach { key val } $enums($enumType) {
            if { $val eq $enumVal } {
                set enumName $key
                break
            }
        }
    }
    return $enumName
}

proc ::Sapi::GetEnumNames {enumType} {

    # Get names of a given enumeration type.
    #
    # enumType - Enumeration type
    #
    # Returns the list of names of a given enumeration type.
    #
    # See also: GetEnumName GetEnumTypes GetEnumVal GetEnum

    variable enums

    if { [info exists enums($enumType)] } {
        foreach { key val } $enums($enumType) {
            lappend nameList $key
        }
        return $nameList
    } else {
        return [list]
    }
}

proc ::Sapi::GetEnumTypes {} {

    # Get available enumeration types.
    #
    # Returns the list of available enumeration types.
    #
    # See also: GetEnumName GetEnumNames GetEnumVal GetEnum

    variable enums

    return [lsort -dictionary [array names enums]]
}

proc ::Sapi::GetEnumVal {enumName} {

    # Get numeric value of an enumeration name.
    #
    # enumName - Enumeration name
    #
    # Returns the numeric value of an enumeration name.
    #
    # See also: GetEnumName GetEnumTypes GetEnumNames GetEnum

    variable enums

    foreach enumType [GetEnumTypes] {
        set ind [lsearch -exact $enums($enumType) $enumName]
        if { $ind >= 0 } {
            return [lindex $enums($enumType) [expr { $ind + 1 }]]
        }
    }
    return ""
}

proc ::Sapi::GetSpeakOptions {appId args} {

    # Get speak options.
    #
    # appId - Identifier of the SAPI instance.
    # args  - Options described below.
    #
    # -rate   - Get the speaking rate of the voice.
    #           Values range from -10 (slowest) to 10 (fastest).
    # -volume - Set the volume (loudiness) of the voice.
    #           Values range from 0 to 100.
    #
    # Example:
    #     lassign [GetSpeakOptions $appId -rate -volume] rate volume
    #
    # Returns the specified options as a list.
    #
    # See also: Open Speak SetSpeakOptions

    set valList [list]
    foreach key $args {
        switch -exact -nocase -- $key {
            "-rate"   { lappend valList [$appId Rate] }
            "-volume" { lappend valList [$appId Volume] }
            default   { error "GetSpeakOptions: Unknown key \"$key\" specified" }
        }
    }
    return $valList
}

proc ::Sapi::GetVoiceByName {appId voiceName} {

    # Get a voice identifier by specifying its name.
    #
    # appId     - Identifier of the SAPI instance.
    # voiceName - Name of the voice.
    #
    # Returns the voice identifier.
    #
    # See also: Open Speak GetVoiceNames SetVoice

    set voices [$appId GetVoices]
    set numVoices [$voices Count]
    for { set v 0 } { $v < $numVoices } { incr v } {
        set voice [$voices Item $v]
        if { [$voice GetDescription] eq $voiceName } {
            Cawt Destroy $voices
            return $voice
        }
        Cawt Destroy $voice
    }
    error "Voice \"$voiceName\" not available."
}

proc ::Sapi::GetVoiceNames {appId} {

    # Get a list of voice names.
    #
    # appId - Identifier of the SAPI instance.
    #
    # Returns the list of voice names.
    #
    # See also: Open Speak GetVoiceByName SetVoice

    set voicesList [list]
    set voices [$appId GetVoices]
    set numVoices [$voices Count]
    for { set v 0 } { $v < $numVoices } { incr v } {
        set voice [$voices Item $v]
        lappend voicesList [$voice GetDescription]
        Cawt Destroy $voice
    }
    Cawt Destroy $voices
    return $voicesList
}

proc ::Sapi::Open {} {

            # Open a SAPI object instance.
            #
            # Returns the SAPI object identifier.
            #
            # See also: Speak SetSpeakOptions GetVoiceNames

    	variable sapiAppName

            set appId [Cawt GetOrCreateApp $sapiAppName true]
            return $appId
}

proc ::Sapi::SetSpeakOptions {appId args} {

    # Set speak options.
    #
    # appId - Identifier of the SAPI instance.
    # args  - Options described below.
    #
    # -rate <int>   - Set the speaking rate of the voice.
    #                 Values range from -10 (slowest) to 10 (fastest).
    # -volume <int> - Set the volume (loudiness) of the voice.
    #                 Values range from 0 to 100.
    #
    # Returns no value.
    #
    # See also: Open Speak GetSpeakOptions

    foreach { key value } $args {
        if { $value eq "" } {
            error "SetSpeakOptions: No value specified for key \"$key\""
        }
        switch -exact -nocase -- $key {
            "-rate"   { $appId Rate   [expr int( $value)] }
            "-volume" { $appId Volume [expr int( $value)] }
            default   { error "SetSpeakOptions: Unknown key \"$key\" specified" }
        }
    }
}

proc ::Sapi::SetVoice {appId voiceId} {

    # Set the voice for speaking.
    #
    # appId   - Identifier of the SAPI instance.
    # voiceId - Identifier of the voice.
    #
    # Returns no value.
    #
    # See also: Open SetSpeakOptions GetVoiceByName

    # Workaround from Ashok to directly invoke the Voice
    # property method as a propertyputref (type 8).
    $appId -invoke Voice [list 8] [list $voiceId]
}

proc ::Sapi::Speak {appId str args} {

    # Speak a sentence.
    #
    # appId - Identifier of the SAPI instance.
    # str   - String to be spoken.
    # args  - Options described below.
    #
    # -flags <int> - Bitflag of enumerations of type [Enum::SpeechVoiceSpeakFlags]
    #
    # Returns no value.
    #
    # See also: Open SetSpeakOptions GetVoiceNames

    set flags $::Sapi::SVSFDefault
    foreach { key value } $args {
        if { $value eq "" } {
            error "Speak: No value specified for key \"$key\""
        }
        switch -exact -nocase -- $key {
            "-flags" { set flags $value }
            default  { error "Speak: Unknown key \"$key\" specified" }
        }
    }
    $appId Speak $str [expr int($flags)]
}