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

.. currentmodule:: wx.lib.agw.flatnotebook

.. highlight:: python



.. _wx.lib.agw.flatnotebook:

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

:class:`~wx.lib.agw.flatnotebook.FlatNotebook` is a full, generic and owner-drawn implementation of :class:`Notebook`.


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

:class:`FlatNotebook` is a full implementation of the :class:`Notebook`, and designed to be
a drop-in replacement for :class:`Notebook`. The API functions are similar so one can
expect the function to behave in the same way.

Some features:

- The buttons are highlighted a la Firefox style;
- The scrolling is done for bulks of tabs (so, the scrolling is faster and better);
- The buttons area is never overdrawn by tabs (unlike many other implementations I saw);
- It is a generic control;
- Currently there are 6 different styles - VC8, VC 71, Standard, Fancy, Firefox 2 and Ribbon;
- Mouse middle click can be used to close tabs;
- A function to add right click menu for tabs (simple as :meth:`~FlatNotebook.SetRightClickMenu`);
- All styles has bottom style as well (they can be drawn in the bottom of screen);
- An option to hide 'X' button or navigation buttons (separately);
- Gradient colouring of the selected tabs and border;
- Support for drag 'n' drop of tabs, both in the same notebook or to another notebook;
- Possibility to have closing button on the active tab directly;
- Support for disabled tabs;
- Colours for active/inactive tabs, and captions;
- Background of tab area can be painted in gradient (VC8 style only);
- Colourful tabs - a random gentle colour is generated for each new tab (very cool, VC8 style only);
- Support for showing pages in "column/row mode", which means that all the pages will be
  shown in "tile" mode while the tabs are hidden;
- Possibility to add a custom panel to show a logo or HTML documentation or
  whatever you like when there are no pages left in :class:`FlatNotebook`;
- Try setting the tab area colour for the Ribbon Style.


And much more.


Usage
=====

Usage example::

    import wx
    import wx.lib.agw.flatnotebook as fnb

    class MyFrame(wx.Frame):

        def __init__(self, parent):

            wx.Frame.__init(self, parent, -1, "FlatNotebook Demo")

            panel = wx.Panel(self)

            notebook = fnb.FlatNotebook(panel, -1)

            for i in range(3):
                caption = "Page %d"%(i+1)
                notebook.AddPage(self.CreatePage(notebook, caption), caption)

            sizer = wx.BoxSizer(wx.VERTICAL)
            sizer.Add(notebook, 1, wx.ALL | wx.EXPAND, 5)
            panel.SetSizer(sizer)


        def CreatePage(self, notebook, caption):
            '''
            Creates a simple :class:`Panel` containing a :class:`TextCtrl`.

            :param `notebook`: an instance of `FlatNotebook`;
            :param `caption`: a simple label.
            '''

            p = wx.Panel(notebook)
            wx.StaticText(p, -1, caption, (20,20))
            wx.TextCtrl(p, -1, "", (20,40), (150,-1))
            return p


    # our normal wxApp-derived class, as usual

    app = wx.App(0)

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

    app.MainLoop()



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

This class supports the following window styles:

================================ =========== ==================================================
Window Styles                    Hex Value   Description
================================ =========== ==================================================
``FNB_VC71``                             0x1 Use Visual Studio 2003 (VC7.1) style for tabs.
``FNB_FANCY_TABS``                       0x2 Use fancy style - square tabs filled with gradient colouring.
``FNB_TABS_BORDER_SIMPLE``               0x4 Draw thin border around the page.
``FNB_NO_X_BUTTON``                      0x8 Do not display the 'X' button.
``FNB_NO_NAV_BUTTONS``                  0x10 Do not display the right/left arrows.
``FNB_MOUSE_MIDDLE_CLOSES_TABS``        0x20 Use the mouse middle button for cloing tabs.
``FNB_BOTTOM``                          0x40 Place tabs at bottom - the default is to place them at top.
``FNB_NODRAG``                          0x80 Disable dragging of tabs.
``FNB_VC8``                            0x100 Use Visual Studio 2005 (VC8) style for tabs.
``FNB_X_ON_TAB``                       0x200 Place 'X' close button on the active tab.
``FNB_BACKGROUND_GRADIENT``            0x400 Use gradients to paint the tabs background.
``FNB_COLOURFUL_TABS``                 0x800 Use colourful tabs (VC8 style only).
``FNB_DCLICK_CLOSES_TABS``            0x1000 Style to close tab using double click.
``FNB_SMART_TABS``                    0x2000 Use `Smart Tabbing`, like ``Alt`` + ``Tab`` on Windows.
``FNB_DROPDOWN_TABS_LIST``            0x4000 Use a dropdown menu on the left in place of the arrows.
``FNB_ALLOW_FOREIGN_DND``             0x8000 Allows drag 'n' drop operations between different :class:`FlatNotebook`.
``FNB_HIDE_ON_SINGLE_TAB``           0x10000 Hides the Page Container when there is one or fewer tabs.
``FNB_DEFAULT_STYLE``                0x10020 :class:`FlatNotebook` default style.
``FNB_FF2``                          0x20000 Use Firefox 2 style for tabs.
``FNB_NO_TAB_FOCUS``                 0x40000 Does not allow tabs to have focus.
``FNB_RIBBON_TABS``                  0x80000 Use the Ribbon Tabs style
``FNB_HIDE_TABS``                   0x100000 Hides the Page Container allowing only keyboard navigation
``FNB_NAV_BUTTONS_WHEN_NEEDED``     0x200000 Hides the navigation left/right arrows if all tabs fit
================================ =========== ==================================================


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

This class processes the following events:

========================================= ==================================================
Event Name                                Description
========================================= ==================================================
``EVT_FLATNOTEBOOK_PAGE_CHANGED``         Notify client objects when the active page in :class:`FlatNotebook` has changed.
``EVT_FLATNOTEBOOK_PAGE_CHANGING``        Notify client objects when the active page in :class:`FlatNotebook` is about to change.
``EVT_FLATNOTEBOOK_PAGE_CLOSED``          Notify client objects when a page in :class:`FlatNotebook` has been closed.
``EVT_FLATNOTEBOOK_PAGE_CLOSING``         Notify client objects when a page in :class:`FlatNotebook` is closing.
``EVT_FLATNOTEBOOK_PAGE_CONTEXT_MENU``    Notify client objects when a pop-up menu should appear next to a tab.
``EVT_FLATNOTEBOOK_PAGE_DROPPED``         Notify client objects when a tab has been dropped and re-arranged (on the *same* notebook)
``EVT_FLATNOTEBOOK_PAGE_DROPPED_FOREIGN`` Notify client objects when a tab has been dropped and re-arranged (from a foreign notebook)
========================================= ==================================================


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

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

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

Version 3.2


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

================================================================================ ================================================================================
:func:`~wx.lib.agw.flatnotebook.AdjustColour`                                    Brighten/darken input colour by `percent` and adjust `alpha` channel if needed.
:func:`~wx.lib.agw.flatnotebook.DrawButton`                                      Draws a :class:`FlatNotebook` tab.
:func:`~wx.lib.agw.flatnotebook.FormatColour`                                    Convert the input `colour` into a valid :class:`wx.Colour` instance, using whatever typemap
:func:`~wx.lib.agw.flatnotebook.LightColour`                                     Brighten the input colour by a percentage.
:func:`~wx.lib.agw.flatnotebook.PaintStraightGradientBox`                        Draws a gradient coloured box from `startColour` to `endColour`.
:func:`~wx.lib.agw.flatnotebook.RandomColour`                                    Creates a random colour.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:ref:`~wx.lib.agw.flatnotebook.FlatNotebook`                                     The :class:`FlatNotebook` is a full implementation of the :class:`Notebook`, and designed to be
:ref:`~wx.lib.agw.flatnotebook.FlatNotebookCompatible`                           This class is more compatible with the :class:`Notebook` API, especially regarding
:ref:`~wx.lib.agw.flatnotebook.FlatNotebookDragEvent`                            This event will be sent when a ``EVT_FLATNOTEBOOK_PAGE_DRAGGED_FOREIGN`` is
:ref:`~wx.lib.agw.flatnotebook.FlatNotebookEvent`                                This events will be sent when a ``EVT_FLATNOTEBOOK_PAGE_CHANGED``,
:ref:`~wx.lib.agw.flatnotebook.FNBDragInfo`                                      Stores all the information to allow drag and drop between different
:ref:`~wx.lib.agw.flatnotebook.FNBDropSource`                                    Give some custom UI feedback during the drag and drop operation in this
:ref:`~wx.lib.agw.flatnotebook.FNBDropTarget`                                    Class used to handle the :meth:`FlatNotebook.OnDropTarget() <FlatNotebook.OnDropTarget>` method when dragging and
:ref:`~wx.lib.agw.flatnotebook.FNBRenderer`                                      Parent class for the 6 renderers defined: `Standard`, `VC71`, `Fancy`, `Firefox 2`,
:ref:`~wx.lib.agw.flatnotebook.FNBRendererDefault`                               This class handles the drawing of tabs using the standard renderer.
:ref:`~wx.lib.agw.flatnotebook.FNBRendererFancy`                                 This class handles the drawing of tabs using the `Fancy` renderer.
:ref:`~wx.lib.agw.flatnotebook.FNBRendererFirefox2`                              This class handles the drawing of tabs using the `Firefox 2` renderer.
:ref:`~wx.lib.agw.flatnotebook.FNBRendererMgr`                                   This class represents a manager that handles all the 6 renderers defined
:ref:`~wx.lib.agw.flatnotebook.FNBRendererRibbonTabs`                            This class handles the drawing of tabs using the `Ribbon Tabs` renderer.
:ref:`~wx.lib.agw.flatnotebook.FNBRendererVC71`                                  This class handles the drawing of tabs using the `VC71` renderer.
:ref:`~wx.lib.agw.flatnotebook.FNBRendererVC8`                                   This class handles the drawing of tabs using the `VC8` renderer.
:ref:`~wx.lib.agw.flatnotebook.PageContainer`                                    This class acts as a container for the pages you add to :class:`FlatNotebook`.
:ref:`~wx.lib.agw.flatnotebook.PageInfo`                                         This class holds all the information (caption, image, etc...) belonging to a
:ref:`~wx.lib.agw.flatnotebook.TabNavigatorWindow`                               This class is used to create a modal dialog that enables `Smart Tabbing`,
================================================================================ ================================================================================


|


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

   wx.lib.agw.flatnotebook.FlatNotebook
   wx.lib.agw.flatnotebook.FlatNotebookCompatible
   wx.lib.agw.flatnotebook.FlatNotebookDragEvent
   wx.lib.agw.flatnotebook.FlatNotebookEvent
   wx.lib.agw.flatnotebook.FNBDragInfo
   wx.lib.agw.flatnotebook.FNBDropSource
   wx.lib.agw.flatnotebook.FNBDropTarget
   wx.lib.agw.flatnotebook.FNBRenderer
   wx.lib.agw.flatnotebook.FNBRendererDefault
   wx.lib.agw.flatnotebook.FNBRendererFancy
   wx.lib.agw.flatnotebook.FNBRendererFirefox2
   wx.lib.agw.flatnotebook.FNBRendererMgr
   wx.lib.agw.flatnotebook.FNBRendererRibbonTabs
   wx.lib.agw.flatnotebook.FNBRendererVC71
   wx.lib.agw.flatnotebook.FNBRendererVC8
   wx.lib.agw.flatnotebook.PageContainer
   wx.lib.agw.flatnotebook.PageInfo
   wx.lib.agw.flatnotebook.TabNavigatorWindow





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

.. function:: AdjustColour(colour, percent, alpha=wx.ALPHA_OPAQUE)

   Brighten/darken input colour by `percent` and adjust `alpha` channel if needed.
   
   :param `colour`: colour object to adjust, an instance of :class:`wx.Colour`;
   :param `percent`: percent to adjust ``+`` (brighten) or ``-`` (darken);
   :param `alpha`: amount to adjust the alpha channel.
   
   :return: The modified colour.


.. function:: DrawButton(dc, rect, focus, upperTabs)

   Draws a :class:`FlatNotebook` tab.
   
   :param `dc`: an instance of :class:`wx.DC`;
   :param `rect`: the tab's client rectangle;
   :param `focus`: ``True`` if the tab has focus, ``False`` otherwise;
   :param `upperTabs`: ``True`` if the tabs are at the top, ``False`` if they are
    at the bottom.


.. function:: FormatColour(colour)

   Convert the input `colour` into a valid :class:`wx.Colour` instance, using whatever typemap
   accepted by wxWidgets/wxPython.
   
   :param `colour`: can be an instance of :class:`wx.Colour`, a 3 or 4 integer tuple, a hex
    string, a string representing the colour name or ``None``.
   
   :returns: a valid instance of :class:`wx.Colour` or ``None`` if the input `colour` was ``None``
    in the first place.


.. function:: LightColour(colour, percent)

   Brighten the input colour by a percentage.
   
   :param `colour`: a valid :class:`wx.Colour` instance;
   :param `percent`: the percentage by which the input colour should be brightened.


.. function:: PaintStraightGradientBox(dc, rect, startColour, endColour, vertical=True)

   Draws a gradient coloured box from `startColour` to `endColour`.
   
   :param `dc`: an instance of :class:`wx.DC`;
   :param `rect`: the rectangle to fill with the gradient shading;
   :param `startColour`: the first colour in the gradient shading;
   :param `endColour`: the last colour in the gradient shading;
   :param `vertical`: ``True`` if the gradient shading is north to south, ``False``
    if it is east to west.


.. function:: RandomColour()

   Creates a random colour. 


