Author: derek Date: Fri Jun 8 01:20:24 2007 New Revision: 273 Removed: sofaswitch/trunk/callflow/docs/description.sgml Modified: sofaswitch/trunk/callflow/docs/app1.sgml sofaswitch/trunk/callflow/docs/chap2.sgml sofaswitch/trunk/callflow/src/callflow.cpp sofaswitch/trunk/callflow/src/callflow.h sofaswitch/trunk/callflow/src/canvas.cpp sofaswitch/trunk/callflow/src/canvas.h sofaswitch/trunk/callflow/src/dnd.cpp Log: Doc tidyups. Get it to display online help documents. Add description on the generation of the help. Now, we have to get the figures all working correctly. Modified: sofaswitch/trunk/callflow/docs/app1.sgml ============================================================================== --- sofaswitch/trunk/callflow/docs/app1.sgml (original) +++ sofaswitch/trunk/callflow/docs/app1.sgml Fri Jun 8 01:20:24 2007 @@ -2,10 +2,10 @@ <title>Building these docs</title> <para> The documentation for %callflow was generated from multiple -<literal>.sgml</literal> and <literal>.xml</literal files. The utility -<screenshot> +<literal>.sgml</literal> and <literal>.xml</literal> files. The utility +<screen> xsltproc -</screenshot> +</screen> was used to process the supplied files to generate <literal>html</literal> files and several auxillary help files. The generated files were compressed into one <literal>.zip</literal> file. When the &callflow; utility runs, it @@ -15,7 +15,52 @@ <para> The file <literal>makedoc.xsl</literal> contains the stylesheet commands that -are used when converting the docbook file <literal>callflow.xml</literal> into html. +are used when converting the docbook file <literal>callflow.xml</literal> into +html. It is likely that the third line in this file (which specifies the +location of the docbook stylesheet to generate html) will need to be changed +for your particular system. </para> -</sect1> + +<para> +The unix command +<screen> +xsltproc makedoc.xsl callflow.xml +</screen> +will generate output something like +<screen> +Writing ch01.html for chapter +Writing ch02s02.html for sect1 +Writing ch02s03.html for sect1 +Writing ch02s04.html for sect1 +Writing ch02s05.html for sect1 +Writing ch02.html for chapter +Writing ch03s02.html for sect1 +Writing ch03s03.html for sect1 +Writing ch03s04.html for sect1 +Writing ch03s05.html for sect1 +Writing ch03s06.html for sect1 +Writing ch03s07.html for sect1 +Writing ch03s08.html for sect1 +Writing ch03s09.html for sect1 +Writing ch03s10.html for sect1 +Writing ch03s11.html for sect1 +Writing ch03s12.html for sect1 +Writing ch03s13.html for sect1 +Writing ch03s14.html for sect1 +Writing ch03s15.html for sect1 +Writing ch03s16.html for sect1 +Writing ch03.html for chapter +Writing apa.html for appendix +Writing index.html for book +Writing callflow.hhp +Writing callflow.hhc +</screen> +Once the actual html is generated, the zip file must be created. This zip file +contains the files generated by the <literal>xsltproc</literal> command. On +Unix, the command is +<screen> +zip doc.zip *.html *.hh* +</screen> +</para> + </appendix> Modified: sofaswitch/trunk/callflow/docs/chap2.sgml ============================================================================== --- sofaswitch/trunk/callflow/docs/chap2.sgml (original) +++ sofaswitch/trunk/callflow/docs/chap2.sgml Fri Jun 8 01:20:24 2007 @@ -20,23 +20,22 @@ <title>Hello World example</title> <para> Perhaps the simplest example of a graph you can create is the standard "Hello -World" example, shown here, in figure <xref linkend="helloworldexample"/>. +World" example, shown here, in <xref xrefstyle="select: title" linkend="helloworldexample"/>. <figure id="helloworldexample"> -<title>The obligatory Hello World example</title> -<mediaobject> -<imageobject> +<title>The standard "Hello World" example</title> +<mediaobject><imageobject> <imagedata fileref="helloworld.png" align="center" format="PNG"></imagedata> -</imageobject> -</mediaobject> +</imageobject></mediaobject> </figure> - -An example of a simple call flow graph. The properties of the Python object in the middle have been adjusted to contain - code to print text to the console. On execution, a text message is sent to the console. +The properties of the Python object in the middle have been adjusted to contain +code to print text to the console. On running the Python code, a text message +is sent to the console. </para> <para> Python will start executing at the very top box, process the code in the -middle, and then terminate at the bottom. The operation of the three boxes (top to bottom) is +middle, and then terminate at the bottom. The operation of the three boxes (top +to bottom) is <itemizedlist> <listitem><para>On loading of this graph, execution will start at this box. It is an error to have two such flow generation boxes on the page.</para></listitem> @@ -49,11 +48,21 @@ pages are not influenced. </para></listitem> </itemizedlist> </para> -<para>Program flow is invariably top to -bottom. Arrows are drawn on the output and input of each box to indicate where -the flow is going. You will notice four black circles, filled, on this -graph. They indicate a connection between the different entities. +<para> +Program flow is invariably top to bottom. Arrows are drawn on the output and +input of each box to indicate where the flow is going. You will notice four +black circles, filled, on this graph. They indicate a connection between the +different entities. </para> + +<para> +When Python code generated from the above graph is run, several messages to and +from the server. First, there is a message to the server saying that a new +entity has been created, but without a specific &sofaswitch; identity. The +server supplies a specific &sofaswitch; identity. Then, the identity disappears +as the generated Python code completes. +</para> + </sect1> <sect1> @@ -69,7 +78,7 @@ initialisation, increment operator, and termination condition, consist of Python code that is set in the preferences at the beginning of the for loop (right mouse button on the for loop entity). A simple example of a for loop is -shown in figure <xref linkend="forloopexample"/>. +shown in <xref linkend="forloopexample"/>. <figure id="forloopexample"> <title>Example of a for loop</title> <mediaobject> @@ -93,8 +102,8 @@ <sect1> <title>Event handling</title> <para> -We describe the handling of events in this section, with a simple example. -Consider the figure <xref linkend="simpleeventexample"/>. +We describe the handling of events in this section, with a simple example, +shown in <xref linkend="simpleeventexample"/>. <figure id="simpleeventexample"> <title>Example of event handling</title> <mediaobject> @@ -169,13 +178,13 @@ <sect1> -<title>Trivial transfer audio</title> +<title>Trivial transfer of audio</title> <para> Key to the operation of &sofaswitch; is the ability to move audio from one entity to another. This audio passes directly betweeen entities, and does not go via the server. The &sofaswitch; entities themselves worry about the transport of the data. The trivial example in -figure <xref linkend="trivialtransferexample"/> shows the transfer of audio from +<xref linkend="trivialtransferexample"/> shows the transfer of audio from the sound entity back to the sound entity. Consequently, audio that is captured at the mic will be directed to the speaker. The sound entity has therefore been told to talk to itself. @@ -210,8 +219,8 @@ <sect1> <title>Transfer audio, and timer example</title> <para> -We describe the handling of events in this section, with a simple example. -Consider the figure <xref linkend="amtestexample"/>. +We describe the handling of events in this section, with a simple example +(<xref linkend="amtestexample"/>). <figure id="amtestexample"> <title>Example of audio transfer between &sofaswitch; nodes, and timers.</title> Modified: sofaswitch/trunk/callflow/src/callflow.cpp ============================================================================== --- sofaswitch/trunk/callflow/src/callflow.cpp (original) +++ sofaswitch/trunk/callflow/src/callflow.cpp Fri Jun 8 01:20:24 2007 @@ -11,8 +11,11 @@ #include "wx/wx.h" #endif -#include <wx/image.h> + + #include <wx/filename.h> +#include <wx/image.h> + #include <wx/listctrl.h> #include <wx/textfile.h> @@ -72,6 +75,12 @@ #include "canvas.h" #include "callflow.h" +#if USE_HTML_HELP +#include "wx/html/helpctrl.h" +#include "wx/filesys.h" +#include "wx/fs_zip.h" +#endif + BEGIN_EVENT_TABLE(MyFrame, wxFrame) EVT_SIZE(MyFrame::OnSize) EVT_MENU ( wxH_CONTROLSCOMPILE, MyFrame::OnCompile) @@ -117,6 +126,19 @@ bool MyApp::OnInit() { +#if USE_HTML_HELP +#if wxUSE_GIF + // Required for images in the online documentation + wxImage::AddHandler(new wxGIFHandler); + wxImage::AddHandler(new wxPNGHandler); +#endif // wxUSE_GIF + + // Required for advanced HTML help +#if wxUSE_STREAMS && wxUSE_ZIPSTREAM && wxUSE_ZLIB + wxFileSystem::AddHandler(new wxZipFSHandler); +#endif +#endif // wxUSE_HTML + MyFrame *frame = new MyFrame (wxT("Callflow"), wxPoint(20,20), wxSize(600,450)); @@ -138,6 +160,9 @@ MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size) : wxFrame((wxFrame *)NULL, -1, title, pos, size) +#if USE_HTML_HELP + , callflowHtmlHelp(wxHF_EMBEDDED|wxHF_DEFAULT_STYLE) +#endif { // create a child control here canvas = new MyCanvas(this); @@ -556,15 +581,32 @@ void MyFrame::OnHelpManual (wxCommandEvent & WXUNUSED(event)) { +#if USE_HTML_HELP + wxHtmlHelpWindow* callflowHelpWindow; + + wxFrame *core = new wxFrame(this, wxID_ANY, wxString(_T("Help window")), + wxDefaultPosition, wxSize(800, 500)); + core->Show(); + + callflowHelpWindow = new wxHtmlHelpWindow; + callflowHtmlHelp.SetHelpWindow(callflowHelpWindow); + + callflowHelpWindow->Create(core, wxID_ANY, wxDefaultPosition, + GetClientSize(), wxTAB_TRAVERSAL|wxNO_BORDER, + wxHF_DEFAULT_STYLE); + callflowHtmlHelp.AddBook(wxFileName(_T("../docs/doc.zip"))); + callflowHtmlHelp.Display(_T("Introduction")); +#else //Respond to menu here - SetStatusText("Get manual has to be written"); + SetStatusText("Get manual has to be written for systems that don't support HTML help"); +#endif } void MyFrame::OnHelpAbout (wxCommandEvent & WXUNUSED(event)) { SetStatusText("Help | About"); - wxMessageBox(_T("Call Flow 1.0.0 \n\nAuthor Derek J Smithies (derek@indranet.co.nz)\n\n Copyright 2006"), _T("About Call Flow")); + wxMessageBox(_T("Call Flow 1.0.0 \n\nAuthor Derek J Smithies <derek@indranet.co.nz>\n\n Copyright 2007"), _T("About Call Flow")); } Modified: sofaswitch/trunk/callflow/src/callflow.h ============================================================================== --- sofaswitch/trunk/callflow/src/callflow.h (original) +++ sofaswitch/trunk/callflow/src/callflow.h Fri Jun 8 01:20:24 2007 @@ -4,6 +4,21 @@ #define _frame_h #include "dnd.h" + +#define USE_HTML_HELP 1 + +#if !wxUSE_HTML +#undef USE_HTML_HELP +#define USE_HTML_HELP 0 +#endif + +#if USE_HTML_HELP +#include <wx/help.h> +#include <wx/cshelp.h> + +class wxHtmlHelpWindow; +#endif + class MyCanvas; /**Enumerate over the different values that the GUI can generate. Each value means to do some action on the flow chart */ @@ -285,6 +300,12 @@ /**Pointer to the vertical toolbar, on the left of the screen */ wxToolBar *tbarVertical; + +#if USE_HTML_HELP + /**The controller of the help, which manages the files etc we look at */ + wxHtmlHelpController callflowHtmlHelp; +#endif + }; #endif Modified: sofaswitch/trunk/callflow/src/canvas.cpp ============================================================================== --- sofaswitch/trunk/callflow/src/canvas.cpp (original) +++ sofaswitch/trunk/callflow/src/canvas.cpp Fri Jun 8 01:20:24 2007 @@ -11,6 +11,7 @@ #include "wx/wx.h" #endif + #if wxUSE_CLIPBOARD #include "wx/dataobj.h" #include "wx/clipbrd.h" @@ -27,6 +28,8 @@ #include "canvas.h" #include "callflow.h" + + BEGIN_EVENT_TABLE (MyCanvas, wxScrolledWindow) EVT_LEFT_DOWN (MyCanvas::OnLeftDown) EVT_LEFT_UP (MyCanvas::OnLeftUp) Modified: sofaswitch/trunk/callflow/src/canvas.h ============================================================================== --- sofaswitch/trunk/callflow/src/canvas.h (original) +++ sofaswitch/trunk/callflow/src/canvas.h Fri Jun 8 01:20:24 2007 @@ -9,7 +9,6 @@ class MyFrame; class MyCanvas; - ///////////////////////////////////////////////////////////////////////////// /**Class that describes activity on the area inside the scrollbars, titlebars Modified: sofaswitch/trunk/callflow/src/dnd.cpp ============================================================================== --- sofaswitch/trunk/callflow/src/dnd.cpp (original) +++ sofaswitch/trunk/callflow/src/dnd.cpp Fri Jun 8 01:20:24 2007 @@ -603,7 +603,11 @@ bool DndShape::Intersects(const wxPoint & testPoint) const { +#if WXWIN_COMPATIBILITY_2_6 + return m_rect.Contains(testPoint); +#else return m_rect.Inside(testPoint); +#endif } void DndShape::SetSelected(bool newIsSelected)