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:   12/19/2004
15#
16# ------------------------------------------------------------------------------
17
18""" Defines the standard menu bar for use with Traits UI windows and panels,
19    and standard actions and buttons.
20"""
21
22from traits.api import Str
23
24# Import and rename the needed Pyface elements:
25from pyface.action.api import ToolBarManager as ToolBar
26from pyface.action.api import MenuBarManager as MenuBar
27from pyface.action.api import MenuManager as Menu
28from pyface.action.api import Group as ActionGroup
29from pyface.action.api import Action as PyFaceAction
30
31# -------------------------------------------------------------------------
32#  'Action' class (extends the core pyface Action class):
33# -------------------------------------------------------------------------
34
35
36class Action(PyFaceAction):
37    """ An action on a menu bar in a Traits UI window or panel.
38    """
39
40    # -------------------------------------------------------------------------
41    #  Trait definitions:
42    # -------------------------------------------------------------------------
43
44    #: Pre-condition for showing the action. If the expression evaluates to
45    #: False, the action is not visible (and disappears if it was previously
46    #: visible). If the value evaluates to True, the action becomes visible.
47    #: All **visible_when** conditions are checked each time that any trait
48    #: value is edited in the display. Therefore, you can use **visible_when**
49    #: conditions to hide or show actions in response to user input.
50    visible_when = Str()
51
52    #: Pre-condition for enabling the action. If the expression evaluates to
53    #: False, the action is disabled, that is, it cannot be selected. All
54    #: **enabled_when** conditions are checked each time that any trait value
55    #: is edited in the display. Therefore, you can use **enabled_when**
56    #: conditions to enable or disable actions in response to user input.
57    enabled_when = Str()
58
59    #: Boolean expression indicating when the action is displayed with a check
60    #: mark beside it. This attribute applies only to actions that are included
61    #: in menus.
62    checked_when = Str()
63
64    #: Pre-condition for including the action in the menu bar or toolbar. If
65    #: the expression evaluates to False, the action is not defined in the
66    #: display. Conditions for **defined_when** are evaluated only once, when
67    #: the display is first constructed.
68    defined_when = Str()
69
70    #: The method to call to perform the action, on the Handler for the window.
71    #: The method must accept a single parameter, which is a UIInfo object.
72    #: Because Actions are associated with Views rather than Handlers, you must
73    #: ensure that the Handler object for a particular window has a method with
74    #: the correct name, for each Action defined on the View for that window.
75    action = Str()
76
77
78# -------------------------------------------------------------------------
79#  Standard actions and menu bar definitions:
80# -------------------------------------------------------------------------
81
82#: Menu separator
83Separator = ActionGroup
84
85#: The standard "close window" action
86CloseAction = Action(name="Close", action="_on_close")
87
88#: The standard "undo last change" action
89UndoAction = Action(
90    name="Undo",
91    action="_on_undo",
92    defined_when="ui.history is not None",
93    enabled_when="ui.history.can_undo",
94)
95
96#: The standard "redo last undo" action
97RedoAction = Action(
98    name="Redo",
99    action="_on_redo",
100    defined_when="ui.history is not None",
101    enabled_when="ui.history.can_redo",
102)
103
104#: The standard "revert all changes" action
105RevertAction = Action(
106    name="Revert",
107    action="_on_revert",
108    defined_when="ui.history is not None",
109    enabled_when="ui.history.can_undo",
110)
111
112#: The standard "show help" action
113HelpAction = Action(name="Help", action="show_help")
114
115#: The standard Traits UI menu bar
116StandardMenuBar = MenuBar(
117    Menu(CloseAction, name="File"),
118    Menu(UndoAction, RedoAction, RevertAction, name="Edit"),
119    Menu(HelpAction, name="Help"),
120)
121
122# -------------------------------------------------------------------------
123#  Standard buttons (i.e. actions):
124# -------------------------------------------------------------------------
125
126NoButton = Action(name="")
127
128#: Appears as two buttons: **Undo** and **Redo**. When **Undo** is clicked, the
129#: most recent change to the data is cancelled, restoring the previous value.
130#: **Redo** cancels the most recent "undo" operation.
131UndoButton = Action(name="Undo")
132
133#: When the user clicks the **Revert** button, all changes made in the window
134#: are cancelled and the original values are restored. If the changes have been
135#: applied to the model (because the user clicked **Apply** or because the
136#: window is live), the model data is restored as well. The window remains
137#: open.
138RevertButton = Action(name="Revert")
139
140#: When the user clicks the **Apply** button, all changes made in the window are
141#: applied to the model. This option is meaningful only for modal windows.
142ApplyButton = Action(name="Apply")
143
144#: When the user clicks the **OK** button, all changes made in the window are
145#: applied to the model, and the window is closed.
146OKButton = Action(name="OK")
147
148#: When the user clicks the **Cancel** button, all changes made in the window
149#: are discarded; if the window is live, the model is restored to the values it
150#: held before the window was opened. The window is then closed.
151CancelButton = Action(name="Cancel")
152
153#: When the user clicks the **Help** button, the current help handler is
154#: invoked. If the default help handler is used, a pop-up window is displayed,
155#: which contains the **help** text for the top-level Group (if any), and for
156#: the items in the view. If the default help handler has been overridden,
157#: the action is determined by the custom help handler. See
158#: **traitsui.help**.
159HelpButton = Action(name="Help")
160
161OKCancelButtons = [OKButton, CancelButton]
162ModalButtons = [ApplyButton, RevertButton, OKButton, CancelButton, HelpButton]
163LiveButtons = [UndoButton, RevertButton, OKButton, CancelButton, HelpButton]
164
165#: The window has no command buttons
166NoButtons = [NoButton]
167