.. wxPython Phoenix documentation

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

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

.. include:: headings.inc

.. module:: wx.lib.agw.shortcuteditor

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

.. highlight:: python



.. _wx.lib.agw.shortcuteditor:

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

:class:`~wx.lib.agw.shortcuteditor.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`.

.. note::

    :class:`ShortcutEditor` **requires** the minimum AGW version 0.9.3 or the current
    SVN, for the various enhancements made to the :class:`~wx.lib.agw.hypertreelist.HyperTreeList`
    and :class:`~wx.lib.agw.genericmessagedialog.GenericMessageDialog`
    widgets.


Description
===========

: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.

Various features:

* Shortcuts are listed in a tree-like structure, pretty much reflecting a menu
  hierarchy (as most of the time :class:`ShortcutEditor` is used to edit :class:`wx.MenuItem`
  shortcuts);
* Accelerators defined via :class:`AcceleratorTable` are handled in a similar way;
* Support for I18N;
* Ability to restore default shortcuts/accelerators via a UI button;
* Possibility to send back the new/updated shortcuts to the original :class:`wx.MenuBar` or
  the original :class:`AcceleratorTable`;
* Filters on the shortcuts label (case-insensitive);
* Basic help window with instructions (customizable via :meth:`~ShortcutEditor.SetHTMLHelpFile`), via
  the ``Help`` button.

And a lot more. Check the demo for an almost complete review of the functionalities.


UI Interactions
===============

1. In the :class:`ShortcutEditor` dialog you can open sub-sections by clicking the small box
   with a + sign in it next to each section name. In the screen grab, you can see I've
   opened the *Options* sub-section as I'm going to add a keyboard shortcut to the
   *OptionsItem 1* item.

   .. figure:: _static/images/sphinxdocs/ShortcutEditor_1_thumb.png
      :alt: Open Subsections
      :figclass: floatcenter
      :target: _static/images/sphinxdocs/ShortcutEditor_1.png

      **Figure 1**


2. Now you need to scroll to the tool or command that you want to edit and click on it
   to select it. When selected, the text for that tool in the *Shortcut* column changes
   to read 'New accelerator...' and you can press the key or combination of keys you
   want to assign as a shortcut.

   .. figure:: _static/images/sphinxdocs/ShortcutEditor_2_thumb.png
      :alt: Assign Shortcut
      :figclass: floatcenter
      :target: _static/images/sphinxdocs/ShortcutEditor_2.png

      **Figure 2**


3. I've changed the *OptionsItem 1*'s keyboard shortcut to ``Shift+Ctrl+F`` by pressing
   the ``Shift``, ``Ctrl`` and ``F`` keys simultaneously. If you want to remove a keyboard
   shortcut from any tool or command, just click on it to select it and then when the
   'New accelerator...' text displays, press the backspace key and the text will change
   to 'Disabled'.

   Once you're happy that your keyboard shortcuts are set up as you wish, simply click
   the ``OK`` button.

   .. figure:: _static/images/sphinxdocs/ShortcutEditor_3_thumb.png
      :alt: Remove/Save Shortcuts
      :figclass: floatcenter
      :target: _static/images/sphinxdocs/ShortcutEditor_3.png

      **Figure 3**


4. If you thought my choice of ``Shift+Ctrl+F`` was an odd selection, I chose it because
   it was a keyboard combination that hadn't already been assigned to any tool or command.
   If you try to assign a keyboard shortcut that is already in use, an alert will open
   telling you what the shortcut is currently being used for. If you want to keep the
   original shortcut, just click the ``Cancel`` button, otherwise click ``Reassign shortcut``
   to make the shortcut apply to your new selection.

   .. figure:: _static/images/sphinxdocs/ShortcutEditor_4_thumb.png
      :alt: Reassigning Shortcuts
      :figclass: floatcenter
      :target: _static/images/sphinxdocs/ShortcutEditor_4.png

      **Figure 4**



Base Functionalities
====================

There are basically three ways to populate the :class:`ShortcutEditor` dialog, depending on
your needs. These approaches can be combined if needed.

1) Use the :meth:`~ShortcutEditor.FromMenuBar` method: if you need to give your user the ability to edit
   the various :class:`wx.MenuItem` shortcuts in your application, you can create :class:`ShortcutEditor`
   in this way::

        # Build your wx.MenuBar first!!!
        # "self" is an instance of wx.TopLevelWindow

        dlg = ShortcutEditor(self)
        dlg.FromMenuBar(self)

        # Here the user will make all the various modifications
        # to the shortcuts

        if dlg.ShowModal() == wx.ID_OK:
            # Changes accepted, send back the new shortcuts to
            # the TLW wx.MenuBar
            dlg.ToMenuBar(self)

        dlg.Destroy()


2) Use the :meth:`~ShortcutEditor.FromAcceleratorTable` method: if you need to give your user the ability to edit
   the various accelerators you set via :class:`AcceleratorTable` in your application, you can
   create :class:`ShortcutEditor` in this way::

        # Build your wx.AcceleratorTable first!!!
        # "accelTable" is a list of tuples (4 elements per tuple)

        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)

        dlg = ShortcutEditor(self)
        dlg.FromAcceleratorTable(accelTable)

        # Here the user will make all the various modifications
        # to the shortcuts

        if dlg.ShowModal() == wx.ID_OK:
            # Changes accepted, send back the new shortcuts to
            # the window with the wx.AcceleratorTable:
            dlg.ToAcceleratorTable(self)

        dlg.Destroy()


3) Build your own hierarchy of shortcuts using :meth:`~ShortcutEditor.GetShortcutManager`::

        dlg = ShortcutEditor(self)
        manager = dlg.GetShortcutManager()

        for label, accelerator, bitmap, help, cmdID in my_list:
            shortcut = Shortcut(label, accelerator, bitmap, help, accelId=cmdID)
            manager.AppendItem(shortcut)

        dlg.ShowModal()
        dlg.Destroy()


Usage
=====

Usage example::

    import wx
    import wx.lib.agw.shortcuteditor as SE

    class MyFrame(wx.Frame):

        def __init__(self, parent):

            wx.Frame.__init__(self, parent, -1, "ShortcutEditor Demo")

            bar = wx.MenuBar()
            menu = wx.Menu()

            menu.Append(101, "&Mercury", "This the text in the Statusbar")
            menu.Append(102, "&Venus", "")
            menu.Append(103, "&Earth", "You may select Earth too")
            menu.AppendSeparator()
            menu.Append(104, "&Close", "Close this frame")

            bar.Append(menu, 'File')
            self.SetMenuBar(bar)

            dlg = SE.ShortcutEditor(self)
            dlg.FromMenuBar(self)

            if dlg.ShowModal() == wx.ID_OK:
                # Changes accepted, send back the new shortcuts to the TLW wx.MenuBar
                dlg.ToMenuBar(self)

            dlg.Destroy()


    # our normal wxApp-derived class, as usual

    app = wx.App(0)

    frame = MyFrame(None)
    app.SetTopWindow(frame)
    frame.Show()

    app.MainLoop()



Window Styles
=============

`No particular window styles are available for this class.`


Events Processing
=================

This class processes the following events:

========================= ==================================================
Event Name                Description
========================= ==================================================
``EVT_SHORTCUT_CHANGING`` Event emitted when the user is about to change a shortcut.
``EVT_SHORTCUT_CHANGED``  Event emitted when the user has changed a shortcut.
========================= ==================================================


Supported Platforms
===================

:class:`ShortcutEditor` has been tested on the following platforms:
  * Windows (Windows Vista/7);


License And Version
===================

:class:`ShortcutEditor` is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 27 Dec 2012, 21.00 GMT

Version 0.1

.. versionadded:: 0.9.3


|function_summary| Functions Summary
====================================

================================================================================ ================================================================================
:func:`~wx.lib.agw.shortcuteditor.FontFromFont`                                  Creates a copy of the input `font`.
================================================================================ ================================================================================


|


|class_summary| Classes Summary
===============================

================================================================================ ================================================================================
:ref:`~wx.lib.agw.shortcuteditor.ConflictDialog`                                 :class:`ConflictDialog` is a subclass of :class:`GenericMessageDialog`, customized to look
:ref:`~wx.lib.agw.shortcuteditor.HTMLHelpWindow`                                 A simple :class:`wx.Frame` container for the basic help provided to :class:`ShortcutEditor`.
:ref:`~wx.lib.agw.shortcuteditor.ListShortcut`                                   :class:`ListShortcut` is a subclass of :class:`~wx.lib.agw.hypertreelist.HyperTreeList`,
:ref:`~wx.lib.agw.shortcuteditor.Shortcut`                                       :class:`Shortcut` is a class containing the details for a shortcut, whether from
:ref:`~wx.lib.agw.shortcuteditor.ShortcutEditor`                                 :class:`ShortcutEditor` is a widget that allows the user to customize and change keyboard
:ref:`~wx.lib.agw.shortcuteditor.ShortcutEvent`                                  :class:`ShortcutEvent` is a special subclassing of :class:`PyCommandEvent`.
================================================================================ ================================================================================


|


.. toctree::
   :maxdepth: 1
   :hidden:

   wx.lib.agw.shortcuteditor.ConflictDialog
   wx.lib.agw.shortcuteditor.HTMLHelpWindow
   wx.lib.agw.shortcuteditor.ListShortcut
   wx.lib.agw.shortcuteditor.Shortcut
   wx.lib.agw.shortcuteditor.ShortcutEditor
   wx.lib.agw.shortcuteditor.ShortcutEvent





Functions
------------

.. function:: FontFromFont(font)

   Creates a copy of the input `font`.
   
   :param `font`: an instance of :class:`wx.Font`.


