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

.. currentmodule:: wx.lib.agw.labelbook

.. highlight:: python



.. _wx.lib.agw.labelbook:

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

:class:`~wx.lib.agw.labelbook.LabelBook` and :class:`~wx.lib.agw.labelbook.FlatImageBook` are a quasi-full generic and owner-drawn
implementations of :class:`Notebook`.


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

:class:`LabelBook` and :class:`FlatImageBook` are quasi-full implementations 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.
:class:`LabelBook` anf :class:`FlatImageBook` share their appearance with :class:`Toolbook` and
:class:`Listbook`, while having more options for custom drawings, label positioning,
mouse pointing and so on. Moreover, they retain also some visual characteristics
of the Outlook address book.

Some features:

- They are generic controls;
- Supports for left, right, top (:class:`FlatImageBook` only), bottom (:class:`FlatImageBook`
  only) book styles;
- Possibility to draw images only, text only or both (:class:`FlatImageBook` only);
- Support for a "pin-button", that allows the user to shrink/expand the book
  tab area;
- Shadows behind tabs (:class:`LabelBook` only);
- Gradient shading of the tab area (:class:`LabelBook` only);
- Web-like mouse pointing on tabs style (:class:`LabelBook` only);
- Many customizable colours (tab area, active tab text, tab borders, active
  tab, highlight) - :class:`LabelBook` only.

And much more. See the demo for a quasi-complete review of all the functionalities
of :class:`LabelBook` and :class:`FlatImageBook`.


Usage
=====

Usage example::

    import wx
    import wx.lib.agw.labelbook as LB

    class MyFrame(wx.Frame):

        def __init__(self, parent):

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

            # Possible values for Tab placement are INB_TOP, INB_BOTTOM, INB_RIGHT, INB_LEFT

            notebook = LB.LabelBook(self, -1, agwStyle=LB.INB_FIT_LABELTEXT|LB.INB_LEFT|LB.INB_DRAW_SHADOW|LB.INB_GRADIENT_BACKGROUND)

            pane1 = wx.Panel(notebook)
            pane2 = wx.Panel(notebook)

            imagelist = wx.ImageList(32, 32)
            imagelist.Add(wx.Bitmap("my_bitmap.png", wx.BITMAP_TYPE_PNG))
            notebook.AssignImageList(imagelist)

            notebook.AddPage(pane_1, "Tab1", 1, 0)
            notebook.AddPage(pane_2, "Tab2", 0, 0)


    # our normal wxApp-derived class, as usual

    app = wx.App(0)

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

    app.MainLoop()



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

:class:`LabelBook` and :class:`FlatImageBook` have been tested on the following platforms:
  * Windows (Windows XP);
  * Linux Ubuntu (Dapper 6.06)


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

This class supports the following window styles:

=========================== =========== ==================================================
Window Styles               Hex Value   Description
=========================== =========== ==================================================
``INB_BOTTOM``                      0x1 Place labels below the page area. Available only for :class:`FlatImageBook`.
``INB_LEFT``                        0x2 Place labels on the left side. Available only for :class:`FlatImageBook`.
``INB_RIGHT``                       0x4 Place labels on the right side.
``INB_TOP``                         0x8 Place labels above the page area.
``INB_BORDER``                     0x10 Draws a border around :class:`LabelBook` or :class:`FlatImageBook`.
``INB_SHOW_ONLY_TEXT``             0x20 Shows only text labels and no images. Available only for :class:`LabelBook`.
``INB_SHOW_ONLY_IMAGES``           0x40 Shows only tab images and no label texts. Available only for :class:`LabelBook`.
``INB_FIT_BUTTON``                 0x80 Displays a pin button to show/hide the book control.
``INB_DRAW_SHADOW``               0x100 Draw shadows below the book tabs. Available only for :class:`LabelBook`.
``INB_USE_PIN_BUTTON``            0x200 Displays a pin button to show/hide the book control.
``INB_GRADIENT_BACKGROUND``       0x400 Draws a gradient shading on the tabs background. Available only for :class:`LabelBook`.
``INB_WEB_HILITE``                0x800 On mouse hovering, tabs behave like html hyperlinks. Available only for :class:`LabelBook`.
``INB_NO_RESIZE``                0x1000 Don't allow resizing of the tab area.
``INB_FIT_LABELTEXT``            0x2000 Will fit the tab area to the longest text (or text+image if you have images) in all the tabs.
``INB_BOLD_TAB_SELECTION``       0x4000 Show the selected tab text using a bold font.
=========================== =========== ==================================================


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

This class processes the following events:

=================================== ==================================================
Event Name                          Description
=================================== ==================================================
``EVT_IMAGENOTEBOOK_PAGE_CHANGED``  Notify client objects when the active page in :class:`FlatImageBook` or :class:`LabelBook` has changed.
``EVT_IMAGENOTEBOOK_PAGE_CHANGING`` Notify client objects when the active page in :class:`FlatImageBook` or :class:`LabelBook` is about to change.
``EVT_IMAGENOTEBOOK_PAGE_CLOSED``   Notify client objects when a page in :class:`FlatImageBook` or :class:`LabelBook` has been closed.
``EVT_IMAGENOTEBOOK_PAGE_CLOSING``  Notify client objects when a page in :class:`FlatImageBook` or :class:`LabelBook` is closing.
=================================== ==================================================


TODOs
=====

- :class:`LabelBook`: support ``IMB_SHOW_ONLY_IMAGES``;
- :class:`LabelBook`: an option to only draw the border between the controls and the pages so the background
  colour can flow into the window background.


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

:class:`LabelBook` and :class:`FlatImageBook` are distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 22 Jan 2013, 21.00 GMT

Version 0.6.


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

================================================================================ ================================================================================
:ref:`~wx.lib.agw.labelbook.FlatBookBase`                                        Base class for the containing window for :class:`LabelBook` and :class:`FlatImageBook`.
:ref:`~wx.lib.agw.labelbook.FlatImageBook`                                       Default implementation of the image book, it is like a :class:`Notebook`, except that
:ref:`~wx.lib.agw.labelbook.ImageContainer`                                      Base class for :class:`FlatImageBook` image container.
:ref:`~wx.lib.agw.labelbook.ImageContainerBase`                                  Base class for :class:`FlatImageBook` image container.
:ref:`~wx.lib.agw.labelbook.ImageInfo`                                           This class holds all the information (caption, image, etc...) belonging to a
:ref:`~wx.lib.agw.labelbook.ImageNotebookEvent`                                  This events will be sent when a ``EVT_IMAGENOTEBOOK_PAGE_CHANGED``,
:ref:`~wx.lib.agw.labelbook.LabelBook`                                           An implementation of a notebook control - except that instead of having
:ref:`~wx.lib.agw.labelbook.LabelContainer`                                      Base class for :class:`LabelBook`.
================================================================================ ================================================================================


|


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

   wx.lib.agw.labelbook.FlatBookBase
   wx.lib.agw.labelbook.FlatImageBook
   wx.lib.agw.labelbook.ImageContainer
   wx.lib.agw.labelbook.ImageContainerBase
   wx.lib.agw.labelbook.ImageInfo
   wx.lib.agw.labelbook.ImageNotebookEvent
   wx.lib.agw.labelbook.LabelBook
   wx.lib.agw.labelbook.LabelContainer



