/******************************************************************************

Copyright (c) 2000 Microsoft Corporation

Module Name:
    HelpHost.idl

Abstract:
    This file contains the declaration of the set of coclasses and interfaces
    that make up the common API shared by Havana and HSS

Revision History:
    Davide Massarenti   (Dmassare)  10/18/2000
        created

******************************************************************************/

import "oaidl.idl";

///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////

//
// Forward declaration.
//
interface IHelpHost;
interface IHelpHostPanes;
interface IHelpHostPane;
interface IHelpHostWindow;

dispinterface DHelpHostEvents;
dispinterface DHelpHostNavEvents;

///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////

[
    object,
    uuid(AF72E210-FA10-4BB5-A348-269D7615A520),
    dual,
    oleautomation,
    helpstring("IHelpHost Interface"),
    pointer_default(unique)
]
interface IHelpHost : IDispatch
{
    ////////////////////////////////////////
    //
    // Read/write Properties
    //
    ////////////////////////////////////////

    [propput] HRESULT FilterName( [in]          BSTR   Value );
    [propget] HRESULT FilterName( [out, retval] BSTR *pValue );


    ////////////////////////////////////////
    //
    // Read-only Properties
    //
    ////////////////////////////////////////

    [propget] HRESULT Namespace       ( [out, retval] BSTR             *pValue );
    [propget] HRESULT Session         ( [out, retval] IDispatch*       *pValue );
    [propget] HRESULT FilterExpression( [out, retval] BSTR             *pValue );
    [propget] HRESULT CurrentUrl      ( [out, retval] BSTR             *pValue );

    [propget] HRESULT Panes           ( [out, retval] IHelpHostPanes*  *pValue );
    [propget] HRESULT HelpHostWindow  ( [out, retval] IHelpHostWindow* *pValue );


    ////////////////////////////////////////
    //
    // Methods
    //
    ////////////////////////////////////////

    //
    // Initialize a session for a namespace
    //
    HRESULT OpenNamespace( [in] BSTR newNamespace ,
                           [in] BSTR filterName   );

    //
    // Navigate to a topic
    //
    HRESULT DisplayTopicFromURL( [in] BSTR    url     ,
                                 [in] VARIANT options );

    //
    // Perform keyword or other lookup
    //
    HRESULT DisplayResultsFromQuery( [in] BSTR    query      ,
                                     [in] BSTR    navMoniker ,
                                     [in] VARIANT options    ); // show only 1

    //
    // Show a UI element
    //
    // <paneName> examples :
    //
    //        //topic/1
    //        //toc/1
    //        //index/1
    //        //search/1
    //
    //
    HRESULT ShowPane( [in] BSTR    paneName   ,  // "path" style name of pane
                      [in] BSTR    query      ,  // prepopulate edit box (optional)
                      [in] BSTR    navMoniker ,
                      [in] VARIANT options    ); // options: hide, doquery


    //
    // Close the Help window
    //
    HRESULT Terminate();
};

[
    object,
    uuid(AF72E211-FA10-4BB5-A348-269D7615A520),
    dual,
    oleautomation,
    helpstring("IHelpHostPanes Interface"),
    pointer_default(unique)
]
interface IHelpHostPanes : IDispatch
{
    [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum(                      [out, retval] IUnknown* *pVal    );
    [propget, id(DISPID_VALUE)  ] HRESULT Item    ( [in] VARIANT vIndex, [out, retval] VARIANT   *ppEntry );
    [propget                    ] HRESULT Count   (                      [out, retval] long      *pVal    );
};

[
    object,
    uuid(AF72E212-FA10-4BB5-A348-269D7615A520),
    dual,
    oleautomation,
    helpstring("IHelpHostPane Interface"),
    pointer_default(unique)
]
interface IHelpHostPane : IDispatch
{
    ////////////////////////////////////////
    //
    // Read/write Properties
    //
    ////////////////////////////////////////

    [propput] HRESULT Visible	( [in         ] VARIANT_BOOL   Value );
    [propget] HRESULT Visible   ( [out, retval] VARIANT_BOOL *pValue );
 
    [propput] HRESULT NavMoniker( [in         ] BSTR   Value );
    [propget] HRESULT NavMoniker( [out, retval] BSTR *pValue );


    ////////////////////////////////////////
    //
    // Read-only Properties
    //
    ////////////////////////////////////////

    [propget] HRESULT Name      ( [out, retval] VARIANT_BOOL *pValue );
    [propget] HRESULT CurrentUrl( [out, retval] BSTR         *pValue );
    [propget] HRESULT WebBrowser( [out, retval] IDispatch*   *pValue );


	//
    // Navigate to a topic
	//
    HRESULT DisplayTopicFromURL( [in] BSTR    url     ,
                                 [in] VARIANT options );

	//
    // Perform keyword or other lookup
	//
    HRESULT DisplayResultsFromQuery( [in] BSTR    query   ,
                                     [in] VARIANT options ); // show only 1

	//
    // Synchronize a navigation pane
	//
    HRESULT Sync( [in] BSTR    url     ,
                  [in] VARIANT options ); // force pane to show

};

[
    object,
    uuid(AF72E213-FA10-4BB5-A348-269D7615A520),
    dual,
    oleautomation,
    helpstring("IHelpHostWindow Interface"),
    pointer_default(unique)
]
interface IHelpHostWindow : IDispatch
{
    ////////////////////////////////////////
    //
    // Read/write Properties
    //
    ////////////////////////////////////////

    //
    // Must be set before opening the namespace.
    //
    [propput] HRESULT ParentWindow( [in         ] long	 HWND );
    [propget] HRESULT ParentWindow( [out, retval] long *pHWND );

    //
    // Recommended to call this before showing the window. Viewers can optionally allow more dynamic setting.
    //
    [propput] HRESULT UILanguage( [in         ] long           LCID  );
    [propget] HRESULT UILanguage( [out, retval] long         *pLCID  );

    [propput] HRESULT Visible   ( [in         ] VARIANT_BOOL   Value );
    [propget] HRESULT Visible   ( [out, retval] VARIANT_BOOL *pValue );


    ////////////////////////////////////////
    //
    // Read-only Properties
    //
    ////////////////////////////////////////

    [propget] HRESULT OriginX   ( [out, retval] long *pValue );
    [propget] HRESULT OriginY   ( [out, retval] long *pValue );
    [propget] HRESULT Width     ( [out, retval] long *pValue );
    [propget] HRESULT Height    ( [out, retval] long *pValue );


    ////////////////////////////////////////
    //
    // Methods
    //
    ////////////////////////////////////////

    //
    // Set the window position and size
    //
    HRESULT MoveWindow( [in] long originX, [in] long originY ,  // corner
                        [in] long width  , [in] long height  ); // size

    //
    // Can we pull this from the interface? Davide will try.
    // Wait (blocked) for user to finish using the Help window
    //
    HRESULT WaitForTermination( [in] long timeOut );   // milliseconds
};

////////////////////////////////////////////////////////////////////////////////

[
    uuid(AF72E220-FA10-4BB5-A348-269D7615A520),
    helpstring("DHelpHostEvents Interface"),
]
dispinterface DHelpHostEvents
{
    properties:
    methods:

    [id(1)] void OnFilterSelectionChanged( 					   	   [in] BSTR filterName );
    [id(2)] void OnFilterModified        ( 					   	   [in] BSTR filterName );
    [id(3)] void OnFilterAdded           ( 					   	   [in] BSTR filterName );
    [id(4)] void OnFilterDeleted	     ( 					   	   [in] BSTR filterName );
    [id(5)] void OnNamespaceChanged      ( [in] BSTR newNamespace, [in] BSTR newFilter  );

    [id(6)] void OnPaneOpened( [in] IHelpHostPane* newPane );
    [id(7)] void OnPaneClosed( [in] IHelpHostPane* oldPane );

    [id(8)] void OnClose();
};

[
    uuid(AF72E221-FA10-4BB5-A348-269D7615A520),
    helpstring("DHelpHostNavEvents Interface"),
]
dispinterface DHelpHostNavEvents
{
    properties:
    methods:

    [id(1)] void OnBeforeNavigate  ( [in] BSTR url, [in] IHelpHostPane* pane, [in, out] VARIANT_BOOL *pCancel );
    [id(2)] void OnDownloadBegin   ( [in] BSTR url, [in] IHelpHostPane* pane                                  );
    [id(3)] void OnDownloadComplete( [in] BSTR url, [in] IHelpHostPane* pane                                  );
    [id(4)] void OnNavigateComplete( [in] BSTR url, [in] IHelpHostPane* pane                                  );
    [id(5)] void OnDocumentComplete( [in] BSTR url, [in] IHelpHostPane* pane                                  );
};