Lindsay Mathieson's newest wxActiveX class has been wrapped into a new

[wxWidgets.git] / wxPython / contrib / activex / wxie / readme.txt

diff --git a/wxPython/contrib/activex/wxie/readme.txt b/wxPython/contrib/activex/wxie/readme.txt
new file mode 100644 (file)
index 0000000..ec3039d
--- /dev/null
+++ b/wxPython/contrib/activex/wxie/readme.txt
@@ -0,0 +1,149 @@
+Lindsay Mathieson
+Email : <lmathieson@optusnet.com.au>
+
+This is prelimanary stuff - the controls need extra methods and events etc,
+feel free to email with suggestions &/or patches.
+
+Tested with wxWindows 2.3.2.
+Built with MS Visual C++ 6.0 & DevStudio
+Minor use of templates and STL
+
+-----------------------------------------------------------
+This sample illustrates using wxActiveX and wxIEHtmlWin too:
+1. Host an arbitrary ActiveX control
+1.1 - Capture and logging of all events from control
+2. Specifically host the MSHTML Control
+
+
+wxActiveX:
+==========
+wxActiveX is used to host and siplay any activeX control, all the wxWindows developer
+needs to know is either the ProgID or CLSID of the control in question.
+
+Derived From:
+- wxWindow
+
+Include Files:
+- wxactivex.h
+
+Source Files:
+- wxactivex.cpp
+
+Event Handling:
+---------------
+- EVT_ACTIVEX(id, eventName, handler) (handler = void OnActiveX(wxActiveXEvent& event))
+- EVT_ACTIVEX_DISPID(id, eventDispId, handler) (handler = void OnActiveX(wxActiveXEvent& event))
+class wxActiveXEvent : public wxNotifyEvent
+    wxString EventName();
+    int ParamCount() const;
+    wxString ParamType(int idx);
+    wxString ParamName(int idx);
+    wxVariant  operator[] (int idx) const;     // parameter by index
+    wxVariant& operator[] (int idx);
+    wxVariant  operator[] (wxString name) const; // named parameters
+    wxVariant& operator[] (wxString name);
+
+
+Members:
+--------
+wxActiveX::wxActiveX(wxWindow * parent, REFCLSID clsid, wxWindowID id = -1);
+- Creates a activeX control identified by clsid
+e.g
+  wxFrame *frame = new wxFrame(this, -1, "test");
+  wxActiveX *X = new wxActiveX(frame, CLSID_WebBrowser);
+
+wxActiveX::wxActiveX(wxWindow * parent, wxString progId, wxWindowID id = -1);
+- Creates a activeX control identified by progId
+e.g.
+  wxFrame *frame = new wxFrame(this, -1, "test");
+  wxActiveX *X = new wxActiveX(frame, "MSCAL.Calendar");
+
+
+wxActiveX::~wxActiveX();
+- Destroys the control
+- disconnects all connection points
+
+- int GetEventCount() const;
+  Number of events generated by control
+
+- const FuncX& GetEvent(int idx) const;
+  Names, Params and Typeinfo for events
+
+HRESULT wxActiveX::ConnectAdvise(REFIID riid, IUnknown *eventSink);
+- Connects a event sink. Connections are automaticlly diconnected in the destructor
+e.g.
+  FS_DWebBrowserEvents2 *events = new FS_DWebBrowserEvents2(iecontrol);
+  hret = iecontrol->ConnectAdvise(DIID_DWebBrowserEvents2, events);
+  if (! SUCCEEDED(hret))
+    delete events;
+
+
+Sample Events:
+--------------
+EVT_ACTIVEX(ID_MSHTML, "BeforeNavigate2",   OnMSHTMLBeforeNavigate2X)
+
+void wxIEFrame::OnMSHTMLBeforeNavigate2X(wxActiveXEvent& event)
+{
+  wxString url = event["Url"];
+
+  int rc = wxMessageBox(url, "Allow open url ?", wxYES_NO);
+
+  if (rc != wxYES)
+    event["Cancel"] = true;
+};
+
+
+wxIEHtmlWin:
+============
+wxIEHtmlWin is a specialisation of the wxActiveX control for hosting the MSHTML control.
+
+Derived From:
+- wxActiveX
+- wxWindow
+
+Event Handling:
+---------------
+- see wxActiveX
+Members:
+--------
+wxIEHtmlWin::wxIEHtmlWin(wxWindow * parent, wxWindowID id = -1);
+- Constructs and initialises the MSHTML control
+- LoadUrl("about:blank") is called
+
+wxIEHtmlWin::~wxIEHtmlWin();
+- destroys the control
+
+void wxIEHtmlWin::LoadUrl(const wxString&);
+- Attempts to browse to the url, the control uses its internal (MS)
+  network streams
+
+bool wxIEHtmlWin::LoadString(wxString html);
+- Load the passed HTML string
+
+bool wxIEHtmlWin::LoadStream(istream *strm);
+- load the passed HTML stream. The control takes ownership of
+  the pointer, deleting when finished.
+
+bool wxIEHtmlWin::LoadStream(wxInputStream *is);
+- load the passed HTML stream. The control takes ownership of
+  the pointer, deleting when finished.
+
+void wxIEHtmlWin::SetCharset(wxString charset);
+- Sets the charset of the loaded document
+
+void wxIEHtmlWin::SetEditMode(bool seton);
+- Sets edit mode. 
+  NOTE: This does work, but is bare bones - we need more events exposed before
+        this is usable as an HTML editor.
+
+bool wxIEHtmlWin::GetEditMode();
+- Returns the edit mode setting
+
+wxString wxIEHtmlWin::GetStringSelection(bool asHTML = false);
+- Returns the currently selected text (plain or HTML text)
+
+wxString GetText(bool asHTML = false);
+- Returns the body text (plain or HTML text)
+
+Lindsay Mathieson
+Email : <lmathieson@optusnet.com.au>