|
|
| (24 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| | {{WIP}} |
| [[Category:UDF]] | | [[Category:UDF]] |
| The PowerPoint UDF offers basic functions to control and manipulate Microsoft PowerPoint. | | The PowerPoint UDF offers basic functions to control and manipulate Microsoft PowerPoint. |
| Line 7: |
Line 8: |
| The PowerPoint UDF is based on the following concept: | | The PowerPoint UDF is based on the following concept: |
|
| |
|
| * Every item in Outlook is uniquely identified by EntryID and StoreID. The default StoreID is your inbox | | * Use function ''_PPT_Open'' as the first step in your script to start up PowerPoint or to connect to a running instance. |
| * Every item has properties to describe the item (subject, startdate ..) and methods to act upon the item (move, delete …) | | * Some functions allow to process just a single Slide and others allow a range of Slides. |
| * It does not matter where an item is stored. You can access any folder and get/create/modify items there | | ** The UDF always uses the SlideRange object when working with Slides.<br>Use function ''_PPT_SlideRangeSet'' to specify the Slides to process, then call a function and pass the SlideRange as parameter. |
| * The search and action functions are now separated. As an example the user first searches for the items to be deleted and then calls the delete function | | ** For details please check the description of the specific function. |
| * The UDF was designed to be as modular as possible. E.g. there is a single function to create an item, be it a mail item, contact item or whatever | | * Some functions allow to process just a single Shape and others allow a range of Shapes. |
| * The number of properties you can pass to most functions is not limited by the number of parameters defined for the function. Properties can be passed as parameters (up to 10) or in an unlimited array as parameter 1 | | ** The UDF always uses the ShapeRange object when working with Shapes.<br>Use function ''_PPT_ShapeRangeSet'' to specify the Shapes to process, then call a function and pass the ShapeRange as parameter. |
| * The UDF allows to access all kind of folders (see the following listing). Folders can be passed to a function by name or as an object
| | ** For details please check the description of the specific function. |
| | | * Use function ''_PPT_Close'' as the last step in your script to shutdown PowerPoint or to release the connection to a running instance. |
| --------------------
| |
|
| |
|
| === PowerPoint === | | === PowerPoint === |
|
| |
|
| ===== Terms ===== | | ===== Definitions ===== |
| * An '''event''' is an activity that lasts 24 hours or longer. | | * '''HandoutMaster''': The Handout Master controls what the slides on the audience handouts will look like. The slide image placeholders show where slides are placed on the master. |
| * An '''appointment''' is an activity that does not involve reserving resources or inviting other people. | | * '''NotesMaster''': The Notes Master lets you alter the appearance of the “Notes Page” presentation view. |
| * A '''meeting''' is an appointment for which you reserve a period of time, invite people to, or reserve resources. | | * '''ShapeRange''': Represents a subset of the Shapes in a Slide. |
| A more detailed description of this terms can be found [http://www.knowledgewave.com/blog/msoffice/outlook/whats-the-dif-events-appointments-and-meeting-requests-in-microsoft-outlook-2013.html here]. | | * '''SlideMaster''': A Slide Master is the top slide in a hierarchy of slides that stores information about the theme and slide layouts of a presentation, including the background, color, fonts, effects, placeholder sizes, and positioning. |
| | | * The '''SlideNumber''' property of a Slide object is the actual number that appears in the lower-right corner of the Slide when you display slide numbers.<br> This number is determined by the number of the Slide within the Presentation (the '''SlideIndex''' property value) and the starting slide number for the Presentation (the FirstSlideNumber property value). |
| | * '''SlideRange''': Represents a subset of the Slides in a Presentation. |
| | * '''Template''': A template is a theme plus some content for a specific purpose—such as a sales presentation, a business plan, or a classroom lesson.<br>So a template has design elements that work together (colors, fonts, backgrounds, effects) and boilerplate content that you augment to tell your story. Details can be found [https://support.microsoft.com/en-us/office/understand-the-difference-between-powerpoint-templates-and-themes-e2408e10-e015-43b3-8b29-b99d128ae448#bm1 here]. |
| | * '''Theme''': A theme is a predefined set of colors, fonts, and visual effects that you apply to your slides for a unified, professional look. Details can be found [https://support.microsoft.com/en-us/office/understand-the-difference-between-powerpoint-templates-and-themes-e2408e10-e015-43b3-8b29-b99d128ae448 here]. |
| | * '''TitleMaster''': The Title Master controls "title" slides. Typically just the first slide of your presentation. |
| ===== Concepts ===== | | ===== Concepts ===== |
| You can get an overview of the concepts of Outlook on [https://docs.microsoft.com/en-us/office/vba/powerpoint/concepts/concepts-powerpoint-vba-reference this website]. | | You can get an overview of the concepts of PowerPoint on [https://docs.microsoft.com/en-us/office/vba/powerpoint/concepts/concepts-powerpoint-vba-reference this website]. |
| | |
| ====== Events ======
| |
| Outlook provides a wide range of events through which it can notify your script that a significant change has occurred. For example, Outlook events can notify your script when a new mail arrives in the InBox.<br>
| |
| To receive notification of a significant event, write an event-handler procedure. This is a function that Outlook calls when the event is called. The code you put in the event handler allows your program to respond appropriately to the event and, in some cases, even lets your program cancel the default action associated with the event, such as preventing a mail item from being sent.
| |
| | |
| '''Types of Events'''<br>
| |
| | |
| Outlook events can be divided into two main categories: item-level events and application-level events.
| |
| | |
| '''Item-level events''' pertain to a particular item. Some examples when an event gets triggered:
| |
| * An item has been opened, sent, posted, saved or closed,
| |
| * the user has replied to or forwarded a message or initiated a custom action,
| |
| * an item property has changed.
| |
| | |
| '''Application-level events''' typically pertain to more than the items associated with a particular Outlook form. Events can pertain to
| |
| * the application itself,
| |
| * to explorer collections and windows,
| |
| * inspector collections and windows,
| |
| * folders and folders collections,
| |
| * items collections,
| |
| * synchronization objects.
| |
| <br>
| |
| The following list describes the most commonly used events:
| |
| | |
| * '''Application.ItemSend'''<br> occurs whenever an Microsoft Outlook item is sent, either by the user through an Inspector (before the inspector is closed, but after the user clicks the Send button) or when the Send method for an Outlook item, such as MailItem, is used in a program.
| |
| * '''Application.NewMailEx'''<br>Occurs when a new item is received in the Inbox. This does only work for your primary inbox. To monitor shared mailboxes or mailboxes of other users use the ItemAdd event.
| |
| * '''Item.PropertyChange'''<br>Occurs when an explicit built-in property (e.g. Subject) of an instance of the parent object (e.g. mail or contact item)is changed.
| |
| * '''Items.ItemAdd'''<br>Occurs when one or more items are added to the specified collection.<br>This event gets triggered as well when a mail has been sent and the sent mail gets moved to the "Sent Mail" folder.
| |
| | |
| '''Responding to Events'''<br>
| |
| The following example (reduced to the minimum) shows how to handle events:
| |
| <syntaxhighlight lang="autoit">
| |
| Global $oOL = _OL_Open()
| |
| Global $oTemp = ObjEvent($oOL, "oOL_") ; Create the application-level event handler
| |
| While 1
| |
| Sleep(10)
| |
| WEnd
| |
| Func oOL_NewMailEx($sEntryIDs)
| |
| Local $iItemCount, $oItem
| |
| Local $aEntryIDs = StringSplit($sEntryIDs, ",", $STR_NOCOUNT) ; multiple EntryIDs are separated by ,
| |
| $iItemCount = UBound($aEntryIDs)
| |
| ConsoleWrite("OutlookEX UDF Example Script - " & ($iItemCount = 1 ? "new item has" : "new items have") & " arrived!" & @CRLF & @CRLF)
| |
| For $i = 0 To $iItemCount - 1
| |
| $oItem = $oOL.Session.GetItemFromID($aEntryIDs[$i], Default) ; Translate the EntryID string to the item object
| |
| ConsoleWrite("From: " & $oItem.SenderName & @CRLF & "Subject: " & $oItem.Subject & @CRLF & "Class: " & $oItem.Class & " (43=Mail, 53=MeetingRequest ...)" & @CRLF)
| |
| Next
| |
| EndFunc
| |
| </syntaxhighlight>
| |
| More examples come with the UDF.
| |
|
| |
|
| ===== Object model ===== | | ===== Object model ===== |
| The Outlook object model is described [https://docs.microsoft.com/en-us/office/vba/api/overview/outlook/object-model here]. | | The PowerPoint object model is described [https://docs.microsoft.com/en-us/office/vba/api/overview/powerpoint/object-model here].<br> |
| | | A very good description of the object model tree can be found [https://www.codevba.com/PowerPoint/ here]. |
| == Folders ==
| |
| It does not matter where an item is stored. You can access any folder and get/create/modify items there.
| |
| | |
| Folders you can access:
| |
|
| |
| {| style="border: 1px solid darkgray" cellspacing=0 cellpadding=5px
| |
| |-
| |
| ! style="border: 1px solid darkgray" | Syntax
| |
| ! style="border: 1px solid darkgray" | Folder you access
| |
| |-
| |
| | style="border: 1px solid darkgray" | "rootfolder\subfolder\...\subfolder"
| |
| | style="border: 1px solid darkgray" | any '''public folder''' or any folder of the current user (replace rootfolder with * to access the root folder of your mailbox)
| |
| |-
| |
| | style="border: 1px solid darkgray" | "\\rootfolder"
| |
| | style="border: 1px solid darkgray" | default folder of '''another user''' (class specified by $iOL_FolderType) (replace "rootfolder" with "*" to access your mailbox)
| |
| |-
| |
| | style="border: 1px solid darkgray" | "\\rootfolder\\subfolder\...\subfolder"
| |
| | style="border: 1px solid darkgray" | subfolder of the default folder of '''another user''' (class specified by $iOL_FolderType)
| |
| |-
| |
| | style="border: 1px solid darkgray" | "\\rootfolder\subfolder\..\subfolder"
| |
| | style="border: 1px solid darkgray" | subfolder of '''another user'''
| |
| |-
| |
| | style="border: 1px solid darkgray" | ""
| |
| | style="border: 1px solid darkgray" | default folder of the '''current user''' (class specified by $iOL_FolderType)
| |
| |-
| |
| | style="border: 1px solid darkgray" | "\subfolder"
| |
| | style="border: 1px solid darkgray" | subfolder of the default folder of the '''current user''' (class specified by $iOL_FolderType)
| |
| |}
| |
| | |
| '''Note:''' You need to use different formats to access '''public folders''' and the mailbox of '''other users'''!
| |
| | |
| "rootfolder" is one of the following:
| |
| * Mailbox name, e.g. "John.Doe@company.com"
| |
| * Display name, e.g. "John Doe"
| |
| | |
| For details please see the item specific section below.
| |
| | |
| === Search folders ===
| |
| As of January 2018 the UDF supports Search Folders as well. Please have a look at functions _OL_SearchFolder*.
| |
| | |
| == Naming pattern ==
| |
| If a method can be used for more than one item type (e.g. mail, calendar and notes) the function is called _OL_ItemXXX else the function is named like the item type e.g. _OL_CalendarXXX
| |
| | |
| == Outlook security ==
| |
| [[File:outlook_security_warning_1.gif|frame|alt=Outlook Security Warning|Outlook Security Warning]] | |
| Some Outlook objects (address book, mail items ...) including their properties and methods are protected by security settings.
| |
| Accessing such objects makes the Outlook Object Model Guard present a popup warning like "a program is trying to access your Address book or Contacts" or "a program is trying to access e-mail addresses you have stored in Outlook...".
| |
| | |
| However, the Outlook Security Warning message does not appear if a valid Anti-Virus is installed.
| |
| | |
| | |
| A small function (''_OL_Warnings.au3''), which has to be compiled and run separately, clicks away all Outlook Security Warnings. Setting parameter ''$fOL_WarningClick'' to ''True'' when you call function ''_OL_Open()'' runs the ''_OL_Warnings.exe''.
| |
| The ''_OL_Warnings.exe'' stays active and clicks away all warnings until the calling script is ended.
| |
| | |
| It's written for an english language environment but can easily be adopted to other languages.
| |
| | |
| == Call a function ==
| |
| Some functions need to accept a lot of parameters when a user needs to set many properties of an item. Let's say you want to create a mail item and pass subject, bodyformat, body and importance to the _OL_ItemCreate function.
| |
| Most functions accept up to 10 properties as parameters or an unlimited number of properties as a zero based one-dimensional array.
| |
| | |
| The following two examples are equivalent:
| |
| <syntaxhighlight lang="autoit">
| |
| $oItem = _OL_ItemCreate($oOutlook, $olMailItem, "*\Outlook-UDF-Test\TargetFolder\Mail", "", "Subject=TestMail", "Importance=" & $olImportanceHigh, "BodyFormat=" & $olFormatHTML, _
| |
| "HTMLBody=Bodytext in <b>bold</b><img src='cid:The_Outlook.jpg'>Embedded image.")
| |
| </syntaxhighlight>
| |
| or
| |
| <syntaxhighlight lang="autoit">
| |
| Global $aProperties[100] = ["Subject=TestMail", "Importance=" & $olImportanceHigh, "BodyFormat=" & $olFormatHTML, "HTMLBody=Bodytext in <b>bold</b><img src='cid:The_Outlook.jpg'>Embedded image."]
| |
| $oItem = _OL_ItemCreate($oOutlook, $olMailItem, "*\Outlook-UDF-Test\TargetFolder\Mail", "", $aProperties)
| |
| </syntaxhighlight>
| |
| Empty properties in the passed array are ignored.
| |
|
| |
|
| == Example Scripts == | | == Example Scripts == |
| === For single functions === | | === For single functions === |
| Every function of the UDF comes with an example script (except internal functions). The example script is named like the function. | | Every function of the UDF comes with an example script (except internal functions). The example script is named like the function. |
| ==== Test Environment ====
| |
| Every example script calls function _OL_TestEnvironment.au3. This function creates a test environment to make sure each function delivers a predictable result independant of the system it is running on and to make sure the Outlook environment of the user is left untouched.<br>
| |
| The test environment is created as folder "Outlook-UDF-Test" plus subfolders and multiple items in your mailbox. This folders and items are manipulated by the example scripts.<br>
| |
| _OL_TestEnvironment.au3 can directly be called by the user. It then displays a GUI where the user can save some settings for the example scripts or create and delete the test environment manually.<br>The test environment is created by every example script but is not deleted after the script has ended. To remove the test environment run _OL_TestEnvironment.au3 and delete the test environment manually.
| |
|
| |
|
| === Extended Examples === | | === Extended Examples === |
| Example scripts which describe more than a single function of the UDF are prefixed with ''_OL_Example_''. | | Example scripts which describe more than a single function of the UDF are prefixed with ''_PPT_Example_''. |
|
| |
|
| == Function specific pages == | | == Function specific pages == |
| The following pages contain information for the functions that can be used for many different item types. | | The following pages contain information for the functions that can be used for many different item types. |
| === Find an Item === | | === Find an Item === |
| Further information on how to find items: [[OutlookEX UDF - Find Items]] | | Further information on how to ...: [[Link]] |
| === Forward an Item ===
| |
| Further information on how to forward items: [[OutlookEX UDF - Forward Items]]
| |
| | |
| == Item specific pages ==
| |
| The following pages contain information for each of the Outlook item types supported by the OutlookEX UDF.
| |
| === Appointment Item ===
| |
| Further information about wrapper functions plus tips & tricks for appointment items: [[OutlookEX UDF - Appointment Item]]
| |
| === Folder Item ===
| |
| Further information about how to access and manipulate folders: [[OutlookEX UDF - Folder Item]]
| |
| === Mail Item ===
| |
| Further information about wrapper functions plus tips & tricks for mail items: [[OutlookEX UDF - Mail Item]]
| |
| === Meeting Item ===
| |
| Further information about wrapper functions plus tips & tricks for meeting items: [[OutlookEX UDF - Meeting Item]]
| |
| | |
| == Known issues ==
| |
| Some features of Microsoft's Office products are proprietary and cannot readily be manipulated.<br>
| |
| Sometimes workarounds are required. [[Known issues with Microsoft Office automation.|This page]] is dedicated to identifying those issues, provide explanations and list solutions or workarounds.
| |
| | |
| === Attachment in GMail ===
| |
| "When I attach a PDF with the Outlook UDF the attachment gets renamed to 'noname' with no extension".<br />
| |
| When you search the web for "gmail attachment noname" you get a lot of hits. Seems it is a problem with GMail.
| |
| | |
| === HTML body shown as WINMAIL.DAT ===
| |
| "I have successfully inserted an HTML body and a PDF attachment. However, Thunderbird and SquirrelMail clients do not show the HTML and only show a WINMAIL.DAT attachment."<br />
| |
| This has been discussed [https://www.autoitscript.com/forum/topic/158418-outlookex-udf-help-support-iii/?page=35#comment-1345813 here].<br>
| |
| Another good explanation including Transport Neutral Encapsulation Format (TNEF) can be found [https://support.microsoft.com/en-us/help/290809/how-e-mail-message-formats-affect-internet-e-mail-messages-in-outlook here].
| |
| | |
| === Mail in RTF format ===
| |
| I think RTF is not supported by Outlook and was introduced by "accident". Described in this - quite old - [http://www.vbforums.com/showthread.php?229250-RESOLVED-Write-RTF-to-outlook-mailitem&p=1352438&viewfull=1#post1352438 thread].
| |
| | |
| == Debugging ==
| |
| === Running script as Administrator ===
| |
| It seems that the process that starts or hooks into Outlook needs to be run with the same [http://social.msdn.microsoft.com/Forums/office/en-US/e661d9d9-0f61-4320-9d83-6942593dcdd4/problem-in-starting-ms-outlook-from-c-application?forum=outlookdev permissions] as Outlook.
| |
| | |
| You get the following error when setting _OL_ErrorNotify(2):
| |
| | |
| NumberHex = 800401E3
| |
| Number = -2147221021
| |
| WinDesciption = Operation Unavailable
| |
| | |
| === Office trial version ===
| |
| The trial version of Office comes without COM components. You get @error = 1 from _OL_Open.
| |
| | |
| Installing the full Office product over a trial doesn't seem to help. You need to uninstall the trial and then re-install the full product.
| |
| | |
| === COM error 0x80040004 - action cancelled ===
| |
| Group Policy settings might deny all "unsafe" actions. Please see this [https://www.autoitscript.com/forum/topic/190964-outlookex-udf-help-support-iv/?do=findComment&comment=1437641 post].
| |
| | |
| === All kind of strange return codes ===
| |
| You get COM errors like
| |
| * 0x800706BA - The RPC server is unavailable
| |
| * 0x800706BE - The remote procedure call failed
| |
| * or strange return values from all kind of _OL_* functions.
| |
| | |
| Outlook (starting with Outlook 2007 SP2) shuts itself down if there is no open window (which is always true when Outlook was not running when _OL_Open is being called) and there is no open reference to an Outlook item (mail, appointment ...).
| |
| | |
| This is described in the following MSDN article: "[http://msdn.microsoft.com/en-us/library/dd239276.aspx Application Shutdown Changes in Outlook 2007 SP2]"
| |
|
| |
|
| So a bug in the UDF or your code can cause Outlook to shut down prematurely.
| | == Tips and Tricks == |
| | === SlideShow === |
| | To hide a Slide during a Slide Show use the following code: |
| | <syntaxhighlight lang="autoit">$oPresentation.Slides(x).SlideShowTransition.Hidden = True ; Replace x with the SlideIndex or Name property of the Slide to hide</syntaxhighlight> |