Add doc for wxGraphicsContext.Create(), which is a lightweight context with no target...

[wxWidgets.git] / src / html / helpctrl.cpp

diff --git a/src/html/helpctrl.cpp b/src/html/helpctrl.cpp
index 87be6838d1d4fc3e73e694672fbb56bb58a5c2f8..af46650fa42fd4fd9eb014790dd0a49e0d67998e 100644 (file)
--- a/src/html/helpctrl.cpp
+++ b/src/html/helpctrl.cpp
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        helpctrl.cpp
+// Name:        src/html/helpctrl.cpp

 // Purpose:     wxHtmlHelpController
 // Notes:       Based on htmlhelp.cpp, implementing a monolithic
 //              HTML Help controller class,  by Vaclav Slavik
 // Purpose:     wxHtmlHelpController
 // Notes:       Based on htmlhelp.cpp, implementing a monolithic
 //              HTML Help controller class,  by Vaclav Slavik


@@ -9,10 +9,6 @@
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 

-#if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
-#pragma implementation "helpctrl.h"
-#endif
-

 // For compilers that support precompilation, includes "wx.h".
 #include "wx/wxprec.h"
 
 // For compilers that support precompilation, includes "wx.h".
 #include "wx/wxprec.h"
 


@@ -27,18 +23,15 @@
     #include "wx/intl.h"
 #endif // WX_PRECOMP
 
     #include "wx/intl.h"
 #endif // WX_PRECOMP
 

-#include "wx/html/helpctrl.h"

 #include "wx/busyinfo.h"
 #include "wx/busyinfo.h"

-
-#ifdef __WXGTK__
-    // for the hack in AddGrabIfNeeded()
-    #include "wx/dialog.h"
-#endif // __WXGTK__
+#include "wx/html/helpctrl.h"
+#include "wx/html/helpwnd.h"
+#include "wx/html/helpfrm.h"
+#include "wx/html/helpdlg.h"

 
 #if wxUSE_HELP
     #include "wx/tipwin.h"
 #endif
 
 #if wxUSE_HELP
     #include "wx/tipwin.h"
 #endif

-    

 
 #if wxUSE_LIBMSPACK
 #include "wx/html/forcelnk.h"
 
 #if wxUSE_LIBMSPACK
 #include "wx/html/forcelnk.h"


@@ -47,48 +40,109 @@ FORCE_LINK(wxhtml_chm_support)
 
 IMPLEMENT_DYNAMIC_CLASS(wxHtmlHelpController, wxHelpControllerBase)
 
 
 IMPLEMENT_DYNAMIC_CLASS(wxHtmlHelpController, wxHelpControllerBase)
 

-wxHtmlHelpController::wxHtmlHelpController(int style)
+wxHtmlHelpController::wxHtmlHelpController(int style, wxWindow* parentWindow):
+    wxHelpControllerBase(parentWindow)

 {
 {

+    Init(style);
+}
+
+wxHtmlHelpController::wxHtmlHelpController(wxWindow* parentWindow, int style):
+    wxHelpControllerBase(parentWindow)
+{
+    Init(style);
+}
+
+void wxHtmlHelpController::Init(int style)
+{
+    m_helpWindow = NULL;

     m_helpFrame = NULL;
     m_helpFrame = NULL;

+    m_helpDialog = NULL;
+#if wxUSE_CONFIG

     m_Config = NULL;
     m_ConfigRoot = wxEmptyString;
     m_Config = NULL;
     m_ConfigRoot = wxEmptyString;

+#endif // wxUSE_CONFIG

     m_titleFormat = _("Help: %s");
     m_FrameStyle = style;
     m_titleFormat = _("Help: %s");
     m_FrameStyle = style;

+    m_shouldPreventAppExit = false;

 }
 
 }
 

+

 wxHtmlHelpController::~wxHtmlHelpController()
 {
 wxHtmlHelpController::~wxHtmlHelpController()
 {

+#if wxUSE_CONFIG

     if (m_Config)
         WriteCustomization(m_Config, m_ConfigRoot);
     if (m_Config)
         WriteCustomization(m_Config, m_ConfigRoot);

-    if (m_helpFrame)
+#endif // wxUSE_CONFIG
+    if (m_helpWindow)

         DestroyHelpWindow();
 }
 
 
 void wxHtmlHelpController::DestroyHelpWindow()
 {
         DestroyHelpWindow();
 }
 
 
 void wxHtmlHelpController::DestroyHelpWindow()
 {

-    //if (m_Config) WriteCustomization(m_Config, m_ConfigRoot);
-    if (m_helpFrame)
-        m_helpFrame->Destroy();
+    if (m_FrameStyle & wxHF_EMBEDDED)
+        return;
+
+    // Find top-most parent window
+    // If a modal dialog
+    wxWindow* parent = FindTopLevelWindow();
+    if (parent)
+    {
+        wxDialog* dialog = wxDynamicCast(parent, wxDialog);
+        if (dialog && dialog->IsModal())
+        {
+            dialog->EndModal(wxID_OK);
+        }
+        parent->Destroy();
+        m_helpWindow = NULL;
+    }
+    m_helpDialog = NULL;
+    m_helpFrame = NULL;

 }
 
 void wxHtmlHelpController::OnCloseFrame(wxCloseEvent& evt)
 {
 }
 
 void wxHtmlHelpController::OnCloseFrame(wxCloseEvent& evt)
 {

+#if wxUSE_CONFIG
+    if (m_Config)
+        WriteCustomization(m_Config, m_ConfigRoot);
+#endif // wxUSE_CONFIG
+

     evt.Skip();
 
     OnQuit();
 
     evt.Skip();
 
     OnQuit();
 

-    m_helpFrame->SetController((wxHelpControllerBase*) NULL);
+    if ( m_helpWindow )
+        m_helpWindow->SetController(NULL);
+    m_helpWindow = NULL;
+    m_helpDialog = NULL;

     m_helpFrame = NULL;
 }
 
     m_helpFrame = NULL;
 }
 

+void wxHtmlHelpController::SetShouldPreventAppExit(bool enable)
+{
+    m_shouldPreventAppExit = enable;
+    if ( m_helpFrame )
+        m_helpFrame->SetShouldPreventAppExit(enable);
+}
+

 void wxHtmlHelpController::SetTitleFormat(const wxString& title)
 {
     m_titleFormat = title;
 void wxHtmlHelpController::SetTitleFormat(const wxString& title)
 {
     m_titleFormat = title;

-    if (m_helpFrame)
-        m_helpFrame->SetTitleFormat(title);
+    wxHtmlHelpFrame* frame = wxDynamicCast(FindTopLevelWindow(), wxHtmlHelpFrame);
+    wxHtmlHelpDialog* dialog = wxDynamicCast(FindTopLevelWindow(), wxHtmlHelpDialog);
+    if (frame)
+    {
+        frame->SetTitleFormat(title);
+    }
+    else if (dialog)
+        dialog->SetTitleFormat(title);

 }
 
 }
 

+// Find the top-most parent window
+wxWindow* wxHtmlHelpController::FindTopLevelWindow()
+{
+    return wxGetTopLevelParent(m_helpWindow);
+}

 
 bool wxHtmlHelpController::AddBook(const wxFileName& book_file, bool show_wait_msg)
 {
 
 bool wxHtmlHelpController::AddBook(const wxFileName& book_file, bool show_wait_msg)
 {


@@ -114,77 +168,111 @@ bool wxHtmlHelpController::AddBook(const wxString& book, bool show_wait_msg)
 #else
     wxUnusedVar(show_wait_msg);
 #endif
 #else
     wxUnusedVar(show_wait_msg);
 #endif

-    if (m_helpFrame) 
-        m_helpFrame->RefreshLists();
+    if (m_helpWindow)
+        m_helpWindow->RefreshLists();

     return retval;
 }
 
     return retval;
 }
 

-
-
-wxHtmlHelpFrame *wxHtmlHelpController::CreateHelpFrame(wxHtmlHelpData *data)
+wxHtmlHelpFrame* wxHtmlHelpController::CreateHelpFrame(wxHtmlHelpData *data)

 {
 {

-    return new wxHtmlHelpFrame(data);
+    wxHtmlHelpFrame* frame = new wxHtmlHelpFrame(data);
+    frame->SetController(this);
+    frame->Create(m_parentWindow, -1, wxEmptyString, m_FrameStyle
+#if wxUSE_CONFIG
+        , m_Config, m_ConfigRoot
+#endif // wxUSE_CONFIG
+        );
+    frame->SetTitleFormat(m_titleFormat);
+    frame->SetShouldPreventAppExit(m_shouldPreventAppExit);
+    m_helpFrame = frame;
+    return frame;

 }
 
 }
 

+wxHtmlHelpDialog* wxHtmlHelpController::CreateHelpDialog(wxHtmlHelpData *data)
+{
+    wxHtmlHelpDialog* dialog = new wxHtmlHelpDialog(data);
+    dialog->SetController(this);
+    dialog->SetTitleFormat(m_titleFormat);
+    dialog->Create(m_parentWindow, -1, wxEmptyString, m_FrameStyle);
+    m_helpDialog = dialog;
+    return dialog;
+}

 
 

-void wxHtmlHelpController::CreateHelpWindow()
+wxWindow* wxHtmlHelpController::CreateHelpWindow()

 {
 {

-    if (m_helpFrame)
+    if (m_helpWindow)

     {
     {

-        m_helpFrame->Raise();
-        return ;
+        if (m_FrameStyle & wxHF_EMBEDDED)
+            return m_helpWindow;
+
+        wxWindow* topLevelWindow = FindTopLevelWindow();
+        if (topLevelWindow)
+            topLevelWindow->Raise();
+        return m_helpWindow;

     }
 
     }
 

+#if wxUSE_CONFIG

     if (m_Config == NULL)
     {
     if (m_Config == NULL)
     {

-        m_Config = wxConfigBase::Get(FALSE);
+        m_Config = wxConfigBase::Get(false);

         if (m_Config != NULL)
         if (m_Config != NULL)

-            m_ConfigRoot = _T("wxWindows/wxHtmlHelpController");
+            m_ConfigRoot = wxT("wxWindows/wxHtmlHelpController");

     }
     }

+#endif // wxUSE_CONFIG

 
 

-    m_helpFrame = CreateHelpFrame(&m_helpData);
-    m_helpFrame->SetController(this);
-
-    if (m_Config)
-        m_helpFrame->UseConfig(m_Config, m_ConfigRoot);
-
-    m_helpFrame->Create(NULL, wxID_HTML_HELPFRAME, wxEmptyString, m_FrameStyle);
-    m_helpFrame->SetTitleFormat(m_titleFormat);
+    if (m_FrameStyle & wxHF_DIALOG)
+    {
+        wxHtmlHelpDialog* dialog = CreateHelpDialog(&m_helpData);
+        m_helpWindow = dialog->GetHelpWindow();
+    }
+    else if ((m_FrameStyle & wxHF_EMBEDDED) && m_parentWindow)
+    {
+        m_helpWindow = new wxHtmlHelpWindow(m_parentWindow, -1, wxDefaultPosition, wxDefaultSize,
+            wxTAB_TRAVERSAL|wxNO_BORDER, m_FrameStyle, &m_helpData);
+    }
+    else // wxHF_FRAME
+    {
+        wxHtmlHelpFrame* frame = CreateHelpFrame(&m_helpData);
+        m_helpWindow = frame->GetHelpWindow();
+        frame->Show(true);
+    }

 
 

-    m_helpFrame->Show(TRUE);
+    return m_helpWindow;

 }
 
 }
 

+#if wxUSE_CONFIG

 void wxHtmlHelpController::ReadCustomization(wxConfigBase* cfg, const wxString& path)
 {
     /* should not be called by the user; call UseConfig, and the controller
      * will do the rest */
 void wxHtmlHelpController::ReadCustomization(wxConfigBase* cfg, const wxString& path)
 {
     /* should not be called by the user; call UseConfig, and the controller
      * will do the rest */

-    if (m_helpFrame && cfg)
-        m_helpFrame->ReadCustomization(cfg, path);
+    if (m_helpWindow && cfg)
+        m_helpWindow->ReadCustomization(cfg, path);

 }
 
 void wxHtmlHelpController::WriteCustomization(wxConfigBase* cfg, const wxString& path)
 {
     /* typically called by the controllers OnCloseFrame handler */
 }
 
 void wxHtmlHelpController::WriteCustomization(wxConfigBase* cfg, const wxString& path)
 {
     /* typically called by the controllers OnCloseFrame handler */

-    if (m_helpFrame && cfg)
-        m_helpFrame->WriteCustomization(cfg, path);
+    if (m_helpWindow && cfg)
+        m_helpWindow->WriteCustomization(cfg, path);

 }
 
 void wxHtmlHelpController::UseConfig(wxConfigBase *config, const wxString& rootpath)
 {
     m_Config = config;
     m_ConfigRoot = rootpath;
 }
 
 void wxHtmlHelpController::UseConfig(wxConfigBase *config, const wxString& rootpath)
 {
     m_Config = config;
     m_ConfigRoot = rootpath;

-    if (m_helpFrame) m_helpFrame->UseConfig(config, rootpath);
+    if (m_helpWindow) m_helpWindow->UseConfig(config, rootpath);

     ReadCustomization(config, rootpath);
 }
     ReadCustomization(config, rootpath);
 }

+#endif // wxUSE_CONFIG

 
 //// Backward compatibility with wxHelpController API
 
 bool wxHtmlHelpController::Initialize(const wxString& file)
 {
     wxString dir, filename, ext;
 
 //// Backward compatibility with wxHelpController API
 
 bool wxHtmlHelpController::Initialize(const wxString& file)
 {
     wxString dir, filename, ext;

-    wxSplitPath(file, & dir, & filename, & ext);
+    wxFileName::SplitPath(file, & dir, & filename, & ext);

 
 

-    if (!dir.IsEmpty())
+    if (!dir.empty())

         dir = dir + wxFILE_SEP_PATH;
 
     // Try to find a suitable file
         dir = dir + wxFILE_SEP_PATH;
 
     // Try to find a suitable file


@@ -211,7 +299,7 @@ bool wxHtmlHelpController::Initialize(const wxString& file)
 bool wxHtmlHelpController::LoadFile(const wxString& WXUNUSED(file))
 {
     // Don't reload the file or we'll have it appear again, presumably.
 bool wxHtmlHelpController::LoadFile(const wxString& WXUNUSED(file))
 {
     // Don't reload the file or we'll have it appear again, presumably.

-    return TRUE;
+    return true;

 }
 
 bool wxHtmlHelpController::DisplaySection(int sectionNo)
 }
 
 bool wxHtmlHelpController::DisplaySection(int sectionNo)


@@ -237,23 +325,34 @@ bool wxHtmlHelpController::DisplayTextPopup(const wxString& text, const wxPoint&
     {
         s_tipWindow = new wxTipWindow(wxTheApp->GetTopWindow(), text, 100, & s_tipWindow);
 
     {
         s_tipWindow = new wxTipWindow(wxTheApp->GetTopWindow(), text, 100, & s_tipWindow);
 

-        return TRUE;
+        return true;

     }
     }

+#else
+    wxUnusedVar(text);

 #endif // wxUSE_TIPWINDOW
 
 #endif // wxUSE_TIPWINDOW
 

-    return FALSE;
+    return false;
+}
+
+void wxHtmlHelpController::SetHelpWindow(wxHtmlHelpWindow* helpWindow)
+{
+    m_helpWindow = helpWindow;
+    if (helpWindow)
+        helpWindow->SetController(this);

 }
 
 }
 

-void wxHtmlHelpController::SetFrameParameters(const wxString& title,
+void wxHtmlHelpController::SetFrameParameters(const wxString& titleFormat,

                                    const wxSize& size,
                                    const wxPoint& pos,
                                    bool WXUNUSED(newFrameEachTime))
 {
                                    const wxSize& size,
                                    const wxPoint& pos,
                                    bool WXUNUSED(newFrameEachTime))
 {

-    SetTitleFormat(title);
-    if (m_helpFrame)
-    {
-        m_helpFrame->SetSize(pos.x, pos.y, size.x, size.y);
-    }
+    SetTitleFormat(titleFormat);
+    wxHtmlHelpFrame* frame = wxDynamicCast(FindTopLevelWindow(), wxHtmlHelpFrame);
+    wxHtmlHelpDialog* dialog = wxDynamicCast(FindTopLevelWindow(), wxHtmlHelpDialog);
+    if (frame)
+        frame->SetSize(pos.x, pos.y, size.x, size.y);
+    else if (dialog)
+        dialog->SetSize(pos.x, pos.y, size.x, size.y);

 }
 
 wxFrame* wxHtmlHelpController::GetFrameParameters(wxSize *size,
 }
 
 wxFrame* wxHtmlHelpController::GetFrameParameters(wxSize *size,


@@ -261,75 +360,81 @@ wxFrame* wxHtmlHelpController::GetFrameParameters(wxSize *size,
                                    bool *newFrameEachTime)
 {
     if (newFrameEachTime)
                                    bool *newFrameEachTime)
 {
     if (newFrameEachTime)

-        (* newFrameEachTime) = FALSE;
-    if (size && m_helpFrame)
-        (* size) = m_helpFrame->GetSize();
-    if (pos && m_helpFrame)
-        (* pos) = m_helpFrame->GetPosition();
-    return m_helpFrame;
+        (* newFrameEachTime) = false;
+
+    wxHtmlHelpFrame* frame = wxDynamicCast(FindTopLevelWindow(), wxHtmlHelpFrame);
+    wxHtmlHelpDialog* dialog = wxDynamicCast(FindTopLevelWindow(), wxHtmlHelpDialog);
+    if (frame)
+    {
+        if (size)
+            (* size) = frame->GetSize();
+        if (pos)
+            (* pos) = frame->GetPosition();
+        return frame;
+    }
+    else if (dialog)
+    {
+        if (size)
+            (* size) = dialog->GetSize();
+        if (pos)
+            (* pos) = dialog->GetPosition();
+        return NULL;
+    }
+    return NULL;

 }
 
 bool wxHtmlHelpController::Quit()
 {
     DestroyHelpWindow();
 }
 
 bool wxHtmlHelpController::Quit()
 {
     DestroyHelpWindow();

-    return TRUE;
+    return true;

 }
 
 // Make the help controller's frame 'modal' if
 // needed
 }
 
 // Make the help controller's frame 'modal' if
 // needed

-void wxHtmlHelpController::AddGrabIfNeeded()
-{
-    // So far, wxGTK only
-#ifdef __WXGTK__
-    bool needGrab = FALSE;
-    
-    // Check if there are any modal windows present,
-    // in which case we need to add a grab.
-    for ( wxWindowList::compatibility_iterator node = wxTopLevelWindows.GetFirst();
-          node;
-          node = node->GetNext() )
+void wxHtmlHelpController::MakeModalIfNeeded()
+{
+    if ((m_FrameStyle & wxHF_EMBEDDED) == 0)

     {
     {

-        wxWindow *win = node->GetData();
-        wxDialog *dialog = wxDynamicCast(win, wxDialog);
-
-        if (dialog && dialog->IsModal())
-            needGrab = TRUE;
+        wxHtmlHelpFrame* frame = wxDynamicCast(FindTopLevelWindow(), wxHtmlHelpFrame);
+        wxHtmlHelpDialog* dialog = wxDynamicCast(FindTopLevelWindow(), wxHtmlHelpDialog);
+        if (frame)
+            frame->AddGrabIfNeeded();
+        else if (dialog && (m_FrameStyle & wxHF_MODAL))
+        {
+            dialog->ShowModal();
+        }

     }
     }

-
-    if (needGrab && m_helpFrame)
-        m_helpFrame->AddGrab();
-#endif // __WXGTK__

 }
 
 bool wxHtmlHelpController::Display(const wxString& x)
 {
     CreateHelpWindow();
 }
 
 bool wxHtmlHelpController::Display(const wxString& x)
 {
     CreateHelpWindow();

-    bool success = m_helpFrame->Display(x);
-    AddGrabIfNeeded();
-    return success;    
+    bool success = m_helpWindow->Display(x);
+    MakeModalIfNeeded();
+    return success;

 }
 
 bool wxHtmlHelpController::Display(int id)
 {
     CreateHelpWindow();
 }
 
 bool wxHtmlHelpController::Display(int id)
 {
     CreateHelpWindow();

-    bool success = m_helpFrame->Display(id);
-    AddGrabIfNeeded();
+    bool success = m_helpWindow->Display(id);
+    MakeModalIfNeeded();

     return success;
 }
 
 bool wxHtmlHelpController::DisplayContents()
 {
     CreateHelpWindow();
     return success;
 }
 
 bool wxHtmlHelpController::DisplayContents()
 {
     CreateHelpWindow();

-    bool success = m_helpFrame->DisplayContents();
-    AddGrabIfNeeded();
+    bool success = m_helpWindow->DisplayContents();
+    MakeModalIfNeeded();

     return success;
 }
 
 bool wxHtmlHelpController::DisplayIndex()
 {
     CreateHelpWindow();
     return success;
 }
 
 bool wxHtmlHelpController::DisplayIndex()
 {
     CreateHelpWindow();

-    bool success = m_helpFrame->DisplayIndex();
-    AddGrabIfNeeded();
+    bool success = m_helpWindow->DisplayIndex();
+    MakeModalIfNeeded();

     return success;
 }
 
     return success;
 }
 


@@ -337,10 +442,31 @@ bool wxHtmlHelpController::KeywordSearch(const wxString& keyword,
                                          wxHelpSearchMode mode)
 {
     CreateHelpWindow();
                                          wxHelpSearchMode mode)
 {
     CreateHelpWindow();

-    bool success = m_helpFrame->KeywordSearch(keyword, mode);
-    AddGrabIfNeeded();
+    bool success = m_helpWindow->KeywordSearch(keyword, mode);
+    MakeModalIfNeeded();

     return success;
 }
 
     return success;
 }
 

+/*
+ * wxHtmlModalHelp
+ * A convenience class, to use like this:
+ *
+ * wxHtmlModalHelp help(parent, helpFile, topic);
+ */
+
+wxHtmlModalHelp::wxHtmlModalHelp(wxWindow* parent, const wxString& helpFile, const wxString& topic, int style)
+{
+    // Force some mandatory styles
+    style |= wxHF_DIALOG | wxHF_MODAL;
+
+    wxHtmlHelpController controller(style, parent);
+    controller.Initialize(helpFile);
+
+    if (topic.IsEmpty())
+        controller.DisplayContents();
+    else
+        controller.DisplaySection(topic);
+}
+

 #endif // wxUSE_WXHTML_HELP
 
 #endif // wxUSE_WXHTML_HELP