dialog.h

Go to the documentation of this file.
00001 /*
00002  * dialog.h
00003  *
00004  * Copyright (C) 2008-2009  Thomas A. Vaughan
00005  * All rights reserved.
00006  *
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *     * Redistributions of source code must retain the above copyright
00011  *       notice, this list of conditions and the following disclaimer.
00012  *     * Redistributions in binary form must reproduce the above copyright
00013  *       notice, this list of conditions and the following disclaimer in the
00014  *       documentation and/or other materials provided with the distribution.
00015  *     * Neither the name of the <organization> nor the
00016  *       names of its contributors may be used to endorse or promote products
00017  *       derived from this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
00020  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00026  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  */
00031 
00032 #ifndef WAVEPACKET_DIALOG_H__
00033 #define WAVEPACKET_DIALOG_H__
00034 
00035 // includes --------------------------------------------------------------------
00036 #include "element.h"
00037 #include "drawer.h"
00038 #include "crypto/crypto.h"
00039 
00040 
00041 // forward declarations
00042 class Datahash;
00043 
00044 
00045 namespace dialog {
00046 
00047 
00048 ////////////////////////////////////////////////////////////////////////////////
00049 ///
00050 /// \ingroup geometric
00051 /// \defgroup dialog Dialog Library
00052 ///
00053 /// \n
00054 /// This is a simple dialog library.  Originally it was intended to be a thin
00055 /// layer on top of other open-source dialog libraries, but I couldn't find any
00056 /// that worked, especially given the dynamic nature of this library.
00057 /// 
00058 /// This interface allows for basic data-driven dialogs with the user.  Think of
00059 /// this as a mini web browser.  The caller of these APIs provides an HTML-like
00060 /// description of the dialog, and the end user can interact with it.
00061 ///
00062 /// The goal is that server-side code can send dialog requests (very similar to
00063 /// HTML forms!) to the client, the client can render the dialog (form) in any
00064 /// way they'd like, and then the user choice is returned back to the server.
00065 ///
00066 /// The dialog language is intended to be rich enough to give rules plugin
00067 /// writers some control over layout and feel of the dialog (for instance,
00068 /// conversation with NPCs or purchasing from a shop), but keeps enough display
00069 /// up to the client so it can handle constraints such as viewport real estate,
00070 /// etc.
00071 ///
00072 ////////////////////////////////////////////////////////////////////////////////
00073 /*@{*/
00074 
00075 
00076 ///     Clients will need to provide an object that implements this interface if
00077 ///     they want callbacks etc.
00078 ///
00079 /// \b  NOTE: the dialog manager does NOT keep a reference to a host object!
00080 ///     The caller is responsible for ensuring that host objects last at least
00081 ///     as long as the dialogs!
00082 class Host {
00083 public:
00084         // dialog::Host class interface methods --------------------------------
00085         virtual void notifySubmit(IN const char * id,
00086                                 IN const Datahash * data) = 0;
00087 
00088 protected:
00089         // virtual destructor --------------------------------------------------
00090         virtual ~Host(void) throw();
00091 
00092 };
00093 
00094 
00095 
00096 /// This is the object that manages dialogs.
00097 ///
00098 ///     Create one of these for each viewport.  These aren't viewport-aware, but
00099 ///     by partitioning your dialog managers by viewport, that lets you specify
00100 ///     viewport settings before invoking the manager for display etc.
00101 ///
00102 /// \n
00103 /// \b NOTE: clients must supply their own identifiers (opaque strings) to
00104 /// uniquely identify dialogs!
00105 ///
00106 ///     You should call display like this:
00107 ///\code
00108 ///         // set viewport to arbitrary rectangle in screen
00109 ///         glViewport(x, y, w, h);
00110 ///
00111 ///         // provide full window (screen) coordinates for display
00112 ///         manager->display(screen_w, screen_h);
00113 ///\endcode
00114 ///     The dialog manager needs the full screen (window) dimensions to properly
00115 ///     establish the orthographic projection, but you should call glViewport
00116 ///     before calling the manager to display so that clipping occurs.
00117 ///
00118 class Manager {
00119 public:
00120         virtual ~Manager(void) throw();
00121 
00122         // dialog::Manager class interface methods -----------------------------
00123         virtual smart_ptr<Drawer> getDrawer(void) = 0;
00124         virtual void registerFactory(IN const char * type,
00125                                 IN smart_ptr<Factory>& factory) = 0;
00126         virtual Factory * getFactory(IN const char * type) = 0;
00127         virtual void display(IN int screen_w, IN int screen_h) = 0;
00128         virtual void cursor(IN int x, IN int y) = 0;
00129         virtual void button(IN int buttons, IN int state,
00130                                 IN int x, IN int y) = 0;
00131         virtual void keyboard(IN int key, IN int mods) = 0;
00132         virtual bool createDialog(IN const char * id,
00133                                 IN int x, IN int y,
00134                                 IN const Datahash * data,
00135                                 IN Host * host) = 0;
00136         virtual bool doesDialogExist(IN const char * id) = 0;
00137         virtual void destroyDialog(IN const char * id) = 0;
00138 
00139         // factory methods -----------------------------------------------------
00140         static smart_ptr<Manager> create(IN smart_ptr<crypto::DESKey>& desKey,
00141                                 IN smart_ptr<Drawer>& drawer);
00142 };
00143 
00144 
00145 
00146 };      // dialog namespace
00147 
00148 #endif  // WAVEPACKET_DIALOG_H__
00149