AGW Logo

agw_title shortcuteditor

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

Note

ShortcutEditor requires the minimum AGW version 0.9.3 or the current SVN, for the various enhancements made to the HyperTreeList and GenericMessageDialog widgets.


description Description

ShortcutEditor is a widget that allows the user to customize and change keyboard shortcuts via a dialog. It can be used to edit wx.MenuItem shortcuts or accelerators defined in a wx.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 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 ShortcutEditor is used to edit wx.MenuItem shortcuts);
  • Accelerators defined via wx.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 wx.MenuBar or the original wx.AcceleratorTable;
  • Filters on the shortcuts label (case-insensitive);
  • Basic help window with instructions (customizable via SetHTMLHelpFile), via the Help button.

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


interface UI Interactions

  1. In the 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.

    Open Subsections

    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.

    Assign Shortcut

    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.

    Remove/Save Shortcuts

    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.

    Reassigning Shortcuts

    Figure 4


base Base Functionalities

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

  1. Use the FromMenuBar method: if you need to give your user the ability to edit the various wx.MenuItem shortcuts in your application, you can create 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 FromAcceleratorTable method: if you need to give your user the ability to edit the various accelerators you set via wx.AcceleratorTable in your application, you can create 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 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

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.PySimpleApp()

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

app.MainLoop()

This code snippet can be downloaded, see this example script.

Note

Some of the AGW snippets of code in the documentation use images and external files (to create bitmaps or access external data). As these files are not provided in these snippets, you should make the approriate modifications to the code to actually run it.


styles Window Styles

No particular window styles are available for this class.


events Events Processing

This class processes the following events:


Events processing for shortcuteditor
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.

platforms Supported Platforms

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

license License And Version

ShortcutEditor is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 06 Mar 2012, 21.00 GMT

Version 0.1

New in version 0.9.3.

Module author: Andrea Gavana <andrea.gavana@gmail.com>


hierarchy Inheritance Diagram

Inheritance diagram for module: shortcuteditor

Inheritance diagram of shortcuteditor.ConflictDialog, shortcuteditor.HTMLHelpWindow, shortcuteditor.ListShortcut, shortcuteditor.Shortcut, shortcuteditor.ShortcutEditor, shortcuteditor.ShortcutEvent


svn_main SVN Revisions

A graphical representation of the SVN commits in the last year.

Click on any date in the picture to jump to that particular revision page, containing information about committers, log messages and SVN diffs.

shortcuteditor

Revision Graph For shortcuteditor


2to3 Python 3 Issues (via 2to3)

No issues have been detected by 2to3.py.


method_summary Function Summary