1# ------------------------------------------------------------------------------
2#
3#  Copyright (c) 2005, Enthought, Inc.
4#  All rights reserved.
5#
6#  This software is provided without warranty under the terms of the BSD
7#  license included in LICENSE.txt and may be redistributed only
8#  under the conditions described in the aforementioned license.  The license
9#  is also available online at http://www.enthought.com/licenses/BSD.txt
10#
11#  Thanks for using Enthought open source!
12#
13#  Author: David C. Morrill
14#  Date:   02/04/2005
15#
16# ------------------------------------------------------------------------------
17
18""" Defines the help interface for displaying the help associated with a
19    Traits UI View object.
20"""
21
22
23
24from .toolkit import toolkit
25
26
27def default_show_help(info, control):
28    """ Default handler for showing the help associated with a view.
29    """
30    toolkit().show_help(info.ui, control)
31
32
33# The default handler for showing help
34show_help = default_show_help
35
36
37def on_help_call(new_show_help=None):
38    """ Sets a new global help provider function.
39
40    The help provider function must have a signature of
41    *function*(*info*, *control*), where *info* is a UIInfo object for the
42    current view, and *control* is the UI control that invokes the function
43    (typically, a **Help** button). It is provided in case the help provider
44    needs to position the help window relative to the **Help** button.
45
46    To retrieve the current help provider function, call this function with
47    no arguments.
48
49    Parameters
50    ----------
51    new_show_help : function
52        The function to set as the new global help provider
53
54    Returns
55    -------
56    previous : callable
57        The previous global help provider function
58    """
59    global show_help
60
61    result = show_help
62    if new_show_help is not None:
63        show_help = new_show_help
64    return result
65