From 9f9f91207f4313feafd2b23077495bd59f72bd01 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Sat, 1 Sep 2012 16:04:54 -0600
Subject: [PATCH] ffi/com: add an ActiveX example to the docs

---
 collects/mysterx/scribblings/mysterx.scrbl  |  5 +-
 collects/scribblings/foreign/active-x.scrbl | 77 +++++++++++++++++++++
 collects/scribblings/foreign/com.scrbl      |  1 +
 3 files changed, 81 insertions(+), 2 deletions(-)
 create mode 100644 collects/scribblings/foreign/active-x.scrbl

diff --git a/collects/mysterx/scribblings/mysterx.scrbl b/collects/mysterx/scribblings/mysterx.scrbl
index 715c318833..32a531b5bd 100644
--- a/collects/mysterx/scribblings/mysterx.scrbl
+++ b/collects/mysterx/scribblings/mysterx.scrbl
@@ -11,8 +11,9 @@ the @tt{IDispatch} interface, and if it publishes type information
 using the @tt{ITypeInfo} interface.
 
 @deprecated[(list @racketmodname[ffi/com] " or " @racketmodname[ffi/unsafe/com])]{
- MysterX formerly provided @as-index{ActiveX} support. We no longer support
- the ActiveX functionality.}
+ MysterX formerly provided @as-index{ActiveX} support; we no longer support
+ that ActiveX functionality, but see 
+ @secref[#:doc '(lib "scribblings/foreign/foreign.scrbl") "active-x"].}
 
 @;MysterX is supported but deprecated; MysterX formerly provided @as-index{ActiveX} support, but ActiveX support has been discontinued.
 
diff --git a/collects/scribblings/foreign/active-x.scrbl b/collects/scribblings/foreign/active-x.scrbl
new file mode 100644
index 0000000000..b19f949f6a
--- /dev/null
+++ b/collects/scribblings/foreign/active-x.scrbl
@@ -0,0 +1,77 @@
+#lang scribble/doc
+@(require scribble/manual
+          "com-common.rkt"
+          (for-label racket/base
+                     ffi/unsafe/com
+                     xml))
+
+@title[#:tag "active-x"]{ActiveX Controls}
+
+An ActiveX control is a COM object that needs a container to manage
+its graphical representation. Although @racketmodname[ffi/com] does
+not provide direct support for ActiveX controls, you can use
+@racketmodname[ffi/com] to drive Internet Explorer as an ActiveX
+container.
+
+The following code demonstrates using Internet Explorer to instantiate
+the ``Sysmon'' ActiveX control that is included with Windows.
+
+@codeblock{
+#lang racket
+(require ffi/com
+	 xml)
+
+;; The control we want to run:
+(define control-progid "Sysmon")
+
+;; Start IE:
+(define ie (com-create-instance "InternetExplorer.Application.1"))
+
+;; Set up an event callback so that we know when the initial document
+;; is ready:
+(define ex (com-make-event-executor))
+(void (thread (lambda () (let loop () ((sync ex)) (loop)))))
+(define ready (make-semaphore))
+(com-register-event-callback ie "DocumentComplete" 
+                             (lambda (doc url) (semaphore-post ready)) 
+                             ex)
+
+;; Navigate to an empty URL to get an initial document:
+(com-invoke ie "Navigate" "")
+(semaphore-wait ready)
+(define doc (com-get-property ie "Document"))
+
+;; Install HTML to show the ActiveX control:
+(com-invoke doc "write"
+            (xexpr->string
+             `(html
+               (head (title "Demo"))
+               (body
+                (object ((class "object")
+                         (CLASSID ,(format 
+                                    "CLSID:~a"
+                                    (let ([s (guid->string 
+                                              (progid->clsid 
+                                               control-progid))])
+                                      ;; must remove curly braces:
+                                      (define len 
+                                        (string-length s))
+                                      (substring s 1 (sub1 len)))))))))))
+
+;; Configure the IE window and show it:
+(com-set-property! ie "MenuBar" #f)
+(com-set-property! ie "ToolBar" 0)
+(com-set-property! ie "StatusBar" #f)
+(com-set-property! ie "Visible" #t)
+
+;; Extract the ActiveX control from the IE document:
+(define ctl (com-get-property 
+	     (com-invoke (com-invoke doc "getElementsByTagName" "object") 
+                         "item" 
+                         0)
+	     "object"))
+
+;; At this point, `ctl' is the ActiveX control;
+;; demonstrate by getting a list of method names:
+(com-methods ctl)
+}
diff --git a/collects/scribblings/foreign/com.scrbl b/collects/scribblings/foreign/com.scrbl
index c791235f1d..cc2d0a094d 100644
--- a/collects/scribblings/foreign/com.scrbl
+++ b/collects/scribblings/foreign/com.scrbl
@@ -60,3 +60,4 @@ to call methods by name and with safe argument marshaling.
 
 @include-section["com-auto.scrbl"]
 @include-section["com-intf.scrbl"]
+@include-section["active-x.scrbl"]