.. wxPython Phoenix documentation

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

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

.. include:: headings.inc

.. module:: wx.lib.agw.aui.aui_utilities

.. currentmodule:: wx.lib.agw.aui.aui_utilities

.. highlight:: python



.. _wx.lib.agw.aui.aui_utilities:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.aui.aui_utilities**
==========================================================================================================================================

This module contains some common functions used by :mod:`lib.agw.aui` to
manipulate colours, bitmaps, text, gradient shadings and custom dragging images
for :class:`~wx.lib.agw.aui.auibook.AuiNotebook` tabs.


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

================================================================================ ================================================================================
:func:`~wx.lib.agw.aui.aui_utilities.BitmapFromBits`                             A utility function that creates a masked bitmap from raw bits (XBM format).
:func:`~wx.lib.agw.aui.aui_utilities.BlendColour`                                Blends the two colour component `fg` and `bg` into one colour component, adding
:func:`~wx.lib.agw.aui.aui_utilities.ChopText`                                   Chops the input `text` if its size does not fit in `max_size`, by cutting the
:func:`~wx.lib.agw.aui.aui_utilities.Clip`                                       Clips the value in `a` based on the extremes `b` and `c`.
:func:`~wx.lib.agw.aui.aui_utilities.CopyAttributes`                             Copies pens, brushes, colours and fonts from the old tab art to the new one.
:func:`~wx.lib.agw.aui.aui_utilities.DarkenBitmap`                               Darkens the input bitmap on wxMAC using the input colour.
:func:`~wx.lib.agw.aui.aui_utilities.DrawGradientRectangle`                      Draws a gradient-shaded rectangle.
:func:`~wx.lib.agw.aui.aui_utilities.DrawMACCloseButton`                         Draws the wxMAC tab close button using :class:`GraphicsContext`.
:func:`~wx.lib.agw.aui.aui_utilities.FindFocusDescendant`                        Find a window with the focus, that is also a descendant of the given window.
:func:`~wx.lib.agw.aui.aui_utilities.GetBaseColour`                              Returns the face shading colour on push buttons/backgrounds,
:func:`~wx.lib.agw.aui.aui_utilities.GetDockingImage`                            Returns the correct name of the docking bitmap depending on the input parameters.
:func:`~wx.lib.agw.aui.aui_utilities.GetLabelSize`                               Returns the :class:`~wx.lib.agw.aui.auibar.AuiToolBar` item label size.
:func:`~wx.lib.agw.aui.aui_utilities.GetSlidingPoints`                           Returns the point at which the sliding in and out of a minimized pane begins.
:func:`~wx.lib.agw.aui.aui_utilities.IndentPressedBitmap`                        Indents the input rectangle `rect` based on the value of `button_state`.
:func:`~wx.lib.agw.aui.aui_utilities.LightColour`                                Brighten input `colour` by `percent`.
:func:`~wx.lib.agw.aui.aui_utilities.LightContrastColour`                        Creates a new, lighter colour based on the input colour `c`.
:func:`~wx.lib.agw.aui.aui_utilities.MakeDisabledBitmap`                         Convert the given image (in place) to a grayed-out version, appropriate for a 'disabled' appearance.
:func:`~wx.lib.agw.aui.aui_utilities.PaneCreateStippleBitmap`                    Creates a stipple bitmap to be used in a :class:`wx.Brush`.
:func:`~wx.lib.agw.aui.aui_utilities.RescaleScreenShot`                          Rescales a bitmap to be `thumbnail_size` pixels wide (or tall) at maximum.
:func:`~wx.lib.agw.aui.aui_utilities.StepColour`                                 Darken/lighten the input colour `c`.
:func:`~wx.lib.agw.aui.aui_utilities.TakeScreenShot`                             Takes a screenshot of the screen at given position and size (`rect`).
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
`~wx.lib.agw.aui.aui_utilities.TabDragImage`                                     This class handles the creation of a custom image in case of drag and drop of a notebook tab.
================================================================================ ================================================================================


|


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

   wx.lib.agw.aui.aui_utilities.TabDragImage





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

.. function:: BitmapFromBits(bits, w, h, colour)

   A utility function that creates a masked bitmap from raw bits (XBM format).
   
   :param string `bits`: the raw bits of the bitmap;
   :param integer `w`: the bitmap width;
   :param integer `h`: the bitmap height;
   :param wx.Colour `colour`: the colour which will replace all white pixels in the
    raw bitmap.


.. function:: BlendColour(fg, bg, alpha)

   Blends the two colour component `fg` and `bg` into one colour component, adding
   an optional alpha channel.
   
   :param wx.Colour `fg`: the first colour component;
   :param wx.Colour `bg`: the second colour component;
   :param integer `alpha`: an optional transparency value.


.. function:: ChopText(dc, text, max_size)

   Chops the input `text` if its size does not fit in `max_size`, by cutting the
   text and adding ellipsis at the end.
   
   :param `dc`: a :class:`wx.DC` device context;
   :param string `text`: the text to chop;
   :param integer `max_size`: the maximum size in which the text should fit.


.. function:: Clip(a, b, c)

   Clips the value in `a` based on the extremes `b` and `c`.
   
   :param `a`: the value to analyze;
   :param `b`: a minimum value;
   :param `c`: a maximum value.


.. function:: CopyAttributes(newArt, oldArt)

   Copies pens, brushes, colours and fonts from the old tab art to the new one.
   
   :param `newArt`: the new instance of :class:`~wx.lib.agw.aui.tabart.AuiDefaultTabArt`;
   :param `oldArt`: the old instance of :class:`~wx.lib.agw.aui.tabart.AuiDefaultTabArt`.


.. function:: DarkenBitmap(bmp, caption_colour, new_colour)

   Darkens the input bitmap on wxMAC using the input colour.
   
   :param wx.Bitmap `bmp`: the bitmap to be manipulated;
   :param wx.Colour `caption_colour`: the colour of the pane caption;
   :param wx.Colour `new_colour`: the colour used to darken the bitmap.


.. function:: DrawGradientRectangle(dc, rect, start_colour, end_colour, direction, offset=0, length=0)

   Draws a gradient-shaded rectangle.
   
   :param `dc`: a :class:`wx.DC` device context;
   :param wx.Rect `rect`: the rectangle in which to draw the gradient;
   :param wx.Colour `start_colour`: the first colour of the gradient;
   :param wx.Colour `end_colour`: the second colour of the gradient;
   :param integer `direction`: the gradient direction (horizontal or vertical).


.. function:: DrawMACCloseButton(colour, backColour=None)

   Draws the wxMAC tab close button using :class:`GraphicsContext`.
   
   :param wx.Colour `colour`: the colour to use to draw the circle;
   :param wx.Colour `backColour`: the optional background colour for the circle.


.. function:: FindFocusDescendant(ancestor)

   Find a window with the focus, that is also a descendant of the given window.
   This is used to determine the window to initially send commands to.
   
   :param wx.Window `ancestor`: the window to check for ancestry.


.. function:: GetBaseColour()

   Returns the face shading colour on push buttons/backgrounds,
   mimicking as closely as possible the platform UI colours.


.. function:: GetDockingImage(direction, useAero, center)

   Returns the correct name of the docking bitmap depending on the input parameters.
   
   :param bool `useAero`: whether :class:`~wx.lib.agw.aui.framemanager.AuiManager` is using
    Aero-style or Whidbey-style docking images or not;
   :param bool `center`: whether we are looking for the center diamond-shaped bitmap or not.


.. function:: GetLabelSize(dc, label, vertical)

   Returns the :class:`~wx.lib.agw.aui.auibar.AuiToolBar` item label size.
   
   :param string `label`: the toolbar tool label;
   :param bool `vertical`: whether the toolbar tool orientation is vertical or not.


.. function:: GetSlidingPoints(rect, size, direction)

   Returns the point at which the sliding in and out of a minimized pane begins.
   
   :param wx.Rect `rect`: the :class:`~wx.lib.agw.aui.auibar.AuiToolBar` tool screen rectangle;
   :param wx.Size `size`: the pane window size;
   :param integer `direction`: the pane docking direction.


.. function:: IndentPressedBitmap(rect, button_state)

   Indents the input rectangle `rect` based on the value of `button_state`.
   
   :param wx.Rect `rect`: the button bitmap rectangle;
   :param integer `button_state`: the button state.


.. function:: LightColour(colour, percent)

   Brighten input `colour` by `percent`.
   
   :param wx.Colour `colour`: the colour to be brightened;
   :param integer `percent`: brightening percentage.


.. function:: LightContrastColour(c)

   Creates a new, lighter colour based on the input colour `c`.
   
   :param wx.Colour `c`: the input colour to analyze.


.. function:: MakeDisabledBitmap(bitmap)

   Convert the given image (in place) to a grayed-out version, appropriate for a 'disabled' appearance.
   
   :param wx.Bitmap `bitmap`: the bitmap to gray-out.


.. function:: PaneCreateStippleBitmap()

   Creates a stipple bitmap to be used in a :class:`wx.Brush`.
   
   This is used to draw sash resize hints.


.. function:: RescaleScreenShot(bmp, thumbnail_size=200)

   Rescales a bitmap to be `thumbnail_size` pixels wide (or tall) at maximum.
   
   :param wx.Bitmap `bmp`: the bitmap to rescale;
   :param integer `thumbnail_size`: the maximum size of every page thumbnail.


.. function:: StepColour(c, ialpha)

   Darken/lighten the input colour `c`.
   
   :param wx.Colour `c`: a colour to darken/lighten;
   :param integer `ialpha`: a transparency value.


.. function:: TakeScreenShot(rect)

   Takes a screenshot of the screen at given position and size (`rect`).
   
   :param wx.Rect `rect`: the screen rectangle for which we want to take a screenshot.