[PATCH 1/3] Add a help button to every Anaconda screen
Martin Kolman
mkolman at redhat.com
Mon Aug 18 18:39:48 UTC 2014
----- Original Message -----
> From: "Anne Mulhern" <amulhern at redhat.com>
> To: "anaconda patch review" <anaconda-patches at lists.fedorahosted.org>
> Sent: Monday, August 18, 2014 3:52:16 PM
> Subject: Re: [PATCH 1/3] Add a help button to every Anaconda screen
>
>
>
>
>
> ----- Original Message -----
> > From: "Martin Kolman" <mkolman at redhat.com>
> > To: anaconda-patches at lists.fedorahosted.org
> > Sent: Thursday, August 14, 2014 7:01:21 AM
> > Subject: [PATCH 1/3] Add a help button to every Anaconda screen
> >
> > This makes context aware help possible for every Anaconda screen by
> > providing a help button in the upper right corner of the screen.
> > Clicking the button opens the yelp help viewer with either a help page
> > tailored for the given screen, the main page of the installation guide
> > (if no help is available for the screen) or a "no help found" placeholder
> > page.
> > The new helpFile GUIObject attribute is used to specify which help
> > file to show for the given screen. If no help file is specified
> > either the main page of the Installation Guide will be shown (if
> > available) or the placeholder page will be shown.
> >
> > Signed-off-by: Martin Kolman <mkolman at redhat.com>
> > ---
> > anaconda.spec.in | 1 +
> > data/HelpPlaceholder.html | 5 ++
> > data/HelpPlaceholderWithLinks.html | 13 ++++++
> > data/Makefile.am | 2 +
> > pyanaconda/constants.py | 6 +++
> > pyanaconda/ihelp.py | 90
> > ++++++++++++++++++++++++++++++++++++
> > pyanaconda/ui/gui/__init__.py | 12 +++++
> > pyanaconda/ui/gui/spokes/__init__.py | 9 ++++
> > widgets/glade/AnacondaWidgets.xml | 5 ++
> > widgets/src/BaseWindow.c | 48 +++++++++++++++++++
> > widgets/src/BaseWindow.h | 3 ++
> > 11 files changed, 194 insertions(+)
> > create mode 100644 data/HelpPlaceholder.html
> > create mode 100644 data/HelpPlaceholderWithLinks.html
> > create mode 100644 pyanaconda/ihelp.py
> >
> > diff --git a/anaconda.spec.in b/anaconda.spec.in
> > index e23d49c..1c6828f 100644
> > --- a/anaconda.spec.in
> > +++ b/anaconda.spec.in
> > @@ -174,6 +174,7 @@ Requires: zenity
> > %endif
> > Requires: keybinder3
> > Requires: NetworkManager-wifi
> > +Requires: yelp
> >
> > %description gui
> > This package contains graphical user interface for the Anaconda installer.
> > diff --git a/data/HelpPlaceholder.html b/data/HelpPlaceholder.html
> > new file mode 100644
> > index 0000000..4d1781a
> > --- /dev/null
> > +++ b/data/HelpPlaceholder.html
> > @@ -0,0 +1,5 @@
> > +<body>
> > +<h1>The Anaconda built-in help</h1>
> > +<p>...is not yet available for this screen.</p>
> > +<p>You can check the Anaconda wiki page, the Fedora Installation Guide or
> > other online help resources instead.</p>
> > +</body>
> > diff --git a/data/HelpPlaceholderWithLinks.html
> > b/data/HelpPlaceholderWithLinks.html
> > new file mode 100644
> > index 0000000..5fe0485
> > --- /dev/null
> > +++ b/data/HelpPlaceholderWithLinks.html
> > @@ -0,0 +1,13 @@
> > +<body>
> > +<h1>The Anaconda built-in help</h1>
> > +<p>...is not yet available for this screen.</p>
> > +<p>You can check the Anaconda wiki page, the Fedora Installation Guide or
> > other online help resources instead:</p>
> > +<p>
> > +<ul>
> > + <li><a
> > href="http://docs.fedoraproject.org/en-US/Fedora/20/html/Installation_Guide/">Fedora
> > Installation Guide</a></li>
> > + <li><a href="https://fedoraproject.org/wiki/Anaconda">Anaconda
> > Wiki</a></li>
> > + <li><a
> > href="http://fedoraproject.org/wiki/Anaconda_Boot_Options">Anaconda Boot
> > Options</a></li>
> > + <li><a
> > href="http://fedoraproject.org/wiki/Anaconda/Kickstart">Anaconda
> > Kickstart</a></li>
> > +</ul>
> > +</p>
> > +</body>
> > diff --git a/data/Makefile.am b/data/Makefile.am
> > index bcc6bf5..17926b3 100644
> > --- a/data/Makefile.am
> > +++ b/data/Makefile.am
> > @@ -26,6 +26,8 @@ dist_pkgdata_DATA = interactive-defaults.ks \
> > anaconda-gtk.css
> >
> > helpdir = $(datadir)/$(PACKAGE_NAME)
> > +docsdir = $(datadir)/docs/$(PACKAGE_NAME)
> > dist_help_DATA = anaconda_options.txt
> > +dist_docs_DATA = HelpPlaceholder.html HelpPlaceholderWithLinks.html
> >
> > MAINTAINERCLEANFILES = Makefile.in
> > diff --git a/pyanaconda/constants.py b/pyanaconda/constants.py
> > index 18c2a1f..5583162 100644
> > --- a/pyanaconda/constants.py
> > +++ b/pyanaconda/constants.py
> > @@ -161,3 +161,9 @@ DEFAULT_AUTOPART_TYPE = AUTOPART_TYPE_LVM
> >
> > import logging
> > LOGLVL_LOCK = logging.DEBUG-1
> > +
> > +# help
> > +HELP_FOLDER = "/usr/share/doc/anaconda"
> > +HELP_MAIN_PAGE = "Installation_Guide.xml"
> > +HELP_PLACEHOLDER = "HelpPlaceholder.html"
> > +HELP_PLACEHOLDER_WITH_LINKS = "HelpPlaceholderWithLinks.html"
> > diff --git a/pyanaconda/ihelp.py b/pyanaconda/ihelp.py
> > new file mode 100644
> > index 0000000..dffd7d8
> > --- /dev/null
> > +++ b/pyanaconda/ihelp.py
> > @@ -0,0 +1,90 @@
> > +#
> > +# Copyright (C) 2014 Red Hat, Inc.
> > +#
> > +# This copyrighted material is made available to anyone wishing to use,
> > +# modify, copy, or redistribute it subject to the terms and conditions of
> > +# the GNU General Public License v.2, or (at your option) any later
> > version.
> > +# This program is distributed in the hope that it will be useful, but
> > WITHOUT
> > +# ANY WARRANTY expressed or implied, including the implied warranties of
> > +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
> > General
> > +# Public License for more details. You should have received a copy of the
> > +# GNU General Public License along with this program; if not, write to the
> > +# Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
> > MA
> > +# 02110-1301, USA. Any Red Hat trademarks that are incorporated in the
> > +# source code or documentation are not subject to the GNU General Public
> > +# License and may only be used or replicated with the express permission
> > of
> > +# Red Hat, Inc.
> > +#
> > +# Red Hat Author(s): Martin Kolman <mkolman at redhat.com>
> > +#
> > +"""
> > +Anaconda built-in help module
> > +"""
> > +import os
> > +import subprocess
> > +
> > +from pyanaconda import constants
> > +from pyanaconda.flags import flags
> > +
> > +import logging
> > +log = logging.getLogger("anaconda")
> > +
> > +yelp_process = None
> > +
> > +def get_help_path(help_file):
> > + """Return the full path for the given help file name,
> > + if the help file path does not exist a fallback path is returned.
> > + There are actually two possible fallback paths that might be returned:
> > + * first we try to return path to the main page of the installation
> > guide
> > + (if it exists)
> > + * if we can't find the main page of the installation page, path to a
> > + "no help found" placeholder bundled with Anaconda is returned
> > +
> > + :param str help_file: help file name
> > + :return str: full path to the help file requested or to a placeholder
> > + """
> > + # check if the screen has any helpFile defined
> > + if help_file:
> > + # check if the help file exists
> > + help_path = os.path.join(constants.HELP_FOLDER, help_file)
> > + if os.path.isfile(help_path):
> > + return help_path
> > + else:
> > + log.debug("the %s help file has been requested, but is not
> > available", help_file)
> > +
> > + # the screen did not have a helpFile defined or the defined help file
> > + # does not exist, so next try to check if we can find the main page
> > + # of the installation guide and use it instead
> > + help_path = os.path.join(constants.HELP_FOLDER,
> > constants.HELP_MAIN_PAGE)
> > + if os.path.exists(help_path):
> > + return help_path
> > +
> > + # looks like the installation guide is not available, so just return
> > + # a placeholder page that should always be available
> > + if flags.livecdInstall:
> > + return os.path.join(constants.HELP_FOLDER,
> > constants.HELP_PLACEHOLDER_WITH_LINKS)
> > + else:
> > + return os.path.join(constants.HELP_FOLDER,
> > constants.HELP_PLACEHOLDER)
> > +
> > +def start_yelp(help_path):
> > + """Start a new yelp process and make sure to kill any existing ones
> > +
> > + :param str help_path: path to the help file yelp should load
> > + """
> > +
> > + kill_yelp()
> > + log.debug("starting yelp")
> > + global yelp_process
> > + yelp_process = subprocess.Popen(["yelp", help_path])
> > +
> > +def kill_yelp():
> > + """Try to kill any existing yelp processes"""
> > +
> > + global yelp_process
> > + if not yelp_process:
> > + return False
> > +
> > + log.debug("killing yelp")
> > + yelp_process.kill()
> > + yelp_process = None
> > + return True
> > diff --git a/pyanaconda/ui/gui/__init__.py b/pyanaconda/ui/gui/__init__.py
> > index 3245d3e..7188aa6 100644
> > --- a/pyanaconda/ui/gui/__init__.py
> > +++ b/pyanaconda/ui/gui/__init__.py
> > @@ -30,6 +30,7 @@ from pyanaconda import product
> >
> > from pyanaconda.ui import UserInterface, common
> > from pyanaconda.ui.gui.utils import gtk_action_wait, busyCursor,
> > unbusyCursor
> > +from pyanaconda import ihelp
> > import os.path
> >
> > import logging
> > @@ -80,6 +81,10 @@ class GUIObject(common.UIObject):
> > that use GUI elements (Hubs & Spokes) from
> > Anaconda
> > can override the translation domain with their
> > own,
> > so that their subclasses are properly
> > translated.
> > + helpFile -- The location of the yelp-compatible help file
> > for
> > the
> > + given GUI object. The default value of ""
> > indicates
> > + that the object has not specific help file
> > assigned
> > + and the default help file should be used.
> > """
> > builderObjects = []
> > mainWidgetName = None
> > @@ -90,6 +95,7 @@ class GUIObject(common.UIObject):
> > focusWidgetName = None
> >
> > uiFile = ""
> > + helpFile = ""
> > translationDomain = "anaconda"
> >
> > screenshots_directory = "/tmp/anaconda-screenshots"
> > @@ -535,6 +541,7 @@ class GraphicalUserInterface(UserInterface):
> >
> > # Use connect_after so classes can add actions before we change
> > screens
> > obj.window.connect_after("continue-clicked",
> > self._on_continue_clicked)
> > + obj.window.connect_after("help-button-clicked",
> > self._on_help_clicked, obj)
> > obj.window.connect_after("quit-clicked", self._on_quit_clicked)
> >
> > return obj
> > @@ -696,6 +703,11 @@ class GraphicalUserInterface(UserInterface):
> > self._currentAction = nextAction
> > self._actions.pop(0)
> >
> > + def _on_help_clicked(self, window, obj):
> > + # the help button has been clicked, start the yelp viewer with
> > + # content for the current screen
> > + ihelp.start_yelp(ihelp.get_help_path(obj.helpFile))
> > +
> > def _on_quit_clicked(self, win, userData=None):
> > if not win.get_quit_button():
> > return
> > diff --git a/pyanaconda/ui/gui/spokes/__init__.py
> > b/pyanaconda/ui/gui/spokes/__init__.py
> > index 183dc6f..5fb2714 100644
> > --- a/pyanaconda/ui/gui/spokes/__init__.py
> > +++ b/pyanaconda/ui/gui/spokes/__init__.py
> > @@ -21,6 +21,7 @@
> >
> > from pyanaconda.ui import common
> > from pyanaconda.ui.gui import GUIObject
> > +from pyanaconda import ihelp
> >
> > __all__ = ["StandaloneSpoke", "NormalSpoke"]
> >
> > @@ -44,6 +45,14 @@ class NormalSpoke(GUIObject, common.NormalSpoke):
> > GUIObject.__init__(self, data)
> > common.NormalSpoke.__init__(self, storage, payload, instclass)
> >
> > + # Add a help handler
> > + self.window.connect_after("help-button-clicked",
> > self._on_help_clicked)
> > +
> > + def _on_help_clicked(self, window):
> > + # the help button has been clicked, start the yelp viewer with
> > + # content for the current spoke
> > + ihelp.start_yelp(ihelp.get_help_path(self.helpFile))
> > +
> > def on_back_clicked(self, window):
> > # Notify the hub that we're finished.
> > # The hub will be the current-action of the main window.
> > diff --git a/widgets/glade/AnacondaWidgets.xml
> > b/widgets/glade/AnacondaWidgets.xml
> > index 42c4194..782d360 100644
> > --- a/widgets/glade/AnacondaWidgets.xml
> > +++ b/widgets/glade/AnacondaWidgets.xml
> > @@ -25,6 +25,11 @@
> > <property id="distribution" translatable="True" />
> > <property id="window-name" translatable="True" />
> > </properties>
> > +
> > + <signals>
> > + <signal since="4.0" id="help-button-clicked" />
> > + </signals>
> > +
> > </glade-widget-class>
> >
> > <glade-widget-class title="Standalone Spoke Window"
> > diff --git a/widgets/src/BaseWindow.c b/widgets/src/BaseWindow.c
> > index 5b7f337..94dee1f 100644
> > --- a/widgets/src/BaseWindow.c
> > +++ b/widgets/src/BaseWindow.c
> > @@ -28,6 +28,8 @@
> > #include "BaseWindow.h"
> > #include "intl.h"
> >
> > + #include <atk/atk.h>
> > +
> > /**
> > * SECTION: BaseWindow
> > * @title: AnacondaBaseWindow
> > @@ -95,6 +97,7 @@
> >
> > enum {
> > SIGNAL_INFO_BAR_CLICKED,
> > + SIGNAL_HELP_BUTTON_CLICKED,
> > LAST_SIGNAL
> > };
> >
> > @@ -109,6 +112,7 @@ enum {
> > #define DEFAULT_WINDOW_NAME N_("SPOKE NAME")
> > #define DEFAULT_BETA N_("PRE-RELEASE / TESTING")
> > #define LAYOUT_INDICATOR_LABEL_WIDTH 10
> > +#define HELP_BUTTON_LABEL _("_Help!")
> >
> > struct _AnacondaBaseWindowPrivate {
> > gboolean is_beta, info_shown;
> > @@ -117,6 +121,7 @@ struct _AnacondaBaseWindowPrivate {
> > GtkWidget *nav_box, *nav_area, *action_area;
> > GtkWidget *name_label, *distro_label, *beta_label;
> > GtkWidget *layout_indicator;
> > + GtkWidget *help_button;
> >
> > /* Untranslated versions of various things. */
> > gchar *orig_name, *orig_distro, *orig_beta;
> > @@ -128,6 +133,7 @@ static void
> > anaconda_base_window_buildable_init(GtkBuildableIface *iface);
> > static void format_beta_label(AnacondaBaseWindow *window, const char
> > *markup);
> >
> > static gboolean anaconda_base_window_info_bar_clicked(GtkWidget *widget,
> > GdkEvent *event, AnacondaBaseWindow *win);
> > +static void anaconda_base_window_help_button_clicked(GtkButton *button,
> > AnacondaBaseWindow *win);
> >
> > G_DEFINE_TYPE_WITH_CODE(AnacondaBaseWindow, anaconda_base_window,
> > GTK_TYPE_BIN,
> > G_IMPLEMENT_INTERFACE(GTK_TYPE_BUILDABLE,
> > anaconda_base_window_buildable_init))
> > @@ -173,6 +179,7 @@ static void
> > anaconda_base_window_class_init(AnacondaBaseWindowClass *klass) {
> > G_PARAM_READWRITE));
> >
> > klass->info_bar_clicked = NULL;
> > + klass->help_button_clicked = NULL;
> >
> > /**
> > * AnacondaBaseWindow::info-bar-clicked:
> > @@ -192,6 +199,24 @@ static void
> > anaconda_base_window_class_init(AnacondaBaseWindowClass *klass) {
> > g_cclosure_marshal_VOID__VOID,
> > G_TYPE_NONE,
> > 0);
> >
> > + /**
> > + * AnacondaBaseWindow::help-button-clicked:
> > + * @window: the window that received the signal
> > + *
> > + * Emitted when the help button in the right corner has been activated
> > + * (pressed and released). This is commonly used to open the help view
> > with
> > + * help content for the given spoke or hub
> > + *
> > + * Since: 4.0
> > + */
> > + window_signals[SIGNAL_HELP_BUTTON_CLICKED] =
> > g_signal_new("help-button-clicked",
> > +
> > G_TYPE_FROM_CLASS(object_class),
> > +
> > G_SIGNAL_RUN_FIRST
> > | G_SIGNAL_ACTION,
> > +
> > G_STRUCT_OFFSET(AnacondaBaseWindowClass,
> > help_button_clicked),
> > + NULL, NULL,
> > +
> > g_cclosure_marshal_VOID__VOID,
> > + G_TYPE_NONE,
> > 0);
> > +
> > g_type_class_add_private(object_class,
> > sizeof(AnacondaBaseWindowPrivate));
> > }
> >
> > @@ -210,6 +235,7 @@ GtkWidget *anaconda_base_window_new() {
> >
> > static void anaconda_base_window_init(AnacondaBaseWindow *win) {
> > char *markup;
> > + AtkObject *atk;
> >
> > win->priv = G_TYPE_INSTANCE_GET_PRIVATE(win,
> > ANACONDA_TYPE_BASE_WINDOW,
> > @@ -325,11 +351,28 @@ G_GNUC_END_IGNORE_DEPRECATIONS
> > gtk_widget_set_margin_top(win->priv->layout_indicator, 6);
> > gtk_widget_set_margin_bottom(win->priv->layout_indicator, 6);
> >
> > + /* Create the help button. */
> > + win->priv->help_button =
> > gtk_button_new_with_mnemonic(HELP_BUTTON_LABEL);
> > + gtk_widget_set_halign(win->priv->help_button, GTK_ALIGN_START);
> > + gtk_widget_set_vexpand(win->priv->help_button, FALSE);
> > + gtk_widget_set_valign(win->priv->help_button, GTK_ALIGN_END);
> > + gtk_widget_set_margin_bottom(win->priv->help_button, 6);
> > +
> > + atk = gtk_widget_get_accessible(win->priv->help_button);
> > + atk_object_set_name(atk, HELP_BUTTON_LABEL);
> > +
> > + /* Hook up some signals for that button. The signal handlers here
> > will
> > + * just raise our own custom signals for the whole window.
> > + */
> > + g_signal_connect(win->priv->help_button, "clicked",
> > + G_CALLBACK(anaconda_base_window_help_button_clicked),
> > win);
> > +
> > /* Add everything to the nav area. */
> > gtk_grid_attach(GTK_GRID(win->priv->nav_area), win->priv->name_label,
> > 0,
> > 0, 1, 1);
> > gtk_grid_attach(GTK_GRID(win->priv->nav_area),
> > win->priv->distro_label,
> > 1, 0, 1, 1);
> > gtk_grid_attach(GTK_GRID(win->priv->nav_area), win->priv->beta_label,
> > 1,
> > 1, 1, 1);
> > gtk_grid_attach(GTK_GRID(win->priv->nav_area),
> > win->priv->layout_indicator, 1, 2, 1, 1);
> > + gtk_grid_attach(GTK_GRID(win->priv->nav_area), win->priv->help_button,
> > 2, 1, 1, 2);
> > }
> >
> > static void anaconda_base_window_get_property(GObject *object, guint
> > prop_id, GValue *value, GParamSpec *pspec) {
> > @@ -587,6 +630,11 @@ static gboolean
> > anaconda_base_window_info_bar_clicked(GtkWidget *wiget, GdkEvent
> > return FALSE;
> > }
> >
> > +static void anaconda_base_window_help_button_clicked(GtkButton *button,
> > + AnacondaBaseWindow
> > *win) {
> > + g_signal_emit(win, window_signals[SIGNAL_HELP_BUTTON_CLICKED], 0);
> > +}
> > +
> > /**
> > * anaconda_base_window_clear_info:
> > * @win: a #AnacondaBaseWindow
> > diff --git a/widgets/src/BaseWindow.h b/widgets/src/BaseWindow.h
> > index eb6191d..19891c1 100644
> > --- a/widgets/src/BaseWindow.h
> > +++ b/widgets/src/BaseWindow.h
> > @@ -56,11 +56,14 @@ struct _AnacondaBaseWindow {
> > * pointer to be cast to a #GtkBin pointer.
> > * @info_bar_clicked : Function pointer called when the
> > #AnacondaBaseWindow::info-bar-clicked
> > * signal is emitted.
> > + * @help_button_clicked: Function pointer called when the
> > #AnacondaSpokeWindow::help-button-clicked
> > + * signal is emitted.
> > */
> > struct _AnacondaBaseWindowClass {
> > GtkBinClass parent_class;
> >
> > void (* info_bar_clicked) (AnacondaBaseWindow *window);
> > + void (* help_button_clicked) (AnacondaBaseWindow *window);
> > };
> >
> > GType anaconda_base_window_get_type (void);
> > --
> > 1.9.3
> >
> > _______________________________________________
> > anaconda-patches mailing list
> > anaconda-patches at lists.fedorahosted.org
> > https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
> >
>
> The fallback help is Fedora specific. Should that part be generalized
> for the likelihood that all this will probably end up in RHEL eventually?
That's a good point - so maybe we can add a Fedora* prefix to the placeholders
& move the path specification to payload ? So for RHEL the payload would have a
different path & there would be a different set of RHEL* placeholders.
>
> - mulhern
> _______________________________________________
> anaconda-patches mailing list
> anaconda-patches at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
>
More information about the anaconda-patches
mailing list