.. wxPython Phoenix documentation

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

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

.. include:: headings.inc

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

.. highlight:: python



.. _wx.lib.agw.shortcuteditor.Shortcut:

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

:class:`Shortcut` is a class containing the details for a shortcut, whether from
a menu item, an accelerator or a user-defined shortcut. It behaves like
a tree, with children and parents.



|

|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>Shortcut</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.Shortcut_inheritance.png" alt="Inheritance diagram of Shortcut" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.lib.agw.shortcuteditor.Shortcut.html" title="wx.lib.agw.shortcuteditor.Shortcut" alt="" coords="5,5,240,35"/> </map> 
   </p>

|


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

================================================================================ ================================================================================
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.__init__`                             Default class constructor.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.AppendItem`                           Appends a :class:`Shortcut` item as a last child of its parent.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.CheckAccelerator`                     Checks if a shortcut string entered by the user has already been taken by another entry
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.FromMenuItem`                         Constructs this :class:`Shortcut` starting from a :class:`wx.Menu` or :class:`wx.MenuItem`.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.Get`                                  Returns an instance of :class:`Shortcut` whose label matches the input `label` string.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.GetAccelerator`                       Returns the string accelerator associated with this shortcut.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.GetBitmap`                            Returns the bitmap associated with this :class:`Shortcut`.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.GetById`                              Returns an instance of :class:`Shortcut` whose ID matches the input `id`.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.GetFirstChild`                        Returns this :class:`Shortcut`'s first child and an integer value 'cookie'.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.GetId`                                Returns this :class:`Shortcut` ID.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.GetImageIndex`                        Returns an integer index to be used in the :class:`ListShortcut` own :class:`wx.ImageList`.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.GetLabel`                             Returns the string label associated with this shortcut.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.GetNextChild`                         Returns this :class:`Shortcut`'s next child.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.HasChanged`                           Returns ``True`` if the current accelerator associated with this :class:`Shortcut` is
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.IsTop`                                Returns ``True`` if this :class:`Shortcut` is associated with a top-level :class:`wx.Menu`,
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.Match`                                Matches this :class:`Shortcut` label string against the `filter` input variable.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.ResetVisibility`                      Set the status of this :class:`Shortcut` and its parent as `hidden` in the
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.RestoreDefaults`                      Restore the original shortcut string for this :class:`Shortcut`.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.SetAccelerator`                       Sets the string accelerator associated with this shortcut.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.SetBitmap`                            Sets the bitmap associated with this :class:`Shortcut`.
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.ShowHierarchy`                        Set the status of this :class:`Shortcut` ans its parent as `shown` in the
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.ToAcceleratorItem`                    Dumps this :class:`Shortcut` into a tuple of 3 elements
:meth:`~wx.lib.agw.shortcuteditor.Shortcut.ToMenuItem`                           Dumps this :class:`Shortcut` into a :class:`wx.Menu` or :class:`wx.MenuItem`.
================================================================================ ================================================================================


|


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


.. class:: Shortcut(object)

   :class:`Shortcut` is a class containing the details for a shortcut, whether from
   a menu item, an accelerator or a user-defined shortcut. It behaves like
   a tree, with children and parents.

   .. method:: __init__(self, label='', accelerator='', bitmap=wx.NullBitmap, help='', menuItem=None, accelId=None)

      Default class constructor.
      
      :param string `label`: the shortcut label string;
      :param string `accelerator`: the shortcut accelerator string;
      :param `bitmap`: an instance of :class:`wx.Bitmap`, to display along the shortcut `label`
       in the interface tree;
      :param string `help`: the help string for this shortcut, to display in the interface tree;
      :param `menuItem`: if this :class:`Shortcut` is derived from a :class:`wx.MenuItem`, the :class:`wx.MenuItem`
       to which it should be associated;
      :param integer `accelId`: if this :class:`Shortcut` is derived from an accelerator in a :class:`AcceleratorTable`
       or from a custom, developer-defined shortcut, it represents the ID it is associated with.


   .. method:: AppendItem(self, item)

      Appends a :class:`Shortcut` item as a last child of its parent.
      
      :param `item`: an instance of :class:`Shortcut`.


   .. method:: CheckAccelerator(self, item, shortcut, accelerator)

      Checks if a shortcut string entered by the user has already been taken by another entry
      in the :class:`Shortcut` hierarchy.
      
      :param `item`: an instance of :class:`Shortcut`;
      :param `shortcut`: another instance of :class:`Shortcut`, to compare with the previous `item`;
      :param string `accelerator`: the user-edited accelerator string to check.
      
      :return: An instance of :class:`Shortcut` if the shortcut string entered by the user conflicts
       with an existing one, ``None`` otherwise.


   .. method:: FromMenuItem(self)

      Constructs this :class:`Shortcut` starting from a :class:`wx.Menu` or :class:`wx.MenuItem`.
      
      The attributes needed to properly construct a :class:`Shortcut` are the label,
      the accelerator string, the help string (optional) and the bitmap associated
      with it (optional).


   .. method:: Get(self, label, item=None)

      Returns an instance of :class:`Shortcut` whose label matches the input `label` string.
      
      :param string `label`: the string label to compare against this :class:`Shortcut` label;
      :param `item`: an instance of :class:`Shortcut`, used only to make this function reentrant
       (i.e. allow more than one enumeration on one and the same object simultaneously).
      
      :return: An instance of :class:`Shortcut` or ``None`` if no match was found.


   .. method:: GetAccelerator(self)

      Returns the string accelerator associated with this shortcut. 


   .. method:: GetBitmap(self)

      Returns the bitmap associated with this :class:`Shortcut`.
      
      :note: You should always check if the returned bitmap is a valid one or not::
      
          bitmap = shortcut.GetBitmap()
          if bitmap.IsOk():
              DoSomething()
      
      
       as the default bitmap associated with a :class:`Shortcut` is :class:`NullBitmap`.


   .. method:: GetById(self, id, item=None)

      Returns an instance of :class:`Shortcut` whose ID matches the input `id`.
      
      :param integer `id`: an integer ID to compare against this :class:`Shortcut` id;
      :param `item`: an instance of :class:`Shortcut`, used only to make this function reentrant
       (i.e. allow more than one enumeration on one and the same object simultaneously).
      
      :return: An instance of :class:`Shortcut` or ``None`` if no match was found.


   .. method:: GetFirstChild(self, item)

      Returns this :class:`Shortcut`'s first child and an integer value 'cookie'.
      Call :meth:`~Shortcut.GetNextChild` for the next child using this very 'cookie' return
      value as an input.
      
      :param `item`: an instance of :class:`Shortcut`.
      
      :return: A tuple with the first value being an instance of :class:`Shortcut` or ``None`` if there are no
       further children, and as second value an integer parameter 'cookie'.
      
      :note: This method returns ``None`` if there are no further children.


   .. method:: GetId(self)

      Returns this :class:`Shortcut` ID. 


   .. method:: GetImageIndex(self)

      Returns an integer index to be used in the :class:`ListShortcut` own :class:`wx.ImageList`. 


   .. method:: GetLabel(self)

      Returns the string label associated with this shortcut. 


   .. method:: GetNextChild(self, item, cookie)

      Returns this :class:`Shortcut`'s next child.
      
      :param `item`: an instance of :class:`Shortcut`;
      :param integer `cookie`: a parameter which is opaque for the application but is necessary
       for the library to make this function reentrant (i.e. allow more than one
       enumeration on one and the same object simultaneously).
      
      :return: A tuple with the first value being an instance of :class:`Shortcut` or ``None`` if there are no
       further children, and as second value an integer parameter 'cookie'.
      
      :note: This method returns ``None`` if there are no further children.


   .. method:: HasChanged(self)

      Returns ``True`` if the current accelerator associated with this :class:`Shortcut` is
      different from the original one, ``False`` otherwise.


   .. method:: IsTop(self)

      Returns ``True`` if this :class:`Shortcut` is associated with a top-level :class:`wx.Menu`,
      (i.e., in the top :class:`wx.MenuBar` level), ``False`` otherwise.


   .. method:: Match(self, filter='', item=None)

      Matches this :class:`Shortcut` label string against the `filter` input variable.
      
      :param string `filter`: a string to match;
      :param `item`: an instance of :class:`Shortcut`: its label string is compared with
       the `filter` string to look for a match.
      
      :return: An instance of :class:`Shortcut` if the `filter` string is contained in
       the `item` lable, ``None`` otherwise.
      
      :note: The string-matching is case-insensitive.


   .. method:: ResetVisibility(self, item=None)

      Set the status of this :class:`Shortcut` and its parent as `hidden` in the
      :class:`ListShortcut` tree hierarchy.
      
      :param `item`: an instance of :class:`Shortcut`, used only to make this function reentrant
       (i.e. allow more than one enumeration on one and the same object simultaneously).


   .. method:: RestoreDefaults(self, item=None)

      Restore the original shortcut string for this :class:`Shortcut`.
      
      :param `item`: an instance of :class:`Shortcut`, used only to make this function reentrant
       (i.e. allow more than one enumeration on one and the same object simultaneously).


   .. method:: SetAccelerator(self, accelerator)

      Sets the string accelerator associated with this shortcut.
      
      :param string `accelerator`: a string representing the shortcut string (accelerator).


   .. method:: SetBitmap(self, bitmap)

      Sets the bitmap associated with this :class:`Shortcut`.
      
      :param `bitmap`: an instance of :class:`wx.Bitmap` (can be invalid, i.e., :class:`NullBitmap`).


   .. method:: ShowHierarchy(self, item)

      Set the status of this :class:`Shortcut` ans its parent as `shown` in the
      :class:`ListShortcut` tree hierarchy.
      
      :param `item`: an instance of :class:`Shortcut`.


   .. method:: ToAcceleratorItem(self, table)

      Dumps this :class:`Shortcut` into a tuple of 3 elements:
      
      * **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.
      
      :param `table`: a list of tuples, with the above specifications.


   .. method:: ToMenuItem(self, menuBar)

      Dumps this :class:`Shortcut` into a :class:`wx.Menu` or :class:`wx.MenuItem`.
      
      The attributes needed to properly dump a :class:`Shortcut` into a :class:`wx.Menu` or :class:`wx.MenuBar`
      are the label and the accelerator string.
      
      :param `menuBar`: an instance of :class:`wx.MenuBar`.


