document and fix help menu
authorKonrad Rosenbaum <konrad@silmor.de>
Mon, 26 Aug 2013 20:22:06 +0000 (22:22 +0200)
committerKonrad Rosenbaum <konrad@silmor.de>
Mon, 26 Aug 2013 20:22:06 +0000 (22:22 +0200)
doc/client/helpmenu.html [new file with mode: 0644]
doc/client/index.html
doc/index.html
src/main.cpp
src/main.h
src/smoke.pro

diff --git a/doc/client/helpmenu.html b/doc/client/helpmenu.html
new file mode 100644 (file)
index 0000000..7afc930
--- /dev/null
@@ -0,0 +1,35 @@
+<html>
+<title>Magic Smoke Client Help Menu</title>
+</head>
+<body>
+<h1>Magic Smoke Client Help Menu</h1>
+
+Per default the Help menu of the client shows three "About" entries, which are fixed, and one help entry which points at a default location. The latter can be replaced by one or more custom entries.<p>
+
+You can customize the help menu of the MagicSmoke client to point at the documentation you chose to show to your users.<p>
+
+<h2>Config Locations</h2>
+
+MagicSmoke checks two locations for configuration of the help menu: its data directory (Linux/Mac: <tt>$HOME/.magicSmoke2</tt>; Windows: <tt>%APPDATA%/.magicSmoke2</tt>) and the installation directory where the executable is located. In both locations it checks for a file named <tt>helpMenu.xml</tt> - if found each file is parsed and read into the help menu. If none is found the default entry is used.<P>
+
+<h2>Config Syntax</h2>
+
+The configuration files allow to define active menu items and separators (with optional labels). The syntax is quite simple:<p>
+
+<pre>
+&lt;HelpMenu>
+        &lt;Item label="&amp;Help Index">default:/&lt;/Item>
+        &lt;Item label="Help &amp;Client">default:/client/index.html&lt;/Item>
+        &lt;Separator label="external"/>
+        &lt;Item label="Heise">http://www.heise.de&lt;/Item>
+&lt;/HelpMenu>
+</pre>
+
+The <b>Item</b> tag defines an active menu item. The <b>label</b> attribute defines what is shown as menu entry - if it contains an ampersand the following letter is used as shortcut. The text of the item is the URL of the help file (usually HTML) to be displayed. MagicSmoke uses the default browser for this type of URL to display the help file - usually file: and http: type URLs in combination with HTML files will work regardless of operating system - other URL types or file types may or may not work. The default: URLs are a special case, if a <tt>doc</tt> directory is present in the installation directory then help files are sought there, otherwise they refer to a default URL that is compiled into MagicSmoke (defined in src/smoke.pro).<p>
+
+The <b>Separator</b> tag defines a simple separator line in the menu. The optional <b>label</b> attribute defines a label shown on the separator. Whether the label is actually visible depends on GUI style (e.g. the default Linux style "cleanlooks" does show them, while the default Windows style does not).<p>
+
+Items and Separators are shown in exactly the order they are listed, first the ones from data directory then those from the installation directory.
+
+
+</html>
\ No newline at end of file
index 6764aa5..2f66b03 100644 (file)
@@ -12,6 +12,7 @@ This section of the documentation describes how to use the dedicated Magic Smoke
 <li><a href="config.html">Configuration</a>
 <li>Creating Events and Inventory
 <li>Selling and Shipping
+<li><a href="helpmenu.html">Configuring the Help menu</a></li>
 <li>User Administration
 <li>Templates
 <li>Scripting
index 3c936cc..11e1aa3 100644 (file)
@@ -62,7 +62,7 @@ This software comes with no warranty at all. You use it at your own risk.
  <li><a href="template.html">Web Template Design</a></li>
  <li><a href="prog_odttemplate.html">ODT Template Design</a></li>
  <li><a href="prog_tickettemplate.html">Ticket and Voucher Template Design</a></li>
-</ul></li>
+ </ul></li>
 </ul>
 
 <h2>Programmers Manual</h2>
index 25e5e13..9a7d1a9 100644 (file)
@@ -106,7 +106,9 @@ static inline QString resolveDir(const QString &dirspec)
         return rdir;
 }
 
+#ifndef HOMEPAGE_BASEURL
 #define HOMEPAGE_BASEURL "http://smoke.silmor.de"
+#endif
 
 void MApplication::aboutMS()
 {
@@ -178,31 +180,45 @@ void MApplication::versionDlg()
 }
 
 
-static QList<QPair<QString,QString> > helpUrl;
+struct HelpUrl { 
+        enum Type {None, Item, Separator} type=None;
+        QString label,url;
+        HelpUrl(Type t,QString l,QString u=QString()):type(t),label(l),url(u){}
+};
+static QList<HelpUrl> helpUrl;
+
+static void loadHelpUrlFile(const QString&fname)
+{
+        QFile fd(fname);
+        QList<HelpUrl > urls;
+        //try to open
+        if(fd.open(QIODevice::ReadOnly)){
+                //read config
+                QDomDocument doc;
+                doc.setContent(&fd);
+                QDomNodeList nl=doc.documentElement().childNodes();
+                for(int i=0;i<nl.size();i++){
+                        QDomElement el=nl.at(i).toElement();
+                        if(!el.isElement())continue;
+                        if(el.tagName()=="Item")
+                                urls.append(HelpUrl(HelpUrl::Item, el.attribute("label").trimmed(), el.text().trimmed()));
+                        else if(el.tagName()=="Separator")
+                                urls.append(HelpUrl(HelpUrl::Separator, el.attribute("label").trimmed()));
+                }
+        }
+        //append to url list
+        if(helpUrl.size()>0 && urls.size()>0)helpUrl.append(HelpUrl(HelpUrl::Separator,""));
+        helpUrl.append(urls);
+}
 
-static void initHelpUrl()
+void MApplication::initHelpUrl()
 {
        //check file exists, if not initialize it
-       QFile fd(dataDir+"/helpMenu.xml");
-       if(!fd.exists()){
-               fd.open(QIODevice::WriteOnly);
-               fd.write(QByteArray("<HelpMenu>\n\t<Item label=\"&amp;Help\">default://</Item>\n</HelpMenu>"));
-               fd.close();
-       };
-       //try to open
-       if(fd.open(QIODevice::ReadOnly)){
-               //read config
-               QDomDocument doc;
-               doc.setContent(&fd);
-               QDomNodeList nl=doc.elementsByTagName("Item");
-               for(int i=0;i<nl.size();i++){
-                       QDomElement el=nl.at(i).toElement();
-                       helpUrl.append(QPair<QString,QString>(el.attribute("label").trimmed(), el.text().trimmed()));
-               }
-       }
+       loadHelpUrlFile(dataDir()+"/helpMenu.xml");
+        loadHelpUrlFile(applicationDirPath()+"/helpMenu.xml");
        //fallback
        if(helpUrl.size()<1)
-               helpUrl<<QPair<QString,QString>("&Help","default://");
+               helpUrl<<HelpUrl(HelpUrl::Item,tr("&Help"),tr("default:/index.html","default help URL, if you translate the index.html file, then change this as well"));
 }
 
 QMenu* MApplication::helpMenu()
@@ -211,8 +227,12 @@ QMenu* MApplication::helpMenu()
        QSignalMapper *map=new QSignalMapper(m);
        connect(map,SIGNAL(mapped(int)),qApp,SLOT(help(int)));
        for(int i=0;i<helpUrl.size();i++){
-               QAction*a=m->addAction(helpUrl[i].first,map,SLOT(map()));
-               map->setMapping(a,i);
+                if(helpUrl[i].type==HelpUrl::Separator){
+                        m->addSeparator()->setText(helpUrl[i].label);
+                }else{
+                        QAction*a=m->addAction(helpUrl[i].label,map,SLOT(map()));
+                        map->setMapping(a,i);
+                }
        }
        m->addSeparator();
        m->addAction("About &MagicSmoke",qApp,SLOT(aboutMS()));
@@ -221,14 +241,25 @@ QMenu* MApplication::helpMenu()
        return m;
 }
 
+static inline QUrl convHelpUrl(QUrl s)
+{
+        if(s.scheme()=="default"){
+                static const QString ad=QApplication::applicationDirPath()+"/doc/";
+                if(QFile(ad+"index.html").exists())
+                        return QUrl::fromLocalFile(ad+s.path());
+                else
+                        //TODO: allow different versions?
+                        return HOMEPAGE_BASEURL "/doc/" + s.path();
+        }
+        else return s;
+}
+
+
+
 void MApplication::help()
 {
-       QString d=QApplication::applicationDirPath()+"/doc/index.html";
-       //TODO: fix this to work with GIT and be more generic
-       if(!QFile(d).exists()){
-               d=HOMEPAGE_BASEURL "/doc/"+MSInterface::staticVersionInfo(WOb::VersionPath)+"/index.html";
-       }else d="file:///"+d;
-       QDesktopServices::openUrl(QUrl(d));
+        qDebug()<<"Opening default help...";
+       QDesktopServices::openUrl(convHelpUrl(QUrl("default:/index.html")));
 }
 
 void MApplication::help(int idx)
@@ -237,11 +268,9 @@ void MApplication::help(int idx)
                help();
                return;
        }
-       QString url=helpUrl[idx].second;
-       if(url=="default://" || url=="")
-               help();
-       else
-               QDesktopServices::openUrl(QUrl(url));
+       QUrl u=convHelpUrl(helpUrl[idx].url);
+        qDebug()<<"Opening help:"<<u;
+       QDesktopServices::openUrl(u);
 }
 
 MApplication::MApplication(int&ac,char**av)
@@ -347,11 +376,11 @@ void MApplication::initialize()
         setMyStyle();
         //initialize log file
         initDebug();
-        //init help menu layout
-        initHelpUrl();
         //init localization and profiles
         initLanguage();
         initProfile();
+        //init help menu layout
+        initHelpUrl();
         //init updater
         initUpdater();
 }
index c936f98..df21c91 100644 (file)
@@ -72,6 +72,9 @@ class MAGICSMOKE_EXPORT MApplication:public QApplication
                 ///jump to a specific help page
                void help(int);
                 
+                ///initialize the help menu from config files
+                void initHelpUrl();
+                
                 ///initialize the updater
                 void initUpdater();
                 
index 709ab4f..8fd386a 100644 (file)
@@ -28,6 +28,12 @@ INCLUDEPATH += .
 #make sure exports are ok
 DEFINES += MAGICSMOKE_LIB_BUILD=1
 
+#Base URL of MagicSmoke, 
+# this URL points to the general homepage with downloads, links etc.
+# BASEURL/doc/index.html points to the default documentation
+# you need the triple-backslash to make it a string constant
+DEFINES += HOMEPAGE_BASEURL=\\\"http://smoke.silmor.de\\\"
+
 #images
 RESOURCES += images/files.qrc