dialog.h

Go to the documentation of this file.

/*
 * dialog.h
 *
 * Copyright (C) 2008-2009  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */

#ifndef WAVEPACKET_DIALOG_H__
#define WAVEPACKET_DIALOG_H__

// includes --------------------------------------------------------------------
#include "element.h"
#include "drawer.h"
#include "wave-crypto/wave-crypto.h"


// forward declarations
class Datahash;


namespace dialog {


////////////////////////////////////////////////////////////////////////////////
///
/// \ingroup geometric
/// \defgroup dialog Dialog Library
///
/// \n
/// This is a simple dialog library.  Originally it was intended to be a thin
/// layer on top of other open-source dialog libraries, but I couldn't find any
/// that worked, especially given the dynamic nature of this library.
/// 
/// This interface allows for basic data-driven dialogs with the user.  Think of
/// this as a mini web browser.  The caller of these APIs provides an HTML-like
/// description of the dialog, and the end user can interact with it.
///
/// The goal is that server-side code can send dialog requests (very similar to
/// HTML forms!) to the client, the client can render the dialog (form) in any
/// way they'd like, and then the user choice is returned back to the server.
///
/// The dialog language is intended to be rich enough to give rules plugin
/// writers some control over layout and feel of the dialog (for instance,
/// conversation with NPCs or purchasing from a shop), but keeps enough display
/// up to the client so it can handle constraints such as viewport real estate,
/// etc.
///
////////////////////////////////////////////////////////////////////////////////
/*@{*/


///     Clients will need to provide an object that implements this interface if
///     they want callbacks etc.
///
/// \b  NOTE: the dialog manager does NOT keep a reference to a host object!
///     The caller is responsible for ensuring that host objects last at least
///     as long as the dialogs!
class Host {
public:
        // dialog::Host class interface methods --------------------------------
        virtual void notifySubmit(IN const char * id,
                                IN const Datahash * data) = 0;

protected:
        // virtual destructor --------------------------------------------------
        virtual ~Host(void) throw();

};



/// This is the object that manages dialogs.
///
///     Create one of these for each viewport.  These aren't viewport-aware, but
///     by partitioning your dialog managers by viewport, that lets you specify
///     viewport settings before invoking the manager for display etc.
///
/// \n
/// \b NOTE: clients must supply their own identifiers (opaque strings) to
/// uniquely identify dialogs!
///
///     You should call display like this:
///\code
///         // set viewport to arbitrary rectangle in screen
///         glViewport(x, y, w, h);
///
///         // provide full window (screen) coordinates for display
///         manager->display(screen_w, screen_h);
///\endcode
///     The dialog manager needs the full screen (window) dimensions to properly
///     establish the orthographic projection, but you should call glViewport
///     before calling the manager to display so that clipping occurs.
///
class Manager {
public:
        virtual ~Manager(void) throw();

        // dialog::Manager class interface methods -----------------------------
        virtual smart_ptr<Drawer> getDrawer(void) = 0;
        virtual void registerFactory(IN const char * type,
                                IN smart_ptr<Factory>& factory) = 0;
        virtual Factory * getFactory(IN const char * type) = 0;
        virtual void display(IN int screen_w, IN int screen_h) = 0;
        virtual void cursor(IN int x, IN int y) = 0;
        virtual void button(IN int buttons, IN int state,
                                IN int x, IN int y) = 0;
        virtual void keyboard(IN int key, IN int mods) = 0;
        virtual bool createDialog(IN const char * id,
                                IN int x, IN int y,
                                IN const Datahash * data,
                                IN Host * host) = 0;
        virtual bool doesDialogExist(IN const char * id) = 0;
        virtual void destroyDialog(IN const char * id) = 0;

        // factory methods -----------------------------------------------------
        static smart_ptr<Manager> create(IN smart_ptr<crypto::DESKey>& desKey,
                                IN smart_ptr<Drawer>& drawer);
};



};      // dialog namespace

#endif  // WAVEPACKET_DIALOG_H__