📄 sec-help.html
字号:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html> <head> <title> Online Help </title> <meta name="GENERATOR" content= "Modular DocBook HTML Stylesheet Version 1.45"> <link rel="HOME" title="GTK+ / Gnome Application Development" href="ggad.html"> <link rel="UP" title="The Main Window: GnomeApp" href= "cha-main.html"> <link rel="PREVIOUS" title="Adding a Status Bar" href= "z91.html"> <link rel="NEXT" title="Finishing Touches" href="z94.html"> </head> <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink= "#840084" alink="#0000FF"> <div class="NAVHEADER"> <table width="100%" border="0" bgcolor="#ffffff" cellpadding= "1" cellspacing="0"> <tr> <th colspan="4" align="center"> <font color="#000000" size="2">GTK+ / Gnome Application Development</font> </th> </tr> <tr> <td width="25%" bgcolor="#ffffff" align="left"> <a href="z91.html"><font color="#0000ff" size="2"><b> <<< Previous</b></font></a> </td> <td width="25%" colspan="2" bgcolor="#ffffff" align= "center"> <font color="#0000ff" size="2"><b><a href="ggad.html"> <font color="#0000ff" size="2"><b> Home</b></font></a></b></font> </td> <td width="25%" bgcolor="#ffffff" align="right"> <a href="z94.html"><font color="#0000ff" size="2"><b> Next >>></b></font></a> </td> </tr> </table> </div> <div class="SECT1"> <h1 class="SECT1"> <a name="SEC-HELP">Online Help</a> </h1> <p> Finished applications should provide online help and documentation. Of course, the first "line of defense" is to have an intuitive interface in the first place. But you should give users a way to get more information if they need it. </p> <p> This section describes the two major ways you can explain your interface to users: </p> <ul> <li> <p> By writing documentation, and providing buttons and menu items that jump to relevant sections. For example, the "Help" button in a properties dialog should bring up a help window describing the dialog. </p> </li> <li> <p> By adding "tooltips," explanatory text that appears if the mouse remains motionless over a widget for a short time. For menu items, explanatory text appears in the window's status bar as the user moves over the item. </p> </li> </ul> <div class="SECT2"> <h2 class="SECT2"> <a name="Z92">Gnome Documentation and Help Menu Items</a> </h2> <p> The Gnome documentation installation process was described in <a href="z72.html#SEC-INSTALLDOCS">the section called <i>Documentation</i> in the chapter called <i>Creating Your Source Tree</i></a>. Recall that applications install documentation in HTML format in directories named after locales. Each locale directory contains both help files and a <tt class="FILENAME"> topic.dat</tt> file indexing the available help topics. </p> <p> Gnome makes it ridiculously easy to create menu items for the nodes in <tt class="FILENAME">topic.dat</tt>. Simply create a help menu using the <tt class="FUNCTION"> GNOMEUIINFO_HELP()</tt> macro, like this: </p> <table border="0" bgcolor="#E0E0E0" width="100%"> <tr> <td><pre class="PROGRAMLISTING"> static GnomeUIInfo help_menu [] = { GNOMEUIINFO_HELP ("gnome-hello"), GNOMEUIINFO_MENU_ABOUT_ITEM(about_cb, NULL), GNOMEUIINFO_END}; </pre> </td> </tr> </table> <p> The single argument to <tt class="FUNCTION"> GNOMEUIINFO_HELP()</tt> is the name of the directory where you've installed your help files. The Gnome libraries will read <tt class="FILENAME">topic.dat</tt> for the user's locale (or the C locale if there is no translation) and create a menu item for each topic. Activating these menu items will launch a help browser to display the appropriate URL. (Users can configure the exact browser Gnome will launch.) If <tt class= "FILENAME">topic.dat</tt> isn't found, Gnome creates no menu items. </p> <p> In other contexts, you will have to manually set up widgets and callbacks to open your help files. Gnome provides some helper functions; the two most important ones are shown in <a href="sec-help.html#FL-GNOMEHELP"> Figure 10</a>. <tt class="FUNCTION"> gnome_help_file_find_file()</tt> returns the complete path to a help file, given the name of your help directory and the name of a help file (relative to one of the locale directories). If the help file is not found, <span class="STRUCTNAME">NULL</span> is returned. For example: </p> <table border="0" bgcolor="#E0E0E0" width="100%"> <tr> <td><pre class="PROGRAMLISTING"> gchar* helpfile; helpfile = gnome_help_file_find_file("gnome-hello", "gnome-hello.html"); if (helpfile != NULL) { gchar* url; url = g_strconcat("file:", helpfile, NULL); gnome_help_goto(NULL, url); g_free(url); g_free(helpfile); } else { gnome_error_dialog(_("Couldn't find the GnomeHello manual!")); } </pre> </td> </tr> </table> <p> <tt class="FUNCTION">gnome_help_file_find_file()</tt> takes the user's locale into account when generating the help file's pathname. </p> <p> <tt class="FUNCTION">gnome_help_goto()</tt> simply directs the help browser to a URL. You must prepend <span class="STRUCTNAME">"file:"</span> to a path to make it a valid URL before calling this function. The first argument to <tt class="FUNCTION">gnome_help_goto()</tt> is ignored; this makes it convenient to connect <tt class="FUNCTION">gnome_help_goto()</tt> as a callback function, for example to a button's <span class="SYMBOL"> "clicked"</span> signal. </p> <p> <tt class="FILENAME">libgnome/gnome-help.h</tt> contains a few other variants of <tt class="FUNCTION"> gnome_help_goto()</tt> suited for connection to signals with different signatures; in particular, there's a callback there for the <tt class="CLASSNAME"> GnomePropertyBox</tt>'s <span class="SYMBOL"> "help"</span> signal. </p> <p> One caveat: the Gnome libraries look for files in the Gnome installation prefix, not in your application's installation prefix. For now, users should install Gnome applications and libraries in the same place. This was done for simplicity's sake when Gnome was much smaller; it's clearly the wrong behavior and will be fixed in a future version. If you use Gnome library functions such as <tt class="FUNCTION">gnome_help_file_find_file()</tt>, your application will automatically take advantage of this future Gnome enhancement. </p> <div class="FIGURE"> <a name="FL-GNOMEHELP"></a> <div class="FUNCSYNOPSIS"> <a name="FL-GNOMEHELP.SYNOPSIS"></a> <table border="0" bgcolor="#E0E0E0" width="100%"> <tr> <td><pre class="FUNCSYNOPSISINFO">#include <libgnome/gnome-help.h></pre> </td> </tr> </table> <p> <code><code class="FUNCDEF">gchar* <tt class= "FUNCTION"> gnome_help_file_find_file</tt></code>(const gchar* <tt class="PARAMETER"><i>app</i></tt>, const gchar* <tt class="PARAMETER"><i>filename</i></tt>);</code> </p> <p> <code><code class="FUNCDEF">void <tt class= "FUNCTION">gnome_help_goto</tt></code>(void* <tt class="PARAMETER"><i>ignore</i></tt>, const gchar* <tt class="PARAMETER"><i>url</i></tt>);</code> </p> </div> <p> <b>Figure 10. Help Files</b> </p> </div> </div> <div class="SECT2"> <h2 class="SECT2"> <a name="Z93">Menu Hints</a> </h2> <p> As the user moves over your application menus, a short description of each menu item should appear in the statusbar. Gnome makes this very easy; just call the <tt class="FUNCTION">gnome_app_install_menu_hints()</tt> (<a href="sec-help.html#FL-MENUHINTS">Figure 11</a>) after you create your menus and statusbar. The <span class= "STRUCTNAME">GnomeUIInfo</span> struct passed to this function must have its <span class="STRUCTNAME"> widget</span> fields filled in by one of the menu-creation functions, and the <span class= "STRUCTNAME">GnomeApp</span> must have a <span class= "STRUCTNAME">GnomeAppBar</span> or <span class= "STRUCTNAME">GtkStatusbar</span> in its statusbar slot. </p> <div class="FIGURE"> <a name="FL-MENUHINTS"></a> <div class="FUNCSYNOPSIS"> <a name="FL-MENUHINTS.SYNOPSIS"></a> <table border="0" bgcolor="#E0E0E0" width="100%"> <tr> <td><pre class="FUNCSYNOPSISINFO">#include <libgnomeui/gnome-app-helper.h></pre> </td> </tr> </table> <p> <code><code class="FUNCDEF">void <tt class= "FUNCTION"> gnome_app_install_menu_hints</tt></code>(GnomeApp* <tt class="PARAMETER"><i>app</i></tt>, GnomeUIInfo* <tt class="PARAMETER"><i>uiinfo</i></tt>);</code> </p> </div> <p> <b>Figure 11. Installing Menu Hints</b> </p> </div> </div> <div class="SECT2"> <h2 class="SECT2"> <a name="SEC-TOOLTIPS">Tooltips</a> </h2> <p> GTK+ provides tooltip functionality; you simply create a <span class="STRUCTNAME">GtkTooltips</span> and attach it to a widget. I like to use the following convenience function in my applications: </p> <table border="0" bgcolor="#E0E0E0" width="100%"> <tr> <td><pre class="PROGRAMLISTING"> voidset_tooltip(GtkWidget* w, const gchar* tip){ GtkTooltips* t = gtk_tooltips_new(); gtk_tooltips_set_tip (t, w, tip, NULL);} </pre> </td> </tr> </table> <p> The <span class="STRUCTNAME">GtkTooltips</span> will be destroyed along with the widget. Make your tooltips long rather than short; there's no reason to skimp on the amount of information you provide here. You should get in the habit of calling <tt class="FUNCTION"> set_tooltip()</tt> every time you create a button or other widget that could benefit from it. </p> <p> Note that toolbars created from a <span class= "STRUCTNAME">GnomeUIInfo</span> template will have tooltips installed automatically. </p> </div> </div> <div class="NAVFOOTER"> <br> <br> <table width="100%" border="0" bgcolor="#ffffff" cellpadding= "1" cellspacing="0"> <tr> <td width="25%" bgcolor="#ffffff" align="left"> <a href="z91.html"><font color="#0000ff" size="2"><b> <<< Previous</b></font></a> </td> <td width="25%" colspan="2" bgcolor="#ffffff" align= "center"> <font color="#0000ff" size="2"><b><a href="ggad.html"> <font color="#0000ff" size="2"><b> Home</b></font></a></b></font> </td> <td width="25%" bgcolor="#ffffff" align="right"> <a href="z94.html"><font color="#0000ff" size="2"><b> Next >>></b></font></a> </td> </tr> <tr> <td colspan="2" align="left"> <font color="#000000" size="2"><b>Adding a Status Bar</b></font> </td> <td colspan="2" align="right"> <font color="#000000" size="2"><b>Finishing Touches</b></font> </td> </tr> </table> </div> </body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -