::OutlookTop, Main

The Outlook namespace provides commands to control Microsoft Outlook.

CommandsOutlook, Top, Main

AddAppointment [::Outlook]Outlook, Top, Main

Create a new appointment in an Outlook calendar.

AddAppointment calId ?args?
calIdIdentifier of the Outlook calendar.
argsOptions described below.
-alldayevent <bool>Specify, if appointment is an all day event. Default: false.
-body <string>Set the body text of the appointment. Default: No body text.
-busystate <OlBusyStatus>Set the busy status of the appointment. Possible values: olBusy olFree olOutOfOffice olTentative olWorkingElsewhere. Default: olBusy.
-category <string>Assign category to appointment. If specified category does not yet exist, it is created. Default: No category.
-enddate <string>Set the end date of the appointment in format %Y-%m-%d %H:%M:%S. Default: Today.
-importance <OlImportance>Set the importance of the appointment. Possible values: olImportanceHigh olImportanceLow olImportanceNormal. Default: olImportanceNormal.
-isrecurringGet the recurring flag of the appointment. Only available for procedure GetAppointmentProperties.
-location <string>Set the location of the appointment. Default: No location.
-reminder <bool>Specify, if appointment has a reminder set. Default: true.
-sensitivity <OlSensitivity>Set the sensitivity of the appointment. Possible values: olConfidential olNormal olPersonal olPrivate. Default: olNormal.
-startdate <string>Set the start date of the appointment in format %Y-%m-%d %H:%M:%S. Default: Today.
-subject <string>Set the subject text of the appointment. Default: No subject.

Returns the identifier of the new appointment object.

See also: CreateMail, AddHolidayAppointment, GetAppointmentProperties, GetNumAppointments

proc ::Outlook::AddAppointment {calId args} {

    # Create a new appointment in an Outlook calendar.
    #
    # calId - Identifier of the Outlook calendar.
    # args  - Options described below.
    #
    # -subject <string>            - Set the subject text of the appointment.
    #                                Default: No subject.
    # -startdate <string>          - Set the start date of the appointment in format `%Y-%m-%d %H:%M:%S`.
    #                                Default: Today.
    # -enddate <string>            - Set the end date of the appointment in format `%Y-%m-%d %H:%M:%S`.
    #                                Default: Today.
    # -category <string>           - Assign category to appointment.
    #                                If specified category does not yet exist, it is created.
    #                                Default: No category.
    # -location <string>           - Set the location of the appointment.
    #                                Default: No location.
    # -body <string>               - Set the body text of the appointment.
    #                                Default: No body text.
    # -alldayevent <bool>          - Specify, if appointment is an all day event.
    #                                Default: false.
    # -reminder <bool>             - Specify, if appointment has a reminder set.
    #                                Default: true.
    # -busystate <OlBusyStatus>    - Set the busy status of the appointment.
    #                                Possible values: `olBusy` `olFree` `olOutOfOffice` `olTentative` `olWorkingElsewhere`.
    #                                Default: `olBusy`.
    # -importance <OlImportance>   - Set the importance of the appointment.
    #                                Possible values: `olImportanceHigh` `olImportanceLow` `olImportanceNormal`.
    #                                Default: `olImportanceNormal`.
    # -sensitivity <OlSensitivity> - Set the sensitivity of the appointment.
    #                                Possible values: `olConfidential` `olNormal` `olPersonal` `olPrivate`.
    #                                Default: `olNormal`.
    # -isrecurring                  - Get the recurring flag of the appointment.
    #                                 Only available for procedure [GetAppointmentProperties].
    #
    # Returns the identifier of the new appointment object.
    #
    # See also: CreateMail AddHolidayAppointment GetAppointmentProperties GetNumAppointments

    set appointId [$calId -with { Items } Add $Outlook::olAppointmentItem]

    foreach { key value } $args {
        if { $value eq "" } {
            error "AddAppointment: No value specified for key \"$key\""
        }
        switch -exact -nocase -- $key {
            "-subject" {
                $appointId Subject $value
            }
            "-startdate" {
                $appointId Start [Cawt IsoDateToOfficeDate $value]
            }
            "-enddate" {
                $appointId End [Cawt IsoDateToOfficeDate $value]
            }
            "-category" {
                set appId [$calId Application]
                Outlook AddCategory $appId $value
                $appointId Categories $value
                Cawt Destroy $appId
            }
            "-location" {
                $appointId Location $value
            }
            "-body" {
                $appointId Body $value
            }
            "-alldayevent" {
                $appointId AllDayEvent [Cawt TclBool $value]
            }
            "-reminder" {
                $appointId ReminderSet [Cawt TclBool $value]
            }
            "-busystate" {
                $appointId BusyStatus [Outlook GetEnum $value]
            }
            "-importance" {
                $appointId Importance [Outlook GetEnum $value]
            }
            "-sensitivity" {
                $appointId Sensitivity [Outlook GetEnum $value]
            }
            default {
                error "AddAppointment: Unknown key \"$key\" specified"
            }
        }
    }
    $appointId Save
    return $appointId
}

AddCalendar [::Outlook]Outlook, Top, Main

Add a new calendar.

AddCalendar appId calendarName
appIdIdentifier of the Outlook instance.
calendarNameName of the new calendar.

Returns the identifier of the new calendar. If a calendar with given name is already existing, the identifier of that calendar is returned. If the calendar could not be added an error is thrown.

See also: GetNumCalendars, HaveCalendar, GetCalendarNames, GetCalendarId, DeleteCalendar

proc ::Outlook::AddCalendar {appId calendarName} {

    # Add a new calendar.
    #
    # appId        - Identifier of the Outlook instance.
    # calendarName - Name of the new calendar.
    #
    # Returns the identifier of the new calendar.
    # If a calendar with given name is already existing, the identifier of that
    # calendar is returned.
    # If the calendar could not be added an error is thrown.
    #
    # See also: GetNumCalendars HaveCalendar GetCalendarNames GetCalendarId DeleteCalendar

    set nsObj [$appId GetNamespace "MAPI"]
    set calId [$nsObj GetDefaultFolder $Outlook::olFolderCalendar]
    set numFolders [$calId -with {Folders} Count]
    for { set i 1 } { $i <= $numFolders } { incr i } {
        set folderId [$calId -with {Folders} Item [expr {$i}]]
        if { [$folderId Name] eq $calendarName } {
            puts "Calendar $calendarName already exists"
            return $folderId
        }
        Cawt Destroy $folderId
    }
    set catchVal [catch {$calId -with { Folders } Add $calendarName $Outlook::olFolderCalendar} newCalId]
    if { $catchVal != 0 } {
        error "Could not add calendar \"$calendarName\"."
    }
    Cawt Destroy $calId
    Cawt Destroy $nsObj
    return $newCalId
}

AddCategory [::Outlook]Outlook, Top, Main

Add a new category to the Outlook categories.

AddCategory appId name ?color?
appIdIdentifier of the Outlook instance.
nameName of the new category.
colorValue of enumeration type Enum::OlCategoryColor or category color name. If set to the empty string, a color is choosen automatically by Outlook. Optional, default "".

Returns the identifier of the new category. If a category with given name is already existing, the identifier of that category is returned.

See also: HaveCategory, GetNumCategories, GetCategoryNames, GetCategoryId, DeleteCategory, GetCategoryColor

proc ::Outlook::AddCategory {appId name {color {}}} {

    # Add a new category to the Outlook categories.
    #
    # appId - Identifier of the Outlook instance.
    # name  - Name of the new category.
    # color - Value of enumeration type [Enum::OlCategoryColor]
    #         or category color name.
    #         If set to the empty string, a color is choosen automatically by Outlook.
    #
    # Returns the identifier of the new category.
    # If a category with given name is already existing, the identifier of that
    # category is returned.
    #
    # See also: HaveCategory GetNumCategories GetCategoryNames
    # GetCategoryId DeleteCategory GetCategoryColor

    if { [Outlook HaveCategory $appId $name] } {
        return [Outlook::GetCategoryId $appId $name]
    }

    set nsObj [$appId GetNamespace "MAPI"]
    set categories [$nsObj Categories]
    if { $color eq "" } {
        set categoryId [$categories Add $name]
    } else {
        set colorEnum [Outlook::GetCategoryColorEnum $color]
        set categoryId [$categories Add $name $colorEnum]
    }
    Cawt Destroy $categories
    Cawt Destroy $nsObj
    return $categoryId
}

AddHolidayAppointment [::Outlook]Outlook, Top, Main

Create a new appointment in an Outlook calendar.

AddHolidayAppointment calId subject ?args?
calIdIdentifier of the Outlook calendar.
subjectSubject text.
argsOptions described below.
-category <string>Assign category to appointment. Default: No category.
-date <string>Set the date of the appointment in format %Y-%m-%d. Default: Today.
-location <string>Set the location of the appointment. Default: No location.

The appointment has the following properties automatically set: All-Day event, No reminder, OutOfOffice status.

Returns the identifier of the new appointment object.

See also: CreateMail, AddAppointment, ApplyHolidayFile, GetNumAppointments

proc ::Outlook::AddHolidayAppointment {calId subject args} {

    # Create a new appointment in an Outlook calendar.
    #
    # calId   - Identifier of the Outlook calendar.
    # subject - Subject text.
    # args    - Options described below.
    #
    # -date <string>     - Set the date of the appointment in format `%Y-%m-%d`. Default: Today.
    # -category <string> - Assign category to appointment. Default: No category.
    # -location <string> - Set the location of the appointment. Default: No location.
    #
    # The appointment has the following properties automatically set:
    #   `All-Day event`, `No reminder`, `OutOfOffice status`.
    #
    # Returns the identifier of the new appointment object.
    #
    # See also: CreateMail AddAppointment ApplyHolidayFile GetNumAppointments

    set appointId [$calId -with { Items } Add $Outlook::olAppointmentItem]
    foreach { key value } $args {
        if { $value eq "" } {
            error "AddHolidayAppointment: No value specified for key \"$key\""
        }
        switch -exact -nocase -- $key {
            "-date"     {
                            set dateSec [clock scan $value -format "%Y-%m-%d"]
                            $appointId Start [Cawt SecondsToOfficeDate $dateSec]
                        }
            "-category" {
                            if { $value ne "" } {
                                set appId [$calId Application]
                                Outlook AddCategory $appId $value
                                $appointId Categories $value
                                Cawt Destroy $appId
                            }
                        }
            "-location" { $appointId Location $value }
            default     { error "AddHolidayAppointment: Unknown key \"$key\" specified" }
        }
    }

    $appointId Subject $subject
    $appointId AllDayEvent [Cawt TclBool true]
    $appointId ReminderSet [Cawt TclBool false]
    $appointId BusyStatus $Outlook::olOutOfOffice

    $appointId Save

    return $appointId
}

ApplyHolidayFile [::Outlook]Outlook, Top, Main

Read an Outlook holiday file and insert appointments.

ApplyHolidayFile calId fileName ?category?
calIdIdentifier of the Outlook calendar.
fileNameName of the Outlook holiday file.
categoryAssign category to appointment. Default: No category. Optional, default "".

Returns no value. If the holiday file could not be read, an error is thrown.

See also: ReadHolidayFile, AddHolidayAppointment

proc ::Outlook::ApplyHolidayFile {calId fileName {category {}}} {

    # Read an Outlook holiday file and insert appointments.
    #
    # calId    - Identifier of the Outlook calendar.
    # fileName - Name of the Outlook holiday file.
    # category - Assign category to appointment. Default: No category.
    #
    # Returns no value.
    # If the holiday file could not be read, an error is thrown.
    #
    # See also: ReadHolidayFile AddHolidayAppointment

    set holidayDict [Outlook::ReadHolidayFile $fileName]
    set sectionList [dict get $holidayDict SectionList]
    foreach section $sectionList {
        set subjectList [dict get $holidayDict "SubjectList_$section"]
        set dateList    [dict get $holidayDict "DateList_$section"]
        foreach subject $subjectList date $dateList {
            Outlook::AddHolidayAppointment $calId $subject  -date $date  -location $section  -category $category
        }
    }
}

CreateHtmlMail [::Outlook]Outlook, Top, Main

Create a new Outlook HTML mail.

CreateHtmlMail appId recipientList ?subject? ?body? ?attachmentList?
appIdIdentifier of the Outlook instance.
recipientListList of mail addresses.
subjectSubject text. Optional, default "".
bodyMail body text in HTML format. Optional, default "".
attachmentListList of files used as attachment. Optional, default "".

Returns the identifier of the new mail object.

See also: CreateMail, SendMail

proc ::Outlook::CreateHtmlMail {appId recipientList {subject {}} {body {}} {attachmentList {}}} {

    # Create a new Outlook HTML mail.
    #
    # appId          - Identifier of the Outlook instance.
    # recipientList  - List of mail addresses.
    # subject        - Subject text.
    # body           - Mail body text in HTML format.
    # attachmentList - List of files used as attachment.
    #
    # Returns the identifier of the new mail object.
    #
    # See also: CreateMail SendMail

    return [Outlook::_CreateMail $appId "html" $recipientList $subject $body $attachmentList]
}

CreateMail [::Outlook]Outlook, Top, Main

Create a new Outlook text mail.

CreateMail appId recipientList ?subject? ?body? ?attachmentList?
appIdIdentifier of the Outlook instance.
recipientListList of mail addresses.
subjectSubject text. Optional, default "".
bodyMail body text. Optional, default "".
attachmentListList of files used as attachment. Optional, default "".

Returns the identifier of the new mail object.

See also: CreateHtmlMail, SendMail

proc ::Outlook::CreateMail {appId recipientList {subject {}} {body {}} {attachmentList {}}} {

    # Create a new Outlook text mail.
    #
    # appId          - Identifier of the Outlook instance.
    # recipientList  - List of mail addresses.
    # subject        - Subject text.
    # body           - Mail body text.
    # attachmentList - List of files used as attachment.
    #
    # Returns the identifier of the new mail object.
    #
    # See also: CreateHtmlMail SendMail

    return [Outlook::_CreateMail $appId "text" $recipientList $subject $body $attachmentList]
}

DeleteAppointmentByIndex [::Outlook]Outlook, Top, Main

Delete an appointment of an Outlook calendar by its index.

DeleteAppointmentByIndex calId index
calIdIdentifier of the Outlook calendar.
indexIndex of the appointment.

The first appointment has index 1. Instead of using the numeric index the special word end may be used to specify the last appointment. If the index is out of bounds an error is thrown.

Returns no value.

See also: GetNumAppointments, GetAppointmentByIndex, AddAppointment

proc ::Outlook::DeleteAppointmentByIndex {calId index} {

    # Delete an appointment of an Outlook calendar by its index.
    #
    # calId - Identifier of the Outlook calendar.
    # index - Index of the appointment.
    #
    # Returns no value.
    #
    # The first appointment has index 1.
    # Instead of using the numeric index the special word `end` may
    # be used to specify the last appointment.
    # If the index is out of bounds an error is thrown.
    #
    # See also: GetNumAppointments GetAppointmentByIndex AddAppointment

    set count [Outlook::GetNumAppointments $calId]
    if { $index eq "end" } {
        set index $count
    } else {
        if { $index < 1 || $index > $count } {
            error "DeleteAppointmentIdByIndex: Invalid index $index given."
        }
    }
    $calId -with { Items } Remove [expr {$index}]
}

DeleteCalendar [::Outlook]Outlook, Top, Main

Delete an Outlook calendar.

DeleteCalendar calId
calIdIdentifier of the Outlook calendar.

Returns no value.

See also: GetNumCalendars, HaveCalendar, GetCalendarNames, GetCalendarId, AddCalendar

proc ::Outlook::DeleteCalendar {calId} {

    # Delete an Outlook calendar.
    #
    # calId - Identifier of the Outlook calendar.
    #
    # Returns no value.
    #
    # See also: GetNumCalendars HaveCalendar GetCalendarNames GetCalendarId AddCalendar
    $calId Delete
}

DeleteCategory [::Outlook]Outlook, Top, Main

Delete an Outlook category.

DeleteCategory appId indexOrName
appIdNot documented.
indexOrNameIndex or name of the Outlook category.

Returns no value.

See also: AddCategory, HaveCategory, GetNumCategories, GetCategoryNames, GetCategoryId, DeleteCategory

proc ::Outlook::DeleteCategory {appId indexOrName} {

    # Delete an Outlook category.
    #
    # indexOrName - Index or name of the Outlook category.
    #
    # Returns no value.
    #
    # See also: AddCategory HaveCategory GetNumCategories GetCategoryNames
    # GetCategoryId DeleteCategory

    set nsObj [$appId GetNamespace "MAPI"]
    set categories [$nsObj Categories]
    set count [$categories Count]

    if { [string is integer -strict $indexOrName] } {
        set index [expr int($indexOrName)]
        if { $index < 1 || $index > $count } {
            error "DeleteCategory: Invalid index $index given."
        }
    } else {
        set index 1
        set found false
        foreach name [Outlook::GetCategoryNames $appId] {
            if { $indexOrName eq $name } {
                set found true
                break
            }
            incr index
        }
        if { ! $found } {
            error "DeleteCategory: No category with name $indexOrName"
        }
    }
    $categories Remove $index

    Cawt Destroy $categories
    Cawt Destroy $nsObj
}

GetAppointmentByIndex [::Outlook]Outlook, Top, Main

Get an appointment of an Outlook calendar by its index.

GetAppointmentByIndex calId index
calIdIdentifier of the Outlook calendar.
indexIndex of the appointment.

The first appointment has index 1. Instead of using the numeric index the special word end may be used to specify the last appointment. If the index is out of bounds an error is thrown.

Returns the identifier of the found appointment.

See also: GetNumAppointments, DeleteAppointmentByIndex, AddAppointment

proc ::Outlook::GetAppointmentByIndex {calId index} {

    # Get an appointment of an Outlook calendar by its index.
    #
    # calId - Identifier of the Outlook calendar.
    # index - Index of the appointment.
    #
    # Returns the identifier of the found appointment.
    #
    # The first appointment has index 1.
    # Instead of using the numeric index the special word `end` may
    # be used to specify the last appointment.
    # If the index is out of bounds an error is thrown.
    #
    # See also: GetNumAppointments DeleteAppointmentByIndex AddAppointment

    set count [Outlook::GetNumAppointments $calId]
    if { $index eq "end" } {
        set index $count
    } else {
        if { $index < 1 || $index > $count } {
            error "GetAppointmentIdByIndex: Invalid index $index given."
        }
    }

    set itemId [$calId -with { Items } Item [expr {$index}]]
    return $itemId
}

GetAppointmentProperties [::Outlook]Outlook, Top, Main

Get properties of an appointment.

GetAppointmentProperties appointId ?args?
appointIdIdentifier of the Outlook appointment.
argsList of keys specifying appointment configure options.

See AddAppointment for a list of configure options.

Returns the appointment properties as a list of values. The list elements have the same order as the list of keys.

See also: AddAppointment, GetNumAppointments

proc ::Outlook::GetAppointmentProperties {appointId args} {

    # Get properties of an appointment.
    #
    # appointId - Identifier of the Outlook appointment.
    # args      - List of keys specifying appointment configure options.
    #
    # See [AddAppointment] for a list of configure options.
    #
    # Returns the appointment properties as a list of values.
    # The list elements have the same order as the list of keys.
    #
    # See also: AddAppointment GetNumAppointments

    set valueList [list]
    foreach key $args {
        switch -exact -nocase -- $key {
            "-subject" {
                lappend valueList [$appointId Subject]
            }
            "-startdate" {
                lappend valueList [Cawt OfficeDateToIsoDate [$appointId Start]]
            }
            "-enddate" {
                lappend valueList [Cawt OfficeDateToIsoDate [$appointId End]]
            }
            "-category" {
                lappend valueList [$appointId Categories]
            }
            "-location" {
                lappend valueList [$appointId Location]
            }
            "-body" {
                lappend valueList [$appointId Body]
            }
            "-alldayevent" {
                lappend valueList [$appointId AllDayEvent]
            }
            "-reminder" {
                lappend valueList [$appointId ReminderSet]
            }
            "-busystate" {
                lappend valueList [Outlook GetEnumName OlBusyStatus [$appointId BusyStatus]]
            }
            "-importance" {
                lappend valueList [Outlook GetEnumName OlImportance [$appointId Importance]]
            }
            "-sensitivity" {
                lappend valueList [Outlook GetEnumName OlSensitivity [$appointId Sensitivity]]
            }
            "-isrecurring" {
                lappend valueList [$appointId IsRecurring]
            }
            default {
                error "GetAppointmentProperties: Unknown key \"$key\" specified"
            }
        }
    }
    return $valueList
}

GetCalendarId [::Outlook]Outlook, Top, Main

Get a calendar by its name.

GetCalendarId appId ?calendarName?
appIdIdentifier of the Outlook instance.
calendarNameName of the calendar to find. Optional, default "".

If a calendar with given name does not exist an error is thrown.

Returns the identifier of the found calendar.

See also: GetNumCalendars, HaveCalendar, GetCalendarNames, AddCalendar, DeleteCalendar

proc ::Outlook::GetCalendarId {appId {calendarName {}}} {

    # Get a calendar by its name.
    #
    # appId        - Identifier of the Outlook instance.
    # calendarName - Name of the calendar to find.
    #
    # Returns the identifier of the found calendar.
    #
    # If a calendar with given name does not exist an error is thrown.
    #
    # See also: GetNumCalendars HaveCalendar GetCalendarNames AddCalendar DeleteCalendar

    if { $calendarName eq "" } {
        set nsObj [$appId GetNamespace "MAPI"]
        set calId [$nsObj GetDefaultFolder $Outlook::olFolderCalendar]
        Cawt Destroy $nsObj
        return $calId
    }
    set foundId ""
    foreach { name calId } [Outlook::_GetFoldersRecursive $appId $Outlook::olAppointmentItem] {
        if { $name eq $calendarName } {
            set foundId $calId
        } else {
            Cawt Destroy $calId
        }
    }
    return $foundId
}

GetCalendarNames [::Outlook]Outlook, Top, Main

Get a list of calendar names.

GetCalendarNames appId
appIdIdentifier of the Outlook instance.

Returns a list of calendar names.

See also: GetNumCalendars, HaveCalendar, GetCalendarId, AddCalendar, DeleteCalendar

proc ::Outlook::GetCalendarNames {appId} {

    # Get a list of calendar names.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns a list of calendar names.
    #
    # See also: GetNumCalendars HaveCalendar GetCalendarId AddCalendar DeleteCalendar

    set calendarNameList [list]
    foreach { name calId } [Outlook::_GetFoldersRecursive $appId $Outlook::olAppointmentItem] {
        lappend calendarNameList $name
    }
    return $calendarNameList
}

GetCategoryColor [::Outlook]Outlook, Top, Main

Convert a category color enumeration or name into a hexadecimal Tcl color string representation.

GetCategoryColor colorEnumOrName
colorEnumOrNameA category color enumeration or name.

Outlook category colors can be specified in one of the following representations:

EnumA value of enumeration Enum::OlCategoryColor.
NameEnumeration name without prefix olCategoryColor. Example: Name of Outlook::olCategoryColorBlack is Black.

Returns the hexadecimal representation of the specified color, ex. #00FFAA.

See also: ::Cawt::GetColor, GetCategoryColorEnum, GetCategoryColorName, GetCategoryColorNames

proc ::Outlook::GetCategoryColor {colorEnumOrName} {

    # Convert a category color enumeration or name
    # into a hexadecimal Tcl color string representation.
    #
    # colorEnumOrName - A category color enumeration or name.
    #
    # Outlook category colors can be specified in one of the following representations:
    #   Enum - A value of enumeration [Enum::OlCategoryColor].
    #   Name - Enumeration name without prefix `olCategoryColor`.
    #          Example: Name of `Outlook::olCategoryColorBlack` is `Black`.
    #
    # Returns the hexadecimal representation of the specified color, ex. `#00FFAA`.
    #
    # See also: ::Cawt::GetColor GetCategoryColorEnum GetCategoryColorName GetCategoryColorNames

    variable sCategoryColorList

    set enum [Outlook::GetCategoryColorEnum $colorEnumOrName]
    set rgb [lrange $sCategoryColorList($enum) 1 end]
    lassign $rgb r g b
    return [format "#%02X%02X%02X" $r $g $b]
}

GetCategoryColorEnum [::Outlook]Outlook, Top, Main

Convert a category color enumeration or name into a color enumeration.

GetCategoryColorEnum colorEnumOrName
colorEnumOrNameA category color enumeration or name.

See GetCategoryColor for a description of color enumerations and names.

Returns the category color enumeration.

See also: ::Cawt::GetColor, GetCategoryColor, GetCategoryColorName, GetCategoryColorNames

proc ::Outlook::GetCategoryColorEnum {colorEnumOrName} {

    # Convert a category color enumeration or name into a color enumeration.
    #
    # colorEnumOrName - A category color enumeration or name.
    #
    # See [GetCategoryColor] for a description of color enumerations and names.
    #
    # Returns the category color enumeration.
    #
    # See also: ::Cawt::GetColor GetCategoryColor GetCategoryColorName GetCategoryColorNames

    variable sCategoryColorList

    if { [string is integer $colorEnumOrName] } {
        if { [info exists sCategoryColorList($colorEnumOrName)] } {
            return $colorEnumOrName
        }
    } else {
        foreach { key val } [array get sCategoryColorList] {
            if { [lindex $val 0] eq $colorEnumOrName } {
                return $key
            }
        }
    }
    error "GetCategoryColorEnum: Invalid color representation \"$colorEnumOrName\" specified."
}

GetCategoryColorName [::Outlook]Outlook, Top, Main

Convert a category color enumeration into a category color name.

GetCategoryColorName colorEnum
colorEnumA category color enumeration.

See GetCategoryColor for a description of color enumerations and names.

Returns the category color name.

See also: ::Cawt::GetColor, GetCategoryColor, GetCategoryColorEnum, GetCategoryColorNames

proc ::Outlook::GetCategoryColorName {colorEnum} {

    # Convert a category color enumeration into a category color name.
    #
    # colorEnum - A category color enumeration.
    #
    # See [GetCategoryColor] for a description of color enumerations and names.
    #
    # Returns the category color name.
    #
    # See also: ::Cawt::GetColor GetCategoryColor GetCategoryColorEnum GetCategoryColorNames

    variable sCategoryColorList

    if { [info exists sCategoryColorList($colorEnum)] } {
        return [lindex $sCategoryColorList($colorEnum) 0]
    }
    error "GetCategoryColorName: Invalid color enumeration \"$colorEnum\" specified."
}

GetCategoryColorNames [::Outlook]Outlook, Top, Main

Get all category color names.

GetCategoryColorNames

See GetCategoryColor for a description of color enumerations and names.

Returns a list of all category color names.

See also: ::Cawt::GetColor, GetCategoryColor, GetCategoryColorEnum, GetCategoryColorName

proc ::Outlook::GetCategoryColorNames {} {

    # Get all category color names.
    #
    # See [GetCategoryColor] for a description of color enumerations and names.
    #
    # Returns a list of all category color names.
    #
    # See also: ::Cawt::GetColor GetCategoryColor GetCategoryColorEnum GetCategoryColorName

    variable sCategoryColorList

    set colorNameList [list]
    foreach { key val } [array get sCategoryColorList] {
        lappend colorNameList [lindex $val 0]
    }
    return $colorNameList
}

GetCategoryId [::Outlook]Outlook, Top, Main

Get a category by its index or name.

GetCategoryId appId indexOrName
appIdIdentifier of the Outlook instance.
indexOrNameIndex or name of the category.

The first category has index 1. If the index is out of bounds or the category name does not exist, an error is thrown.

Returns the identifier of the found category.

See also: HaveCategory, GetNumCategories, GetCategoryNames, AddCategory, DeleteCategory

proc ::Outlook::GetCategoryId {appId indexOrName} {

    # Get a category by its index or name.
    #
    # appId       - Identifier of the Outlook instance.
    # indexOrName - Index or name of the category.
    #
    # Returns the identifier of the found category.
    #
    # The first category has index 1.
    # If the index is out of bounds or the category name does not
    # exist, an error is thrown.
    #
    # See also: HaveCategory GetNumCategories GetCategoryNames
    # AddCategory DeleteCategory

    set nsObj [$appId GetNamespace "MAPI"]
    set count [$nsObj -with { Categories } Count]
    if { [string is integer -strict $indexOrName] } {
        set index [expr int($indexOrName)]
        if { $index < 1 || $index > $count } {
            error "GetCategoryId: Invalid index $index given."
        }
    } else {
        set index 1
        set found false
        foreach name [Outlook GetCategoryNames $appId] {
            if { $indexOrName eq $name } {
                set found true
                break
            }
            incr index
        }
        if { ! $found } {
            error "GetCategoryId: No category with name $indexOrName"
        }
    }
    set categoryId [$nsObj -with { Categories } Item $index]
    Cawt Destroy $nsObj
    return $categoryId
}

GetCategoryNames [::Outlook]Outlook, Top, Main

Get a list of category names.

GetCategoryNames appId
appIdIdentifier of the Outlook instance.

Returns a list of category names.

See also: HaveCategory, GetNumCategories, GetCategoryId, AddCategory, DeleteCategory

proc ::Outlook::GetCategoryNames {appId} {

    # Get a list of category names.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns a list of category names.
    #
    # See also: HaveCategory GetNumCategories GetCategoryId
    # AddCategory DeleteCategory

    set nsObj [$appId GetNamespace "MAPI"]
    set categories [$nsObj Categories]
    set count [$categories Count]

    set nameList [list]
    for { set i 1 } { $i <= $count } { incr i } {
        set categoryId [$categories Item [expr {$i}]]
        lappend nameList [$categoryId Name]
        Cawt Destroy $categoryId
    }
    Cawt Destroy $categories
    Cawt Destroy $nsObj
    return $nameList
}

GetEnum [::Outlook]Outlook, Top, Main

Get numeric value of an enumeration.

GetEnum enumOrString
enumOrStringEnumeration name

Returns the numeric value of an enumeration.

See also: GetEnumName, GetEnumTypes, GetEnumVal, GetEnumNames

proc ::Outlook::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]
    }
}

GetEnumName [::Outlook]Outlook, Top, Main

Get name of a given enumeration type and numeric value.

GetEnumName enumType enumVal
enumTypeEnumeration type
enumValEnumeration numeric value.

Returns the list of names of a given enumeration type.

See also: GetEnumNames, GetEnumTypes, GetEnumVal, GetEnum

proc ::Outlook::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
}

GetEnumNames [::Outlook]Outlook, Top, Main

Get names of a given enumeration type.

GetEnumNames enumType
enumTypeEnumeration type

Returns the list of names of a given enumeration type.

See also: GetEnumName, GetEnumTypes, GetEnumVal, GetEnum

proc ::Outlook::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]
    }
}

GetEnumTypes [::Outlook]Outlook, Top, Main

Get available enumeration types.

GetEnumTypes

Returns the list of available enumeration types.

See also: GetEnumName, GetEnumNames, GetEnumVal, GetEnum

proc ::Outlook::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]]
}

GetEnumVal [::Outlook]Outlook, Top, Main

Get numeric value of an enumeration name.

GetEnumVal enumName
enumNameEnumeration name

Returns the numeric value of an enumeration name.

See also: GetEnumName, GetEnumTypes, GetEnumNames, GetEnum

proc ::Outlook::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 ""
}

GetMailIds [::Outlook]Outlook, Top, Main

Get a list of mail identifiers.

GetMailIds appId
appIdIdentifier of the Outlook instance.

Returns a list of mail identifiers.

See also: GetMailSubjects, CreateMail, SendMail

proc ::Outlook::GetMailIds {appId} {

    # Get a list of mail identifiers.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns a list of mail identifiers.
    #
    # See also: GetMailSubjects CreateMail SendMail

    set idList [list]
    foreach { name folderId } [Outlook::_GetFoldersRecursive $appId $Outlook::olMailItem] {
        set numItems [$folderId -with { Items } Count]
        if { $numItems > 0 } {
            for { set i 1 } { $i <= $numItems } { incr i } {
                lappend idList [$folderId -with { Items } Item $i]
            }
        }
    }
    return $idList
}

GetMailSubjects [::Outlook]Outlook, Top, Main

Get a list of mail subjects.

GetMailSubjects appId
appIdIdentifier of the Outlook instance.

Returns a list of mail subjects.

See also: GetMailIds, CreateMail, SendMail

proc ::Outlook::GetMailSubjects {appId} {

    # Get a list of mail subjects.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns a list of mail subjects.
    #
    # See also: GetMailIds CreateMail SendMail

    set subjectList [list]
    foreach { name folderId } [Outlook::_GetFoldersRecursive $appId $Outlook::olMailItem] {
        set numItems [$folderId -with { Items } Count]
        if { $numItems > 0 } {
            for { set i 1 } { $i <= $numItems } { incr i } {
                set mailId [$folderId -with { Items } Item $i]
                lappend subjectList [$mailId Subject]
                Cawt Destroy $mailId
            }
        }
    }
    return $subjectList
}

GetNumAppointments [::Outlook]Outlook, Top, Main

Get the number of appointments in an Outlook calendar.

GetNumAppointments calId
calIdIdentifier of the Outlook calendar.

Returns the number of Outlook appointments.

See also: GetAppointmentByIndex, DeleteAppointmentByIndex, AddAppointment

proc ::Outlook::GetNumAppointments {calId} {

    # Get the number of appointments in an Outlook calendar.
    #
    # calId - Identifier of the Outlook calendar.
    #
    # Returns the number of Outlook appointments.
    #
    # See also: GetAppointmentByIndex DeleteAppointmentByIndex AddAppointment

    set count [$calId -with { Items } Count]
    return $count
}

GetNumCalendars [::Outlook]Outlook, Top, Main

Get the number of Outlook calendars.

GetNumCalendars appId
appIdIdentifier of the Outlook instance.

Returns the number of Outlook calendars.

See also: HaveCalendar, GetCalendarNames, GetCalendarId, AddCalendar, DeleteCalendar

proc ::Outlook::GetNumCalendars {appId} {

    # Get the number of Outlook calendars.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns the number of Outlook calendars.
    #
    # See also: HaveCalendar GetCalendarNames GetCalendarId AddCalendar DeleteCalendar

    return [llength [Outlook::GetCalendarNames $appId]]
}

GetNumCategories [::Outlook]Outlook, Top, Main

Get the number of Outlook categories.

GetNumCategories appId
appIdIdentifier of the Outlook instance.

Returns the number of Outlook categories.

See also: HaveCategory, GetCategoryNames, GetCategoryId, AddCategory, DeleteCategory

proc ::Outlook::GetNumCategories {appId} {

    # Get the number of Outlook categories.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns the number of Outlook categories.
    #
    # See also: HaveCategory GetCategoryNames GetCategoryId
    # AddCategory DeleteCategory

    set nsObj [$appId GetNamespace "MAPI"]
    set count [$nsObj -with { Categories } Count]
    Cawt Destroy $nsObj
    return $count
}

GetVersion [::Outlook]Outlook, Top, Main

Get the version of an Outlook application.

GetVersion objId ?useString?
objIdIdentifier of an Outlook object instance.
useStringIf set to true, return the version name (ex. Outlook 2000). Otherwise return the version number (ex. 9.0). Optional, default false.

Both version name and version number are returned as strings. Version number is in a format, so that it can be evaluated as a floating point number.

Returns the version of an Outlook application.

See also: Open

proc ::Outlook::GetVersion {objId {useString false}} {

    # Get the version of an Outlook application.
    #
    # objId     - Identifier of an Outlook object instance.
    # useString - If set to true, return the version name (ex. `Outlook 2000`).
    #             Otherwise return the version number (ex. `9.0`).
    #
    # Returns the version of an Outlook application.
    #
    # Both version name and version number are returned as strings.
    # Version number is in a format, so that it can be evaluated as a
    # floating point number.
    #
    # See also: Open

    array set map {
        "7.0"  "Outlook 95"
        "8.0"  "Outlook 97"
        "9.0"  "Outlook 2000"
        "10.0" "Outlook 2002"
        "11.0" "Outlook 2003"
        "12.0" "Outlook 2007"
        "14.0" "Outlook 2010"
        "15.0" "Outlook 2013"
        "16.0" "Outlook 2016/2019"
    }
    set versionString [Office GetApplicationVersion $objId]

    set members [split $versionString "."]
    set version "[lindex $members 0].[lindex $members 1]"
    if { $useString } {
        if { [info exists map($version)] } {
            return $map($version)
        } else {
            return "Unknown Outlook version $version"
        }
    } else {
        return $version
    }
}

HaveCalendar [::Outlook]Outlook, Top, Main

Check, if a calendar already exists.

HaveCalendar appId calendarName
appIdIdentifier of the Outlook instance.
calendarNameName of the calendar to check.

Returns true, if the calendar exists, otherwise false.

See also: GetNumCalendars, GetCalendarNames, GetCalendarId, AddCalendar, DeleteCalendar

proc ::Outlook::HaveCalendar {appId calendarName} {

    # Check, if a calendar already exists.
    #
    # appId        - Identifier of the Outlook instance.
    # calendarName - Name of the calendar to check.
    #
    # Returns true, if the calendar exists, otherwise false.
    #
    # See also: GetNumCalendars GetCalendarNames GetCalendarId AddCalendar DeleteCalendar

    if { [lsearch -exact [Outlook::GetCalendarNames $appId] $calendarName] >= 0 } {
        return true
    } else {
        return false
    }
}

HaveCategory [::Outlook]Outlook, Top, Main

Check, if a category already exists.

HaveCategory appId categoryName
appIdIdentifier of the Outlook instance.
categoryNameName of the category to check.

Returns true, if the category exists, otherwise false.

See also: HaveCategory, GetCategoryNames, GetCategoryId, AddCategory, DeleteCategory, GetCategoryColor

proc ::Outlook::HaveCategory {appId categoryName} {

    # Check, if a category already exists.
    #
    # appId        - Identifier of the Outlook instance.
    # categoryName - Name of the category to check.
    #
    # Returns true, if the category exists, otherwise false.
    #
    # See also: HaveCategory GetCategoryNames GetCategoryId
    # AddCategory DeleteCategory GetCategoryColor

    if { [lsearch -exact [Outlook::GetCategoryNames $appId] $categoryName] >= 0 } {
        return true
    } else {
        return false
    }
}

Open [::Outlook]Outlook, Top, Main

Open an Outlook instance.

Open ?explorerType?
explorerTypeValue of enumeration type Enum::OlDefaultFolders. Typical values are: olFolderCalendar, olFolderInbox, olFolderTasks. Optional, default olFolderInbox.

Returns the identifier of the Outlook application instance.

See also: Quit

proc ::Outlook::Open {{explorerType olFolderInbox}} {

            # Open an Outlook instance.
            #
            # explorerType - Value of enumeration type [Enum::OlDefaultFolders].
            #                Typical values are: `olFolderCalendar`, `olFolderInbox`, `olFolderTasks`.
            #
            # Returns the identifier of the Outlook application instance.
            #
            # See also: Quit

            variable outlookAppName
    	variable outlookVersion

            set appId [Cawt GetOrCreateApp $outlookAppName true]
            set outlookVersion [Outlook GetVersion $appId]

            set explorers [$appId Explorers]
            if { $explorerType ne "" && ! [Cawt IsComObject [$appId ActiveExplorer]] } {
                set nsObj [$appId GetNamespace "MAPI"]
                set myFolder [$nsObj GetDefaultFolder [Outlook GetEnum $explorerType]]
                set myExplorer [$explorers Add $myFolder $Outlook::olFolderDisplayNormal]
                $myExplorer Display
                Cawt Destroy $myExplorer
                Cawt Destroy $myFolder
                Cawt Destroy $nsObj
            }
            Cawt Destroy $explorers
            return $appId
}

OpenNew [::Outlook]Outlook, Top, Main

Obsolete: Replaced with Open in version 2.4.1

OpenNew ?explorerType?
explorerTypeNot documented. Optional, default olFolderInbox.
proc ::Outlook::OpenNew {{explorerType olFolderInbox}} {

    # Obsolete: Replaced with [Open] in version 2.4.1

    return [Outlook::Open $explorerType]
}

Quit [::Outlook]Outlook, Top, Main

Quit an Outlook instance.

Quit appId
appIdIdentifier of the Outlook instance.

Returns no value.

See also: Open

proc ::Outlook::Quit {appId} {

    # Quit an Outlook instance.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns no value.
    #
    # See also: Open

    $appId Quit
}

ReadHolidayFile [::Outlook]Outlook, Top, Main

Read an Outlook holiday file.

ReadHolidayFile fileName
fileNameName of the Outlook holiday file.

The data of the holiday file is returned as a dict with the following keys:

SectionListThe list of sections in the holiday file.

For each section the following keys are set:

SubjectList_$sectionThe list of subjects of this section.
DateList_$sectionThe list of dates of this section.

Returns the data of the holiday file as a dictionary. If the holiday file could not be read, an error is thrown.

See also: AddHolidayAppointment, ApplyHolidayFile

proc ::Outlook::ReadHolidayFile {fileName} {

    # Read an Outlook holiday file.
    #
    # fileName - Name of the Outlook holiday file.
    #
    # The data of the holiday file is returned as a dict with the following keys:
    # `SectionList` - The list of sections in the holiday file.
    #
    # For each section the following keys are set:
    #  `SubjectList_$section` - The list of subjects of this section.
    #  `DateList_$section`    - The list of dates of this section.
    #
    # Returns the data of the holiday file as a dictionary.
    # If the holiday file could not be read, an error is thrown.
    #
    # See also: AddHolidayAppointment ApplyHolidayFile

    set isUnicodeFile [Cawt IsUnicodeFile $fileName]

    set catchVal [catch {open $fileName r} fp]
    if { $catchVal != 0 } {
        error "Could not open file \"$fileName\" for reading."
    }

    if { $isUnicodeFile } {
        # If Unicode, skip the 2 BOM bytes and set appropriate encoding.
        set bom [read $fp 2]
        fconfigure $fp -encoding unicode
    }

    set holidayDict [dict create]
    dict set emptyDict   SectionList [list]
    dict set holidayDict SectionList [list]

    while { [gets $fp line] >= 0 } {
        if { [string length $line] == 0 } {
            continue
        }
        if { [string index $line 0] eq "\[" } {
            set endRange [string first "\]" $line]
            if { $endRange < 0 } {
                return $emptyDict
            }
            set sectionName [string range $line 1 [expr {$endRange - 1}]]
            dict lappend holidayDict SectionList $sectionName
        } else {
            set nameDateList [split $line ","]
            if { [llength $nameDateList] == 2 } {
                lassign $nameDateList name date
                set isoDate [string map { "/" "-" } $date]
                dict lappend holidayDict "SubjectList_$sectionName" $name
                dict lappend holidayDict "DateList_$sectionName"    $isoDate
            } else {
                return $emptyDict
            }
        }
    }
    close $fp
    return $holidayDict
}

SendMail [::Outlook]Outlook, Top, Main

Send an Outlook mail.

SendMail mailId
mailIdIdentifier of the Outlook mail object.

Returns no value.

See also: CreateMail, CreateHtmlMail

proc ::Outlook::SendMail {mailId} {

    # Send an Outlook mail.
    #
    # mailId - Identifier of the Outlook mail object.
    #
    # Returns no value.
    #
    # See also: CreateMail CreateHtmlMail

    $mailId Send
}
Document generated by Ruff!