--- /dev/null
+<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>
+<HelpMenu>
+ <Item label="&Help Index">default:/</Item>
+ <Item label="Help &Client">default:/client/index.html</Item>
+ <Separator label="external"/>
+ <Item label="Heise">http://www.heise.de</Item>
+</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
return rdir;
}
+#ifndef HOMEPAGE_BASEURL
#define HOMEPAGE_BASEURL "http://smoke.silmor.de"
+#endif
void MApplication::aboutMS()
{
}
-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=\"&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()
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()));
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)
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)
setMyStyle();
//initialize log file
initDebug();
- //init help menu layout
- initHelpUrl();
//init localization and profiles
initLanguage();
initProfile();
+ //init help menu layout
+ initHelpUrl();
//init updater
initUpdater();
}
projects / konrad/smoke.git / commitdiff