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



.. _wx.Icon:

==========================================================================================================================================
|phoenix_title|  **wx.Icon**
==========================================================================================================================================

An icon is a small rectangular bitmap usually used for denoting a minimized application.          

It differs from a :ref:`wx.Bitmap`  in always having a mask associated with it for transparent drawing. On some platforms, icons and bitmaps are implemented identically, since there is no real distinction between a :ref:`wx.Bitmap`  with a mask and an icon; and there is no specific icon format on some platforms (X-based applications usually standardize on XPMs for small bitmaps and icons). However, some platforms (such as Windows) make the distinction, so a separate class is provided. 







         



.. note:: 

   It is usually desirable to associate a pertinent icon with a frame. Icons can also be used for other purposes, for example with :ref:`wx.TreeCtrl`  and :ref:`wx.ListCtrl`. Icons have different formats on different platforms therefore separate icons will usually be created for the different environments. Platform-specific methods for creating a :ref:`wx.Icon`  structure are catered for, and this is an occasion where conditional compilation will probably be required. Note that a new icon must be created for every time the icon is to be used for a new window. In Windows, the icon will not be reloaded if it has already been used. An icon allocated to a frame will be deleted when the frame is deleted. For more information please see :ref:`Bitmaps and Icons <bitmaps and icons>`.  







.. seealso:: :ref:`Bitmaps and Icons <bitmaps and icons>`, :ref:`Supported Bitmap File Formats <supported bitmap file formats>`, :ref:`wx.IconBundle`, :meth:`wx.DC.DrawIcon` , :ref:`wx.Cursor`    







|

|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>Icon</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.Icon_inheritance.png" alt="Inheritance diagram of Icon" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Icon.html" title="wx.Icon" alt="" coords="25,160,97,189"/> <area shape="rect" id="node2" href="wx.GDIObject.html" title="wx.GDIObject" alt="" coords="5,83,116,112"/> <area shape="rect" id="node3" href="wx.Object.html" title="wx.Object" alt="" coords="17,5,104,35"/> </map> 
   </p>
   </div>

|


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

================================================================================ ================================================================================
:meth:`~wx.Icon.__init__`                                                        Default constructor.
:meth:`~wx.Icon.CopyFromBitmap`                                                  Copies `bmp`  bitmap to this icon.
:meth:`~wx.Icon.CreateFromHICON`                                                 MSW-only method to create a wx.Icon from a native icon handle.
:meth:`~wx.Icon.GetDepth`                                                        Gets the colour depth of the icon.
:meth:`~wx.Icon.GetHandle`                                                       
:meth:`~wx.Icon.GetHeight`                                                       Gets the height of the icon in physical pixels.
:meth:`~wx.Icon.GetLogicalHeight`                                                Gets the height of the icon in logical pixels.
:meth:`~wx.Icon.GetLogicalSize`                                                  Gets the size of the icon in logical pixels.
:meth:`~wx.Icon.GetLogicalWidth`                                                 Gets the width of the icon in logical pixels.
:meth:`~wx.Icon.GetScaleFactor`                                                  Gets the scale factor of this icon.
:meth:`~wx.Icon.GetSize`                                                         Gets the size of the icon in physical pixels.
:meth:`~wx.Icon.GetWidth`                                                        Gets the width of the icon in physical pixels.
:meth:`~wx.Icon.IsOk`                                                            Returns ``True`` if icon data is present.
:meth:`~wx.Icon.LoadFile`                                                        Loads an icon from a file or resource.
:meth:`~wx.Icon.SetDepth`                                                        
:meth:`~wx.Icon.SetHandle`                                                       
:meth:`~wx.Icon.SetHeight`                                                       
:meth:`~wx.Icon.SetWidth`                                                        
:meth:`~wx.Icon.__bool__`                                                        
:meth:`~wx.Icon.__nonzero__`                                                     
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.Icon.Depth`                                                           See :meth:`~wx.Icon.GetDepth` and :meth:`~wx.Icon.SetDepth`
:attr:`~wx.Icon.Handle`                                                          See :meth:`~wx.Icon.GetHandle` and :meth:`~wx.Icon.SetHandle`
:attr:`~wx.Icon.Height`                                                          See :meth:`~wx.Icon.GetHeight` and :meth:`~wx.Icon.SetHeight`
:attr:`~wx.Icon.LogicalHeight`                                                   See :meth:`~wx.Icon.GetLogicalHeight`
:attr:`~wx.Icon.LogicalSize`                                                     See :meth:`~wx.Icon.GetLogicalSize`
:attr:`~wx.Icon.LogicalWidth`                                                    See :meth:`~wx.Icon.GetLogicalWidth`
:attr:`~wx.Icon.ScaleFactor`                                                     See :meth:`~wx.Icon.GetScaleFactor`
:attr:`~wx.Icon.Size`                                                            See :meth:`~wx.Icon.GetSize`
:attr:`~wx.Icon.Width`                                                           See :meth:`~wx.Icon.GetWidth` and :meth:`~wx.Icon.SetWidth`
================================================================================ ================================================================================


|


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


.. class:: wx.Icon(GDIObject)

   **Possible constructors**::

       Icon()
       
       Icon(icon)
       
       Icon(name, type=BITMAP_TYPE_ANY, desiredWidth=-1, desiredHeight=-1)
       
       Icon(loc)
       
       Icon(bmp)
       
   
   An icon is a small rectangular bitmap usually used for denoting a
   minimized application.



   .. method:: __init__(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self)`
      
      Default constructor.                  
      
      Constructs an icon object with no data; an assignment or another member function such as :meth:`LoadFile`   must be called subsequently.                   
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, icon)`
      
      Copy constructor.                  
      
      
      :param `icon`: 
      :type `icon`: wx.Icon
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, name, type=BITMAP_TYPE_ANY, desiredWidth=-1, desiredHeight=-1)`
      
      Loads an icon from a file or resource.                  
      
      
      
      
      :param `name`: This can refer to a resource name or a filename under MS Windows and X. Its meaning is determined by the  `type`  parameter.   
      :type `name`: string
      :param `type`: May be one of the :ref:`wx.BitmapType`  values and indicates which type of bitmap should be loaded. See the note in the class detailed description. Note that the ``ICON_DEFAULT_TYPE`` constant has different value under different wxWidgets ports. See the :ref:`icon.h`  header for the value it takes for a specific port.   
      :type `type`: wx.BitmapType
      :param `desiredWidth`: Specifies the desired width of the icon. This parameter only has an effect in Windows where icon resources can contain several icons of different sizes.   
      :type `desiredWidth`: int
      :param `desiredHeight`: Specifies the desired height of the icon. This parameter only has an effect in Windows where icon resources can contain several icons of different sizes.  
      :type `desiredHeight`: int
      
      
      
      
      
      
      
      
      
      
                        
      
      
      
      .. seealso:: :meth:`LoadFile`     
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, loc)`
      
      Loads an icon from the specified location.                  
      
      
      :param `loc`: 
      :type `loc`: wx.IconLocation
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, bmp)`
      
      Construct an Icon from a Bitmap.  
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: CopyFromBitmap(self, bmp)

      Copies `bmp`  bitmap to this icon.                  

      Under MS Windows the bitmap must have mask colour set. 

                


      :param `bmp`: 
      :type `bmp`: wx.Bitmap






      .. seealso:: :meth:`LoadFile`     








   .. method:: CreateFromHICON(self, hicon)

      MSW-only method to create a wx.Icon from a native icon handle. 

      :rtype: `bool`








   .. method:: GetDepth(self)

      Gets the colour depth of the icon.                  

      A value of 1 indicates a monochrome icon.                  

      :rtype: `int`








   .. method:: GetHandle(self)



      :rtype: `long`








   .. method:: GetHeight(self)

      Gets the height of the icon in physical pixels.                  

                

      :rtype: `int`







      .. seealso:: :meth:`GetWidth` , :meth:`GetLogicalHeight`     








   .. method:: GetLogicalHeight(self)

      Gets the height of the icon in logical pixels.                  

      See :meth:`wx.Bitmap.GetLogicalHeight` . 

                

      :rtype: `float`







      .. versionadded:: 4.1/wxWidgets-3.1.6  
     








   .. method:: GetLogicalSize(self)

      Gets the size of the icon in logical pixels.                  

      See :meth:`wx.Bitmap.GetLogicalSize` . 

                

      :rtype: :ref:`wx.Size`







      .. versionadded:: 4.1/wxWidgets-3.1.6  
     








   .. method:: GetLogicalWidth(self)

      Gets the width of the icon in logical pixels.                  

      See :meth:`wx.Bitmap.GetLogicalWidth` . 

                

      :rtype: `float`







      .. versionadded:: 4.1/wxWidgets-3.1.6  
     








   .. method:: GetScaleFactor(self)

      Gets the scale factor of this icon.                  

      See :meth:`wx.Bitmap.GetScaleFactor` . 

                

      :rtype: `float`







      .. versionadded:: 4.1/wxWidgets-3.1.6  
     








   .. method:: GetSize(self)

      Gets the size of the icon in physical pixels.                  

                

      :rtype: :ref:`wx.Size`







      .. seealso:: :meth:`GetLogicalSize`     








   .. method:: GetWidth(self)

      Gets the width of the icon in physical pixels.                  

                

      :rtype: `int`







      .. seealso:: :meth:`GetHeight` , :meth:`GetLogicalWidth`     








   .. method:: IsOk(self)

      Returns ``True`` if icon data is present.                  

      :rtype: `bool`








   .. method:: LoadFile(self, name, type=BITMAP_TYPE_ANY, desiredWidth=-1, desiredHeight=-1)

      Loads an icon from a file or resource.                  




      :param `name`: Either a filename or a Windows resource name. The meaning of name is determined by the  `type`  parameter.   
      :type `name`: string
      :param `type`: One of the :ref:`wx.BitmapType`  values; see the note in the class detailed description. Note that the ``ICON_DEFAULT_TYPE`` constant has different value under different wxWidgets ports. See the :ref:`icon.h`  header for the value it takes for a specific port.   
      :type `type`: wx.BitmapType
      :param `desiredWidth`: Specifies the desired width of the icon. This parameter only has an effect in Windows where icon resources can contain several icons of different sizes.   
      :type `desiredWidth`: int
      :param `desiredHeight`: Specifies the desired height of the icon. This parameter only has an effect in Windows where icon resources can contain several icons of different sizes.  
      :type `desiredHeight`: int












      :rtype: `bool`



                  



      :returns: 

         ``True`` if the operation succeeded, ``False`` otherwise.   








   .. method:: SetDepth(self, depth)





      Sets the depth member (does not affect the icon data). 




      :param `depth`: Icon depth.   
      :type `depth`: int




                  



      .. wxdeprecated:: 
         This function is deprecated since version 3.1.2, dimensions and depth can only be set at construction time.   








   .. method:: SetHandle(self, handle)






   .. method:: SetHeight(self, height)





      Sets the height member (does not affect the icon data). 




      :param `height`: Icon height in pixels.   
      :type `height`: int




                  



      .. wxdeprecated:: 
         This function is deprecated since version 3.1.2, dimensions and depth can only be set at construction time.   








   .. method:: SetWidth(self, width)





      Sets the width member (does not affect the icon data). 




      :param `width`: Icon width in pixels.   
      :type `width`: int




                  



      .. wxdeprecated:: 
         This function is deprecated since version 3.1.2, dimensions and depth can only be set at construction time.   








   .. method:: __bool__(self)



      :rtype: `int`








   .. method:: __nonzero__(self)



      :rtype: `int`








   .. attribute:: Depth

      See :meth:`~wx.Icon.GetDepth` and :meth:`~wx.Icon.SetDepth`


   .. attribute:: Handle

      See :meth:`~wx.Icon.GetHandle` and :meth:`~wx.Icon.SetHandle`


   .. attribute:: Height

      See :meth:`~wx.Icon.GetHeight` and :meth:`~wx.Icon.SetHeight`


   .. attribute:: LogicalHeight

      See :meth:`~wx.Icon.GetLogicalHeight`


   .. attribute:: LogicalSize

      See :meth:`~wx.Icon.GetLogicalSize`


   .. attribute:: LogicalWidth

      See :meth:`~wx.Icon.GetLogicalWidth`


   .. attribute:: ScaleFactor

      See :meth:`~wx.Icon.GetScaleFactor`


   .. attribute:: Size

      See :meth:`~wx.Icon.GetSize`


   .. attribute:: Width

      See :meth:`~wx.Icon.GetWidth` and :meth:`~wx.Icon.SetWidth`

