path: root/lib/wx/doc/src/wxBitmap.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<!-- THIS FILE IS GENERATED DO NOT EDIT -->


<erlref>
<header>
  <copyright>
    <year>2020</year><year>2021</year>
    <holder>wxWidgets team.</holder></copyright>
  <legalnotice>Licensed under the wxWindows Free Documentation Licence, Version 3
  </legalnotice>
  <title>wxBitmap</title>
</header>
<module>wxBitmap</module>
<modulesummary>Functions for wxBitmap class</modulesummary>
<description><p>This class encapsulates the concept of a platform-dependent bitmap, either monochrome or colour or colour with alpha channel support.
      </p><p>If you need direct access the bitmap data instead going through drawing to it using <seeerl marker="wxMemoryDC"><c>wxMemoryDC</c></seeerl> you need to use the <c>wxPixelData</c> (not implemented in wx) class (either wxNativePixelData for RGB bitmaps or wxAlphaPixelData for bitmaps with an additionally alpha channel).
      </p><p>Note that many <seeerl marker="wxBitmap"><c>wxBitmap</c></seeerl> functions take a <c>type</c> parameter, which is a value of the ?wxBitmapType enumeration. The validity of those values depends however on the platform where your program is running and from the wxWidgets configuration. If all possible wxWidgets settings are used:
      </p><p>In addition, <seeerl marker="wxBitmap"><c>wxBitmap</c></seeerl> can load and save all formats that <seeerl marker="wxImage"><c>wxImage</c></seeerl> can; see <seeerl marker="wxImage"><c>wxImage</c></seeerl> for more info. Of course, you must have loaded the <seeerl marker="wxImage"><c>wxImage</c></seeerl> handlers (see ?wxInitAllImageHandlers() and <c>wxImage::AddHandler</c> (not implemented in wx)). Note that all available wxBitmapHandlers for a given wxWidgets port are automatically loaded at startup so you won't need to use <c>wxBitmap::AddHandler</c> (not implemented in wx).
      </p><p>More on the difference between <seeerl marker="wxImage"><c>wxImage</c></seeerl> and <seeerl marker="wxBitmap"><c>wxBitmap</c></seeerl>: <seeerl marker="wxImage"><c>wxImage</c></seeerl> is just a buffer of RGB bytes with an optional buffer for the alpha bytes. It is all generic, platform independent and image file format independent code. It includes generic code for scaling, resizing, clipping, and other manipulations of the image data. OTOH, <seeerl marker="wxBitmap"><c>wxBitmap</c></seeerl> is intended to be a wrapper of whatever is the native image format that is quickest/easiest to draw to a DC or to be the target of the drawing operations performed on a <seeerl marker="wxMemoryDC"><c>wxMemoryDC</c></seeerl>. By splitting the responsibilities between wxImage/wxBitmap like this then it's easier to use generic code shared by all platforms and image types for generic operations and platform specific code where performance or compatibility is needed.
      </p><p>Predefined objects (include wx.hrl): ?wxNullBitmap
      </p><p>See: <url href="https://docs.wxwidgets.org/3.1/overview_bitmap.html#overview_bitmap">Overview bitmap</url>, <url href="https://docs.wxwidgets.org/3.1/overview_bitmap.html#overview_bitmap_supportedformats">Overview bitmap</url>, <seemfa marker="wxDC#blit/6"><c>wxDC:blit/6</c></seemfa>, <seeerl marker="wxIcon"><c>wxIcon</c></seeerl>, <seeerl marker="wxCursor"><c>wxCursor</c></seeerl>, <seeerl marker="wxMemoryDC"><c>wxMemoryDC</c></seeerl>, <seeerl marker="wxImage"><c>wxImage</c></seeerl>, <c>wxPixelData</c> (not implemented in wx)
      </p>
  <p>wxWidgets docs: <url href="https://docs.wxwidgets.org/3.1/classwx_bitmap.html">wxBitmap</url></p>
  </description>
<datatypes><datatype><name name="wxBitmap"/></datatype></datatypes>

<funcs>
  <func>
    <name name="new" arity="0" clause_i="1" since=""/>
    <fsummary>Default constructor. </fsummary>
    <desc><p>Default constructor. 
      </p><p>Constructs a bitmap object with no data; an assignment or another member function such as <seemfa marker="#create/4"><c>create/4</c></seemfa> or <seemfa marker="#loadFile/3"><c>loadFile/3</c></seemfa> must be called subsequently. 
      </p></desc>
  </func>
  
  <func>
    <name name="new" arity="1" clause_i="1" since=""/>
  
    <name name="new" arity="1" clause_i="2" since=""/>
  
    <name name="new" arity="1" clause_i="3" since=""/>
    <fsummary></fsummary><desc></desc>
  </func>
  
  <func>
    <name name="new" arity="2" clause_i="1" since=""/>
  
    <name name="new" arity="2" clause_i="2" since=""/>
  
    <name name="new" arity="2" clause_i="3" since=""/>
  
    <name name="new" arity="2" clause_i="4" since=""/>
    <fsummary>Creates this bitmap object from the given image. </fsummary>
    <desc><p>Creates this bitmap object from the given image. 
      </p><p>This has to be done to actually display an image as you cannot draw an image directly on a window.
      </p><p>The resulting bitmap will use the provided colour depth (or that of the current system if depth is ?wxBITMAP_SCREEN_DEPTH) which entails that a colour reduction may take place.
      </p><p>On Windows, if there is a palette present (set with SetPalette), it will be used when creating the <seeerl marker="wxBitmap"><c>wxBitmap</c></seeerl> (most useful in 8-bit display mode). On other platforms, the palette is currently ignored.
      </p></desc>
  </func>
  
  <func>
    <name name="new" arity="3" clause_i="1" since=""/>
  
    <name name="new" arity="3" clause_i="2" since=""/>
    <fsummary>Creates a new bitmap. </fsummary>
    <desc><p>Creates a new bitmap. 
      </p><p>A depth of ?wxBITMAP_SCREEN_DEPTH indicates the depth of the current screen or visual.
      </p><p>Some platforms only support 1 for monochrome and ?wxBITMAP_SCREEN_DEPTH for the current colour setting.
      </p><p>A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.
      </p></desc>
  </func>
  
  <func>
    <name name="new" arity="4" clause_i="1" since=""/>
    <fsummary>Creates a bitmap from the given array <c>bits</c>. </fsummary>
    <desc><p>Creates a bitmap from the given array <c>bits</c>. 
      </p><p>You should only use this function for monochrome bitmaps (depth 1) in portable programs: in this case the bits parameter should contain an XBM image.
      </p><p>For other bit depths, the behaviour is platform dependent: under Windows, the data is passed without any changes to the underlying CreateBitmap() API. Under other platforms, only monochrome bitmaps may be created using this constructor and <seeerl marker="wxImage"><c>wxImage</c></seeerl> should be used for creating colour bitmaps from static data.
      </p></desc>
  </func>
  
  <func>
    <name name="destroy" arity="1" clause_i="1" since=""/>
    <fsummary>Creates bitmap corresponding to the given cursor. </fsummary>
    <desc><p>Creates bitmap corresponding to the given cursor. 
      </p><p>This can be useful to display a cursor as it cannot be drawn directly on a window.
      </p><p>This constructor only exists in wxMSW and wxGTK (where it is implemented for GTK+ 2.8 or later) only.
      </p><p>Since: 3.1.0 Destructor. See overview_refcount_destruct for more info.
      </p><p> If the application omits to delete the bitmap explicitly, the bitmap will be destroyed automatically by wxWidgets when the application exits.
      </p><p>Warning: Do not delete a bitmap that is selected into a memory device context. 
      </p></desc>
  </func>
  
  <func>
    <name name="convertToImage" arity="1" clause_i="1" since=""/>
    <fsummary>Creates an image from a platform-dependent bitmap. </fsummary>
    <desc><p>Creates an image from a platform-dependent bitmap. 
      </p><p>This preserves mask information so that bitmaps and images can be converted back and forth without loss in that respect. 
      </p></desc>
  </func>
  
  <func>
    <name name="copyFromIcon" arity="2" clause_i="1" since=""/>
    <fsummary>Creates the bitmap from an icon. </fsummary>
    <desc><p>Creates the bitmap from an icon. 
      </p></desc>
  </func>
  
  <func>
    <name name="create" arity="2" clause_i="1" since=""/>
    <fsummary>See: <c>create/3</c></fsummary>
  </func>
  
  <func>
    <name name="create" arity="3" clause_i="1" since=""/>
  
    <name name="create" arity="3" clause_i="2" since=""/>
    <fsummary>This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. </fsummary>
    <desc><p>This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. 
      </p></desc>
  </func>
  
  <func>
    <name name="create" arity="4" clause_i="1" since=""/>
  
    <name name="create" arity="4" clause_i="2" since=""/>
    <fsummary>Create a bitmap compatible with the given DC, inheriting its magnification factor. </fsummary>
    <desc><p>Create a bitmap compatible with the given DC, inheriting its magnification factor. 
      </p><p>Return: true if the creation was successful.
      </p><p>Since: 3.1.0 
      </p></desc>
  </func>
  
  <func>
    <name name="getDepth" arity="1" clause_i="1" since=""/>
    <fsummary>Gets the colour depth of the bitmap. </fsummary>
    <desc><p>Gets the colour depth of the bitmap. 
      </p><p>A value of 1 indicates a monochrome bitmap. 
      </p></desc>
  </func>
  
  <func>
    <name name="getHeight" arity="1" clause_i="1" since=""/>
    <fsummary>Gets the height of the bitmap in pixels. </fsummary>
    <desc><p>Gets the height of the bitmap in pixels. 
      </p><p>See: <seemfa marker="#getWidth/1"><c>getWidth/1</c></seemfa>, <c>GetSize()</c> (not implemented in wx)
      </p></desc>
  </func>
  
  <func>
    <name name="getPalette" arity="1" clause_i="1" since=""/>
    <fsummary>Gets the associated palette (if any) which may have been loaded from a file or set for the bitmap. </fsummary>
    <desc><p>Gets the associated palette (if any) which may have been loaded from a file or set for the bitmap. 
      </p><p>See: <seeerl marker="wxPalette"><c>wxPalette</c></seeerl>
      </p></desc>
  </func>
  
  <func>
    <name name="getMask" arity="1" clause_i="1" since=""/>
    <fsummary>Gets the associated mask (if any) which may have been loaded from a file or set for the bitmap. </fsummary>
    <desc><p>Gets the associated mask (if any) which may have been loaded from a file or set for the bitmap. 
      </p><p>See: <seemfa marker="#setMask/2"><c>setMask/2</c></seemfa>, <seeerl marker="wxMask"><c>wxMask</c></seeerl>
      </p></desc>
  </func>
  
  <func>
    <name name="getWidth" arity="1" clause_i="1" since=""/>
    <fsummary>Gets the width of the bitmap in pixels. </fsummary>
    <desc><p>Gets the width of the bitmap in pixels. 
      </p><p>See: <seemfa marker="#getHeight/1"><c>getHeight/1</c></seemfa>, <c>GetSize()</c> (not implemented in wx)
      </p></desc>
  </func>
  
  <func>
    <name name="getSubBitmap" arity="2" clause_i="1" since=""/>
    <fsummary>Returns a sub bitmap of the current one as long as the rect belongs entirely to the bitmap. </fsummary>
    <desc><p>Returns a sub bitmap of the current one as long as the rect belongs entirely to the bitmap. 
      </p><p>This function preserves bit depth and mask information. 
      </p></desc>
  </func>
  
  <func>
    <name name="loadFile" arity="2" clause_i="1" since=""/>
    <fsummary>See: <c>loadFile/3</c></fsummary>
  </func>
  
  <func>
    <name name="loadFile" arity="3" clause_i="1" since=""/>
    <fsummary>Loads a bitmap from a file or resource. </fsummary>
    <desc><p>Loads a bitmap from a file or resource. 
      </p><p>Return: true if the operation succeeded, false otherwise.
      </p><p>Remark: A palette may be associated with the bitmap if one exists (especially for colour Windows bitmaps), and if the code supports it. You can check if one has been created by using the <seemfa marker="#getPalette/1"><c>getPalette/1</c></seemfa> member.
      </p><p>See: <seemfa marker="#saveFile/4"><c>saveFile/4</c></seemfa>
      </p></desc>
  </func>
  
  <func>
    <name name="ok" arity="1" clause_i="1" since=""/>
    <fsummary>See: <c>isOk/1</c></fsummary>
    <desc><p>See: <seemfa marker="#isOk/1"><c>isOk/1</c></seemfa>.</p>
    </desc>
  </func>
  
  <func>
    <name name="isOk" arity="1" clause_i="1" since=""/>
    <fsummary>Returns true if bitmap data is present. </fsummary>
    <desc><p>Returns true if bitmap data is present. 
      </p></desc>
  </func>
  
  <func>
    <name name="saveFile" arity="3" clause_i="1" since=""/>
    <fsummary>See: <c>saveFile/4</c></fsummary>
  </func>
  
  <func>
    <name name="saveFile" arity="4" clause_i="1" since=""/>
    <fsummary>Saves a bitmap in the named file. </fsummary>
    <desc><p>Saves a bitmap in the named file. 
      </p><p>Return: true if the operation succeeded, false otherwise.
      </p><p>Remark: Depending on how wxWidgets has been configured, not all formats may be available.
      </p><p>See: <seemfa marker="#loadFile/3"><c>loadFile/3</c></seemfa>
      </p></desc>
  </func>
  
  <func>
    <name name="setDepth" arity="2" clause_i="1" since=""/>
    <fsummary/>
    <desc><p>Deprecated: This function is deprecated since version 3.1.2, dimensions and depth can only be set at construction time.
      
      </p><p>Sets the depth member (does not affect the bitmap data).
      </p></desc>
  </func>
  
  <func>
    <name name="setHeight" arity="2" clause_i="1" since=""/>
    <fsummary/>
    <desc><p>Deprecated: This function is deprecated since version 3.1.2, dimensions and depth can only be set at construction time.
      
      </p><p>Sets the height member (does not affect the bitmap data).
      </p></desc>
  </func>
  
  <func>
    <name name="setMask" arity="2" clause_i="1" since=""/>
    <fsummary>Sets the mask for this bitmap. </fsummary>
    <desc><p>Sets the mask for this bitmap. 
      </p><p>Remark: The bitmap object owns the mask once this has been called.
      </p><p>Note: A mask can be set also for bitmap with an alpha channel but doing so under wxMSW is not recommended because performance of drawing such bitmap is not very good.
      </p><p>See: <seemfa marker="#getMask/1"><c>getMask/1</c></seemfa>, <seeerl marker="wxMask"><c>wxMask</c></seeerl>
      </p></desc>
  </func>
  
  <func>
    <name name="setPalette" arity="2" clause_i="1" since=""/>
    <fsummary>Sets the associated palette. </fsummary>
    <desc><p>Sets the associated palette. 
      </p><p>(Not implemented under GTK+).
      </p><p>See: <seeerl marker="wxPalette"><c>wxPalette</c></seeerl>
      </p></desc>
  </func>
  
  <func>
    <name name="setWidth" arity="2" clause_i="1" since=""/>
    <fsummary/>
    <desc><p>Deprecated: This function is deprecated since version 3.1.2, dimensions and depth can only be set at construction time.
      
      </p><p>Sets the width member (does not affect the bitmap data).
      </p></desc>
  </func>
  </funcs>
</erlref>