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

.. module:: wx.lib.agw.flatmenu

.. currentmodule:: wx.lib.agw.flatmenu

.. highlight:: python



.. _wx.lib.agw.flatmenu:

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

:class:`~wx.lib.agw.flatmenu.FlatMenu` is a generic menu implementation.


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

:class:`FlatMenu`, like the name implies, it is a generic menu implementation.
I tried to provide a full functionality for menus, menubar and toolbar.


:class:`FlatMenu` supports the following features:

- Fires all the events (UI & Cmd);
- Check items;
- Separators;
- Enabled / Disabled menu items;
- Images on items;
- Toolbar support, with images and separators;
- Controls in toolbar (work in progress);
- Toolbar tools tooltips (done: thanks to Peter Kort);
- Accelerators for menus;
- Accelerators for menubar;
- Radio items in menus;
- Integration with AUI;
- Scrolling when menu is too big to fit the screen;
- Menu navigation with keyboard;
- Drop down arrow button to the right of the menu, it always contains the
  "Customize" option, which will popup an options dialog. The dialog has the
  following abilities:

  (a) Ability to add/remove menus;
  (b) Select different colour schemes for the menu bar / toolbar;
  (c) Control various options, such as: colour for highlight menu item, draw
      border around menus (classic look only);
  (d) Toolbar floating appearance.

- Allows user to specify grey bitmap for disabled menus/toolbar tools;
- If no grey bitmap is provided, it generates one from the existing bitmap;
- Hidden toolbar items / menu bar items - will appear in a small popmenu
  to the right if they are hidden;
- 4 different colour schemes for the menu bar (more can easily added);
- Scrolling is available if the menu height is greater than the screen height;
- Context menus for menu items;
- Show/hide the drop down arrow which allows the customization of :class:`FlatMenu`;
- Multiple columns menu window;
- Tooltips for menus and toolbar items on a :class:`StatusBar` (if present);
- Transparency (alpha channel) for menu windows (for platforms supporting it);
- FileHistory support through a pure-Python :class:`FileHistory` implementation;
- Possibility to set a background bitmap for a :class:`FlatMenu`;
- First attempt in adding controls to FlatToolbar;
- Added a MiniBar (thanks to Vladiuz);
- Added :class:`ToolBar` methods AddCheckTool/AddRadioTool (thanks to Vladiuz).


Usage
=====

Usage example::

    import wx
    import wx.lib.agw.flatmenu as FM

    class MyFrame(wx.Frame):

        def __init__(self, parent):

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

            self.CreateMenu()

            panel = wx.Panel(self, -1)
            btn = wx.Button(panel, -1, "Hello", (15, 12), (100, 120))

            main_sizer = wx.BoxSizer(wx.VERTICAL)
            main_sizer.Add(self.menubar, 0, wx.EXPAND)
            main_sizer.Add(panel, 1, wx.EXPAND)

            self.SetSizer(main_sizer)
            main_sizer.Layout()


        def CreateMenu(self):

            self.menubar = FM.FlatMenuBar(self, -1)

            f_menu = FM.FlatMenu()
            e_menu = FM.FlatMenu()
            v_menu = FM.FlatMenu()
            t_menu = FM.FlatMenu()
            w_menu = FM.FlatMenu()

            # Append the menu items to the menus
            f_menu.Append(-1, "Simple   Ctrl+N", "Text", None)
            e_menu.Append(-1, "FlatMenu", "Text", None)
            v_menu.Append(-1, "Example", "Text", None)
            t_menu.Append(-1, "Hello", "Text", None)
            w_menu.Append(-1, "World", "Text", None)

            # Append menus to the menubar
            self.menubar.Append(f_menu, "&File")
            self.menubar.Append(e_menu, "&Edit")
            self.menubar.Append(v_menu, "&View")
            self.menubar.Append(t_menu, "&Options")
            self.menubar.Append(w_menu, "&Help")


    # our normal wxApp-derived class, as usual

    app = wx.App(0)

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

    app.MainLoop()



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

:class:`FlatMenu` has been tested on the following platforms:
  * Windows (Windows XP, Vista);
  * Linux Ubuntu (Dapper 6.06)



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

This class supports the following window styles:

========================= =========== ==================================================
Window Styles             Hex Value   Description
========================= =========== ==================================================
``FM_OPT_IS_LCD``                 0x1 Use this style if your computer uses a LCD screen.
``FM_OPT_MINIBAR``                0x2 Use this if you plan to use the toolbar only.
``FM_OPT_SHOW_CUSTOMIZE``         0x4 Show "customize link" in the `More` menu, you will need to write your own handler. See demo.
``FM_OPT_SHOW_TOOLBAR``           0x8 Set this option is you are planning to use the toolbar.
========================= =========== ==================================================


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

This class processes the following events:

================================= ==================================================
Event Name                        Description
================================= ==================================================
``EVT_FLAT_MENU_DISMISSED``       Used internally.
``EVT_FLAT_MENU_ITEM_MOUSE_OUT``  Fires an event when the mouse leaves a :class:`FlatMenuItem`.
``EVT_FLAT_MENU_ITEM_MOUSE_OVER`` Fires an event when the mouse enters a :class:`FlatMenuItem`.
``EVT_FLAT_MENU_SELECTED``        Fires the :class:`EVT_MENU` event for :class:`FlatMenu`.
================================= ==================================================


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

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

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

Version 1.0


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

================================================================================ ================================================================================
:func:`~wx.lib.agw.flatmenu.ConvertToMonochrome`                                 Converts a bitmap to monochrome colour.
:func:`~wx.lib.agw.flatmenu.GetAccelIndex`                                       Returns the mnemonic index of the label and the label stripped of the ampersand mnemonic
:func:`~wx.lib.agw.flatmenu.GetMRUEntryLabel`                                    Returns the string used for the MRU list items in the menu.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:ref:`~wx.lib.agw.flatmenu.FileHistory`                                          The :class:`FileHistory` encapsulates a user interface convenience, the list of most
:ref:`~wx.lib.agw.flatmenu.FlatMenu`                                             A Flat popup menu generic implementation.
:ref:`~wx.lib.agw.flatmenu.FlatMenuBar`                                          Implements the generic owner-drawn menu bar for :class:`FlatMenu`.
:ref:`~wx.lib.agw.flatmenu.FlatMenuBase`                                         Base class for generic flat menu derived from :class:`PopupWindow`.
:ref:`~wx.lib.agw.flatmenu.FlatMenuButton`                                       A nice small class that functions like :class:`wx.BitmapButton`, the reason I did
:ref:`~wx.lib.agw.flatmenu.FlatMenuEvent`                                        Event class that supports the :class:`FlatMenu`-compatible event called
:ref:`~wx.lib.agw.flatmenu.FlatMenuItem`                                         A class that represents an item in a menu.
:ref:`~wx.lib.agw.flatmenu.FlatMenuItemGroup`                                    A class that manages a group of radio menu items.
:ref:`~wx.lib.agw.flatmenu.FlatToolbarItem`                                      This class represents a toolbar item.
:ref:`~wx.lib.agw.flatmenu.FMRenderer`                                           Base class for the :class:`FlatMenu` renderers. This class implements the common
:ref:`~wx.lib.agw.flatmenu.FMRendererMgr`                                        This class represents a manager that handles all the renderers defined.
:ref:`~wx.lib.agw.flatmenu.FMRendererMSOffice2007`                               Windows Office 2007 style.
:ref:`~wx.lib.agw.flatmenu.FMRendererVista`                                      Windows Vista-like style.
:ref:`~wx.lib.agw.flatmenu.FMRendererXP`                                         Xp-Style renderer.
:ref:`~wx.lib.agw.flatmenu.FocusHandler`                                         A focus event handler.
:ref:`~wx.lib.agw.flatmenu.mcPopupWindow`                                        Since Max OS does not support :class:`PopupWindow`, this is an alternative.
:ref:`~wx.lib.agw.flatmenu.MenuEntryInfo`                                        Internal class which holds information about a menu.
:ref:`~wx.lib.agw.flatmenu.MenuKbdRedirector`                                    A keyboard event handler.
:ref:`~wx.lib.agw.flatmenu.ShadowPopupWindow`                                    Base class for generic :class:`FlatMenu` derived from :class:`PopupWindow`.
:ref:`~wx.lib.agw.flatmenu.StatusBarTimer`                                       Timer used for deleting :class:`StatusBar` long help after ``_DELAY`` seconds.
:ref:`~wx.lib.agw.flatmenu.ToolBarItem`                                          A simple class that holds information about a toolbar item.
================================================================================ ================================================================================


|


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

   wx.lib.agw.flatmenu.FileHistory
   wx.lib.agw.flatmenu.FlatMenu
   wx.lib.agw.flatmenu.FlatMenuBar
   wx.lib.agw.flatmenu.FlatMenuBase
   wx.lib.agw.flatmenu.FlatMenuButton
   wx.lib.agw.flatmenu.FlatMenuEvent
   wx.lib.agw.flatmenu.FlatMenuItem
   wx.lib.agw.flatmenu.FlatMenuItemGroup
   wx.lib.agw.flatmenu.FlatToolbarItem
   wx.lib.agw.flatmenu.FMRenderer
   wx.lib.agw.flatmenu.FMRendererMgr
   wx.lib.agw.flatmenu.FMRendererMSOffice2007
   wx.lib.agw.flatmenu.FMRendererVista
   wx.lib.agw.flatmenu.FMRendererXP
   wx.lib.agw.flatmenu.FocusHandler
   wx.lib.agw.flatmenu.mcPopupWindow
   wx.lib.agw.flatmenu.MenuEntryInfo
   wx.lib.agw.flatmenu.MenuKbdRedirector
   wx.lib.agw.flatmenu.ShadowPopupWindow
   wx.lib.agw.flatmenu.StatusBarTimer
   wx.lib.agw.flatmenu.ToolBarItem





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

.. function:: ConvertToMonochrome(bmp)

   Converts a bitmap to monochrome colour.
   
   :param `bmp`: a valid :class:`wx.Bitmap` object.


.. function:: GetAccelIndex(label)

   Returns the mnemonic index of the label and the label stripped of the ampersand mnemonic
   (e.g. 'lab&el' ==> will result in 3 and labelOnly = label).
   
   :param string `label`: a string possibly containining an ampersand.


.. function:: GetMRUEntryLabel(n, path)

   Returns the string used for the MRU list items in the menu.
   
   :param integer `n`: the index of the file name in the MRU list;
   :param string `path`: the full path of the file name.
   
   :note: The index `n` is 0-based, as usual, but the strings start from 1.


