20.1 单个实例和多个实例

依照你的应用程序的性质的不同,你可能允许你的用户同时运行多个你的应用程序的实例,或者你也可能希望同时只能存在一个你的应用程序的实例,如果用户试图打开第二个或者试图通过资源管理器打开多个和你的应用程序关联的文档,它们都将只看到一个应用程序在运行.一种很通用的作法是,让你的用户根据他的工作习惯,自己选择是否允许运行应用程序的多个实例.不过同时运行多个实例有一个大问题是,哪个程序实例首先将配置文件写入磁盘是不一定的,因此用户可能会丢失它们的设置.而且多个实例运行对一些新手来说也有麻烦,它们可能并没有意识到它们已经运行了应用程序的多个实例.允许同时运行应用程序的多个实例在所有的平台上都是默认选项(除了在Mac平台上通过Finder(查找器)来启动应用程序打开文档的时候),因此,如果你不希望你的应用程序可以运行多个实例, 你需要一些额外的代码.

在Mac OS(也仅在这个系统)上,使用单一实例打开多个文档是非常容易的.你只需要重载MacOpenFile函数,这个函数采用一个wxString类型的文件名作为参数,这个函数将在Mac Os的Finder打开和这个应用程序关联的文档的时候被调用.如果当前还没有运行任何这个应用程序的实例,Mac系统会先启动一个实例,然后再调用这个函数(这个大多数系统不同,在别的系统上,打开文档通常是通过调用应用程序并且将文件名作为参数的方法).如果你使用的是文档/试图框架,你可能并不需要重载这个函数,因为其在Mac OsX上的实现代码如下:

void wxApp::MacOpenFile(const wxString& fileName)
{
    wxDocManager* dm = wxDocManager::GetDocumentManager() ;
    if ( dm )
        dm->CreateDocument(fileName, wxDOC_SILENT) ;
}

然后,即使在Mac Os上,用户还是可以通过直接多次运行程序的方法运行你的应用程序的多个实例. 如果你想检测和禁止运行超过一个应用程序实例,你可以在程序运行之初使用wxSingleInstanceChecker类.这个对象将保持在应用程序的整个生命周期,因此,在你的OnInit函数中,调用其IsAnotherRunning函数检测是否已经有别的实例正在运行,如果返回true,你可以在警告你的用户之后,立刻退出应用程序.如下所示:

bool MyApp::OnInit()
{
    const wxString name = wxString::Format(wxT("MyApp-%s"),
                              wxGetUserId().c_str());
    m_checker = new wxSingleInstanceChecker(name);
    if ( m_checker->IsAnotherRunning() )
    {
        wxLogError(_("Program already running, aborting."));
        return false;
    }
    ... more initializations ...
    return true;
}
int MyApp::OnExit()
{
    delete m_checker;
    return 0;
}

但是,如果你想把旧的实例带到前台,或者你想使用旧的实例打开传递给你的新的实例作为命令行参数的文件,该怎么办呢?一般说来,这需要在这两个实例间进行通讯.我们可以使用wxWidgets提供的高层进程间通讯类来实现.

在下面的例子中,我们将实现应用程序多个实例之间的通讯,以便允许第二个实例询问第一个实例是否它自己打开相应的文件,还是将自己提到前台以便提醒用户它已经请求用这个应用程序来打开文件,下面的代码声明了一个连接类,这个类将被两个实例使用.一个服务器类将被老的实例使用以便监听别的实例的连接请求,一个客户端类将被后来的实例使用以便和老的实例通讯.

#include "wx/ipc.h"
// Server类,用来监听连接请求
class stServer: public wxServer
{
public:
    wxConnectionBase *OnAcceptConnection(const wxString& topic);
};
// Client类,在OnInit函数中被后来的实例使用
class stClient: public wxClient
{
public:
    stClient() {};
    wxConnectionBase *OnMakeConnection() { return new stConnection; }
};
// Connection类,被两个实例同时使用以实现通讯
class stConnection : public wxConnection
{
public:
    stConnection() {}
    ~stConnection() {}
    bool OnExecute(const wxString& topic, wxChar*data, int size,
                   wxIPCFormat format);
};

OnAcceptConnection函数在老实例(Server)中当有新实例(Client)进行连接请求的时候被调用.我们应该首先检查老实例中没有显示任何模式对话框,因为如果有模式对话框,就不可能有别的行为可以引起用户的注意.

// 接收到了来自别的实例的连接请求
wxConnectionBase *stServer::OnAcceptConnection(const wxString& topic)
{
    if (topic.Lower() == wxT("myapp"))
    {
        // 检查没有活动的模式对话框
        wxWindowList::Node* node = wxTopLevelWindows.GetFirst();
        while (node)
        {
            wxDialog* dialog = wxDynamicCast(node->GetData(), wxDialog);
            if (dialog && dialog->IsModal())
            {
                return false;
            }
            node = node->GetNext();
        }
        return new stConnection();
    }
    else
        return NULL;
}

OnExecute函数在客户端实例对其连接对象调用Execute函数的时候被调用. OnExecute函数可以有一个空的参数,这表示它需要将自己提到前台就可以了,否则,它需要检测参数中的文件名指示的文件是否已经被它打开,如果已经打开,将这个文件显示给用户,否则,就打开这个文件,再将其显示给用户.

// 打开别的实例传来的文件参数.
bool stConnection::OnExecute(const wxString& WXUNUSED(topic),
                             wxChar *data,
                             int WXUNUSED(size),
                             wxIPCFormat WXUNUSED(format))
{
    stMainFrame* frame = wxDynamicCast(wxGetApp().GetTopWindow(), stMainFrame);
    wxString filename(data);
    if (filename.IsEmpty())
    {
        // 只需要提升主窗口
        if (frame)
            frame->Raise();
    }
    else
    {
        // 检查文件是否已经打开并且将其显示给用户
        wxNode* node = wxGetApp().GetDocManager()->GetDocuments().GetFirst();
        while (node)
        {
            MyDocument* doc = wxDynamicCast(node->GetData(),MyDocument);
            if (doc && doc->GetFilename() == filename)
            {
                if (doc->GetFrame())
                    doc->GetFrame()->Raise();
                return true;
            }
            node = node->GetNext();
        }
        wxGetApp().GetDocManager()->CreateDocument(
                                         filename, wxDOC_SILENT);
    }
    return true;
}

在OnInit函数中,应用程序应该首先象前面介绍的那样使用wxSingleInstanceChecker检查是否已经运行了多个实例,如果没有别的实例运行,这个实例可以将自己设置位一个Server,等待别的应用程序实例的连接请求,如果已经有实例在运行,就创建一个和那个实例的连接,第二个实例请求第一个实例打开自己被请求的文件或者提升其主窗口.下面是相关的代码:

bool MyApp::OnInit()
{
    wxString cmdFilename; // code to initialize this omitted
    ...
    m_singleInstanceChecker = new wxSingleInstanceChecker(wxT("MyApp"));
    // 如果使用单实例,用IPC检测是否有别的实例.
    if (!m_singleInstanceChecker->IsAnotherRunning())
    {
        // 创建一个服务器
        m_server = new stServer;
        if ( !m_server->Create(wxT("myapp") )
        {
            wxLogDebug(wxT("Failed to create an IPC service."));
        }
    }
    else
    {
        wxLogNull logNull;
        // OK, 已经有一个实例了,创建一个和它之间的连接,然后在自己退出之前发送文件名
        stClient* client = new stClient;
        // 下面的参数在使用DDE的时候被忽略,在使用基于TCP/IP的类的时候代表主机名.
        wxString hostName = wxT("localhost");
        // 创建连接
        wxConnectionBase* connection =
                     client->MakeConnection(hostName,
                                     wxT("myapp"), wxT("MyApp"));
        if (connection)
        {
            // 请求那个已经存在的实例打开文件或者提升它自己
            connection->Execute(cmdFilename);
            connection->Disconnect();
            delete connection;
        }
        else
        {
            wxMessageBox(wxT("Sorry, the existing instance may be
            too busy too respond.\nPlease close any open dialogs and retry."),
                wxT("My application"), wxICON_INFORMATION|wxOK);
        }
        delete client;
        return false;
    }
    ...
    return true;
}

如果你想要了解更多这里用到的进程间通讯的细节,你可以在wxWidgets自带的utils/helpview/src目录中,找到另外一个用在独立的wxWidgets帮助阅读器中的例子,在那个例子中,别的应用程序会通过进程间通讯的方式请求帮助阅读器程序打开某个帮助文件,另外在 wxWidgets的samples/ipc例子中,也演示了wxServer, wxClient和wxConnection的用法.