.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc

.. currentmodule:: wx.lib.agw.shortcuteditor

.. highlight:: python



.. _wx.lib.agw.shortcuteditor.ShortcutEditor:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.shortcuteditor.ShortcutEditor**
==========================================================================================================================================

:class:`ShortcutEditor` is a widget that allows the user to customize and change keyboard
shortcuts via a dialog. It can be used to edit :class:`wx.MenuItem` shortcuts or accelerators
defined in a :class:`AcceleratorTable`.

The interface itself is very much inpired by the GIMP shortcut editor:

http://graphicssoft.about.com/od/gimptutorials/tp/keyboard-shortcut-editor.htm

There are very few minor UI differences between :class:`ShortcutEditor` and the GIMP one,
although the behaviour should be pretty much equivalent.



|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>ShortcutEditor</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.lib.agw.shortcuteditor.ShortcutEditor_inheritance.svg" alt="Inheritance diagram of ShortcutEditor" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.lib.agw.shortcuteditor.ShortcutEditor.html" title="ShortcutEditor is a widget that allows the user to customize and change keyboard" alt="" coords="5,543,312,572"/> <area shape="rect" id="node2" href="wx.Dialog.html" title="A dialog box is a window with a title bar and sometimes a system menu, which can be moved around the screen." alt="" coords="109,466,209,495"/> <area shape="rect" id="node3" href="wx.TopLevelWindow.html" title="wx.TopLevelWindow  is a common base class for wx.Dialog  and wx.Frame." alt="" coords="71,389,247,418"/> <area shape="rect" id="node4" href="wx.NonOwnedWindow.html" title="Common base class for all non-child windows." alt="" coords="63,313,255,341"/> <area shape="rect" id="node5" href="wx.Window.html" title="wx.Window  is the base class for all windows and represents any visible object on screen." alt="" coords="103,236,214,265"/> <area shape="rect" id="node6" href="wx.WindowBase.html" title="wx.WindowBase" alt="" coords="85,159,233,188"/> <area shape="rect" id="node7" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="92,82,225,111"/> <area shape="rect" id="node8" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="43,5,141,34"/> <area shape="rect" id="node9" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="165,5,288,34"/> </map> 
   </p>
   </div>

|


|appearance| Control Appearance
===============================

|

.. container:: control-appearance-figures

   .. figure:: _static/images/widgets/fullsize/wxmsw/wx.lib.agw.shortcuteditor.shortcuteditor.png
      :alt: wxMSW
      :figclass: appearance-figure

      **wxMSW**


   .. figure:: _static/images/widgets/fullsize/wxmac/../no_appearance.png
      :alt: wxMAC
      :figclass: appearance-figure

      **wxMAC**


   .. figure:: _static/images/widgets/fullsize/wxgtk/wx.lib.agw.shortcuteditor.shortcuteditor.png
      :alt: wxGTK
      :figclass: appearance-figure

      **wxGTK**

|




|super_classes| Known Superclasses
==================================

:class:`wx.Dialog`

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.__init__`                       Default class constructor.
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.BindEvents`                     Binds a few events we will need to process
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.CreateWidgets`                  Creates all the widgets needed to populate the interface, such as buttons,
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.DoLayout`                       Lays out the widgets using sizers in a platform-independent way.
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.FromAcceleratorTable`           Builds the entire shortcut hierarchy starting from a modified version of a :class:`AcceleratorTable`.
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.FromMenuBar`                    Builds the entire shortcut hierarchy starting from a :class:`wx.MenuBar`.
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.GetShortcutManager`             Returns the root :class:`Shortcut` containing the whole shortcut hierarchy.
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.Init`                           Common initialization procedures.
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.OnClearFilter`                  Handles the ``wx.EVT_BUTTON`` event for :class:`ShortcutEditor` when the user clears the
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.OnHTMLHelp`                     Handles the ``wx.EVT_BUTTON`` event for :class:`ShortcutEditor` when the user presses the ``Help``
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.OnRestoreDefaults`              Handles the ``wx.EVT_BUTTON`` event for :class:`ShortcutEditor` when the user restores the
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.OnSetFilter`                    Handles the ``wx.EVT_TEXT`` event for :class:`ShortcutEditor`.
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.PreShow`                        Does some more common initialization before showing :class:`ShortcutEditor`.
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.SetColumnWidths`                Sets the :class:`ListShortcut` columns widths to acceptable and eye-pleasing
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.SetHTMLHelpFile`                Sets a new HTML help file (a valid html file) to be loaded when the user seeks
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.Show`                           Hides or shows the :class:`ShortcutEditor` dialog.
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.ShowModal`                      Shows the :class:`ShortcutEditor` dialog in an application-modal way.
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.ToAcceleratorTable`             Dumps the entire shortcut hierarchy (for shortcuts associated with a :class:`AcceleratorTable`), into
:meth:`~wx.lib.agw.shortcuteditor.ShortcutEditor.ToMenuBar`                      Dumps the entire shortcut hierarchy (for shortcuts associated with a :class:`wx.MenuItem`), into
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: ShortcutEditor(wx.Dialog)

   :class:`ShortcutEditor` is a widget that allows the user to customize and change keyboard
   shortcuts via a dialog. It can be used to edit :class:`wx.MenuItem` shortcuts or accelerators
   defined in a :class:`AcceleratorTable`.
   
   The interface itself is very much inpired by the GIMP shortcut editor:
   
   http://graphicssoft.about.com/od/gimptutorials/tp/keyboard-shortcut-editor.htm
   
   There are very few minor UI differences between :class:`ShortcutEditor` and the GIMP one,
   although the behaviour should be pretty much equivalent.

   .. method:: __init__(self, parent)

      Default class constructor.
      
      :param `parent`: an instance of :class:`wx.Window`, it can also be ``None``.


   .. method:: BindEvents(self)

      Binds a few events we will need to process:
      
      * ``wx.EVT_TEXT`` for the label filtering;
      * ``wx.EVT_BUTTON`` for clearing the filtering, for the HTML help window and
        to reset all the shortcuts to their defaults.


   .. method:: CreateWidgets(self)

      Creates all the widgets needed to populate the interface, such as buttons,
      texts and, most importantly, :class:`ListShortcut`.


   .. method:: DoLayout(self)

      Lays out the widgets using sizers in a platform-independent way. 


   .. method:: FromAcceleratorTable(self, accelTable)

      Builds the entire shortcut hierarchy starting from a modified version of a :class:`AcceleratorTable`.
      
      :param `accelTable`: a modified version of :class:`AcceleratorTable`, is a list of tuples (4 elements per tuple),
       populated like this::
      
          accelTable = []
      
          # Every tuple is defined in this way:
      
          for label, flags, keyCode, cmdID in my_accelerators:
              # label:   the string used to show the accelerator into the ShortcutEditor dialog
              # flags:   a bitmask of wx.ACCEL_ALT, wx.ACCEL_SHIFT, wx.ACCEL_CTRL, wx.ACCEL_CMD,
              #          or wx.ACCEL_NORMAL used to specify which modifier keys are held down
              # keyCode: the keycode to be detected (i.e., ord('b'), wx.WXK_F10, etc...)
              # cmdID:   the menu or control command ID to use for the accelerator event.
      
              accel_tuple = (label, flags, keyCode, cmdID)
              accelTable.append(accel_tuple)


   .. method:: FromMenuBar(self, topWindow)

      Builds the entire shortcut hierarchy starting from a :class:`wx.MenuBar`.
      
      :param `topWindow`: an instance of :class:`TopLevelWindow`, containing the :class:`wx.MenuBar`
       we wish to scan.


   .. method:: GetShortcutManager(self)

      Returns the root :class:`Shortcut` containing the whole shortcut hierarchy. 


   .. method:: Init(self)

      Common initialization procedures. 


   .. method:: OnClearFilter(self, event)

      Handles the ``wx.EVT_BUTTON`` event for :class:`ShortcutEditor` when the user clears the
      label filter at the top of the user interface.
      
      :param `event`: an instance of :class:`CommandEvent`.


   .. method:: OnHTMLHelp(self, event)

      Handles the ``wx.EVT_BUTTON`` event for :class:`ShortcutEditor` when the user presses the ``Help``
      button.
      
      :param `event`: an instance of :class:`CommandEvent`.
      
      .. note::
      
         By default, this method launches a :class:`html.HtmlWindow` containing the default
         HTML help file. If you wish to load another help file, you should call :meth:`~ShortcutEditor.SetHTMLHelpFile`
         with another input HTML file.


   .. method:: OnRestoreDefaults(self, event)

      Handles the ``wx.EVT_BUTTON`` event for :class:`ShortcutEditor` when the user restores the
      original shortcuts.
      
      :param `event`: an instance of :class:`CommandEvent`.


   .. method:: OnSetFilter(self, event=None)

      Handles the ``wx.EVT_TEXT`` event for :class:`ShortcutEditor`.
      
      :param `event`: if not ``None``, an instance of :class:`KeyEvent`.


   .. method:: PreShow(self)

      Does some more common initialization before showing :class:`ShortcutEditor`. 


   .. method:: SetColumnWidths(self)

      Sets the :class:`ListShortcut` columns widths to acceptable and eye-pleasing
      numbers (in pixels).


   .. method:: SetHTMLHelpFile(self, htmlFile)

      Sets a new HTML help file (a valid html file) to be loaded when the user seeks
      for an explanation on how the UI works.
      
      :param string `htmlFile`: a valid HTML file.


   .. method:: Show(self, show=True)

      Hides or shows the :class:`ShortcutEditor` dialog.
      
      The preferred way of dismissing a modal dialog is to use `EndModal`.
      
      :param bool `show`: if ``True``, the dialog box is shown and brought to the front,
       otherwise the box is hidden. If ``False`` and the dialog is modal, control is
       returned to the calling program.
      
      .. note:: Reimplemented from :class:`wx.Window`.


   .. method:: ShowModal(self)

      Shows the :class:`ShortcutEditor` dialog in an application-modal way.
      
      Program flow does not return until the dialog has been dismissed with `EndModal`.
      
      :return: The value set with :meth:`~Dialog.SetReturnCode`.
      
      .. note::
      
         Notice that it is possible to call :meth:`~ShortcutEditor.ShowModal` for a dialog which had been
         previously shown with :meth:`~ShortcutEditor.Show`, this allows to make an existing modeless dialog
         modal. However :meth:`~ShortcutEditor.ShowModal` can't be called twice without intervening `EndModal` calls.
      
      
      .. note::
      
         Note that this function creates a temporary event loop which takes precedence
         over the application's main event loop (see :class:`EventLoopBase`) and which is
         destroyed when the dialog is dismissed. This also results in a call to
         :meth:`AppConsole.ProcessPendingEvents` ().


   .. method:: ToAcceleratorTable(self, window)

      Dumps the entire shortcut hierarchy (for shortcuts associated with a :class:`AcceleratorTable`), into
      a :class:`AcceleratorTable`. This method **does** rebuild the :class:`AcceleratorTable` and sets it back
      to the input `window`.
      
      :param `window`: an instance of :class:`wx.Window`, to which the new :class:`AcceleratorTable` should be set.


   .. method:: ToMenuBar(self, topWindow)

      Dumps the entire shortcut hierarchy (for shortcuts associated with a :class:`wx.MenuItem`), into
      a :class:`wx.MenuBar`, changing only the :class:`wx.Menu` / :class:`wx.MenuItem` labels (it does **not** rebuild
      the :class:`wx.MenuBar`).
      
      :param `topWindow`: an instance of :class:`TopLevelWindow`, containing the :class:`wx.MenuBar`
       we wish to repopulate.