7. Documentation
7.1 Help
Not much has to be said about help, it's simply a necessity.
Sample code
#include <wx/fs_zip.h> // ZIP filesystem support
#include <wx/html/helpctrl.h> // html help support
//! global help provider
wxHtmlHelpController *g_help = NULL;
class AppFrame: public wxFrame {
...
void OnHelp (wxCommandEvent &event);
...
wxHtmlHelpController& GetHelpController() {return *g_help; }
...
}
bool App::OnInit () {
...
wxFileSystem::AddHandler (new wxZipFSHandler);
g_help = new wxHtmlHelpController;
LocateHelp ();
...
}
bool App::LocateHelp (bool force) {
wxString appPath = wxFileName(argv[0]).GetPath (wxPATH_GET_VOLUME);
if (appPath.IsEmpty()) appPath = wxGetCwd();
wxString appName = wxFileName(argv[0]).GetName();
#ifdef __WXMAC__
appPath += appName + _T(".app/Contents/Resources"));
#endif
wxString helpfile = appPath + wxFileName::GetPathSeparator() + appName + _T(".htb");
wxConfig* cfg = new wxConfig (g_appname);
helpfile = cfg->Read (HELPFILE, helpfile);
delete cfg;
while (force || !helpfile.IsEmpty() && !g_help->AddBook (helpfile)) {
wxFileDialog dlg (NULL, _("Locate help"), g_helppath, wxEmptyString, _T("*.htb"),
wxOPEN | wxFILE_MUST_EXIST);
if (dlg.ShowModal() == wxID_OK) {
helpfile = dlg.GetPath ();
}else{
if (wxMessageBox (_("No help file was chosen, would you like to be \n"
"asked again after next application start?"),
_("Locate help"),
wxYES_NO | wxICON_QUESTION) == wxYES) {
wxConfig* cfg = new wxConfig (g_appname);
if (cfg->Exists (HELPFILE)) cfg->DeleteEntry (HELPFILE);
delete cfg;
return false;
}
helpfile = wxEmptyString;
}
wxConfig* cfg = new wxConfig (g_appname);
cfg->Write (HELPFILE, helpfile);
delete cfg;
force = false;
}
g_helppath = wxFileName(helpfile).GetPath (wxPATH_GET_VOLUME);
return true;
}
int App::OnExit () {
...
// delete help
if (g_help) delete g_help;
...
}
void AppFrame::OnHelp (wxCommandEvent &WXUNUSED(event)) {
wxWindow *active = wxGetActiveWindow();
wxString helptext;
while (active && helptext.IsEmpty()) {
helptext = active->GetHelpText();
active = GetParent();
}
g_help->DisplayContents();
}
7.2 About box
The "About ..." box is the signature of an application and gives the first impression. Depending of the kind of the application this might be a fancy multimedia process or just a practical display of the essential information.
The essential information an "About ..." box should show are:
- Version
- Written by
- License type
- Copyright
Of course additional information might be nice as well, e.g. framework version, important library versions, additional developers, etc.
It should also contain a small description what this application is for and a reference to where to get more information. A clickable link to the web site (if any) would be nice. For OpenSource project its common practice to list the contributors.
An application may show the "About ..." box during program start. If it does it should either provide a disable feature right in the box or remove the box after a certain state is reached or at least a certain amount of time is over. It's very annoying for a user to have to close the box during daily work.
Sample code
static wxString g_appname;
class AppFrame: public wxFrame {
friend class AppAbout;
...
void OnAbout (wxCommandEvent &event);
...
};
class AppAbout: public wxDialog {
public:
AppAbout (wxWindow *parent, long style = 0);
};
void AppFrame::OnAbout (wxCommandEvent &WXUNUSED(event)) {
AppAbout (this);
}
AppAbout::AppAbout (wxWindow *parent,
long style)
: wxDialog (parent, -1, wxEmptyString,
wxDefaultPosition, wxDefaultSize,
wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER) {
// sets the application icon
SetTitle (_("About ..."));
// about info
wxGridSizer *aboutinfo = new wxGridSizer (2, 3, 3);
aboutinfo->Add (new wxStaticText(this, -1, _("Version: ")));
aboutinfo->Add (new wxStaticText(this, -1, APP_VERSION));
aboutinfo->Add (new wxStaticText(this, -1, _("Written by: ")));
aboutinfo->Add (new wxStaticText(this, -1, APP_MAINT));
aboutinfo->Add (new wxStaticText(this, -1, _("Licence type: ")));
aboutinfo->Add (new wxStaticText(this, -1, APP_LICENCE));
aboutinfo->Add (new wxStaticText(this, -1, _("wxWidgets: ")));
aboutinfo->Add (new wxStaticText(this, -1, wxVERSION_STRING));
aboutinfo->Add (new wxStaticText(this, -1, _("Copyright: ")));
aboutinfo->Add (new wxStaticText(this, -1, APP_COPYRIGTH));
// about title/info
wxBoxSizer *abouttext = new wxBoxSizer (wxVERTICAL);
wxStaticText *appname = new wxStaticText (this, -1, g_appname);
appname->SetFont (wxFont (10, wxDEFAULT, wxNORMAL, wxBOLD));
abouttext->Add (appname, 0, wxALIGN_LEFT);
abouttext->Add (0, 10);
abouttext->Add (aboutinfo, 1, wxEXPAND);
// about icontitle//info
wxBoxSizer *aboutpane = new wxBoxSizer (wxHORIZONTAL);
wxBitmap bitmap = wxBitmap(wxICON (app));
aboutpane->Add (new wxStaticBitmap (this, -1, bitmap),
0, wxALIGN_LEFT);
aboutpane->Add (10, 0);
aboutpane->Add (abouttext, 1, wxEXPAND);
// about complete
wxBoxSizer *totalpane = new wxBoxSizer (wxVERTICAL);
totalpane->Add (aboutpane, 0, wxEXPAND | wxALL, 10);
totalpane->Add (new wxStaticText(this, -1, APP_DESCR),
0, wxALIGN_CENTER | wxLEFT | wxRIGHT, 10);
totalpane->Add (0, 6);
myHyperLink *website = new myHyperLink (this, -1, APP_WEBSITE);
wxString url = APP_WEBSITE;
url.Append ("/indexedit.html");
website->SetURL (url);
totalpane->Add (website, 0, wxALIGN_CENTER);
totalpane->Add (new wxStaticLine(this, -1), 0, wxEXPAND | wxALL, 10);
wxButton *okButton = new wxButton (this, wxID_OK, _("OK"));
okButton->SetDefault();
totalpane->Add (okButton, 0, wxALIGN_CENTER | wxLEFT | wxRIGHT | wxBOTTOM, 10);
SetSizerAndFit (totalpane);
ShowModal();
}
7.3 Naming of objects
Someone said once, all the programming art is choosing good names, the rest is just plain work. This is certainly true but it's almost impossible to make good rules.