bitmap.tex

很牛的GUI源码wxWidgets-2.8.0.zip 可在多种平台下运行.

\section{\class{wxBitmap}}\label{wxbitmap}

%\overview{Overview}{wxbitmapoverview}
%
This class encapsulates the concept of a platform-dependent bitmap,
either monochrome or colour or colour with alpha channel support.

\wxheading{Derived from}

\helpref{wxGDIObject}{wxgdiobject}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/bitmap.h>

\wxheading{Predefined objects}

Objects:

{\bf wxNullBitmap}

\wxheading{See also}

\helpref{wxBitmap overview}{wxbitmapoverview},
\helpref{supported bitmap file formats}{supportedbitmapformats},
\helpref{wxDC::Blit}{wxdcblit},
\helpref{wxIcon}{wxicon}, \helpref{wxCursor}{wxcursor}, \helpref{wxBitmap}{wxbitmap},
\helpref{wxMemoryDC}{wxmemorydc}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxBitmap::wxBitmap}\label{wxbitmapctor}

\func{}{wxBitmap}{\void}

Default constructor.

\func{}{wxBitmap}{\param{const wxBitmap\& }{bitmap}}

Copy constructor, uses \helpref{reference counting}{trefcount}.
To make a real copy, you can use:

\begin{verbatim}
    wxBitmap newBitmap = oldBitmap.GetSubBitmap(
                             wxRect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight()));
\end{verbatim}

\func{}{wxBitmap}{\param{const void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}

Creates a bitmap from the given data which is interpreted in platform-dependent
manner.

\func{}{wxBitmap}{\param{const char}{ bits[]}, \param{int}{ width}, \param{int}{ height}\\
  \param{int}{ depth = 1}}

Creates a bitmap from an array of bits.

You should only use this function for monochrome bitmaps ({\it depth} 1) in
portable programs: in this case the {\it bits} parameter should contain an XBM
image.

For other bit depths, the behaviour is platform dependent: under Windows, the
data is passed without any changes to the underlying {\tt CreateBitmap()} API.
Under other platforms, only monochrome bitmaps may be created using this
constructor and \helpref{wxImage}{wximage} should be used for creating colour
bitmaps from static data.

\func{}{wxBitmap}{\param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}

Creates a new bitmap. A depth of -1 indicates the depth of the current screen
or visual. Some platforms only support 1 for monochrome and -1 for the current
colour setting. Beginning with version 2.5.4 of wxWidgets a depth of 32 including
an alpha channel is supported under MSW, Mac and GTK+.

\func{}{wxBitmap}{\param{const char* const*}{ bits}}

Creates a bitmap from XPM data.

\func{}{wxBitmap}{\param{const wxString\& }{name}, \param{long}{ type}}

Loads a bitmap from a file or resource.

\func{}{wxBitmap}{\param{const wxImage\&}{ img}, \param{int}{ depth = -1}}

Creates bitmap object from the image. This has to be done
to actually display an image as you cannot draw an image directly on a window.
The resulting bitmap will use the provided colour depth (or that of the
current system if depth is -1) which entails that a colour reduction has
to take place.

When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube created
on program start-up to look up colors. This ensures a very fast conversion, but
the image quality won't be perfect (and could be better for photo images using more
sophisticated dithering algorithms).

On Windows, if there is a palette present (set with SetPalette), it will be used when
creating the wxBitmap (most useful in 8-bit display mode). On other platforms,
the palette is currently ignored.

\wxheading{Parameters}

\docparam{bits}{Specifies an array of pixel values.}

\docparam{width}{Specifies the width of the bitmap.}

\docparam{height}{Specifies the height of the bitmap.}

\docparam{depth}{Specifies the depth of the bitmap. If this is omitted, the display depth of the
screen is used.}

\docparam{name}{This can refer to a resource name under MS Windows, or a filename under MS Windows and X.
Its meaning is determined by the {\it type} parameter.}

\docparam{type}{May be one of the following:

\twocolwidtha{5cm}
\begin{twocollist}
\twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.}
\twocolitem{\indexit{wxBITMAP\_TYPE\_BMP\_RESOURCE}}{Load a Windows bitmap resource from the executable. Windows only.}
\twocolitem{\indexit{wxBITMAP\_TYPE\_PICT\_RESOURCE}}{Load a PICT image resource from the executable. Mac OS only.}
\twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
\twocolitem{\indexit{wxBITMAP\_TYPE\_XBM}}{Load an X bitmap file.}
\twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.}
\end{twocollist}

The validity of these flags depends on the platform and wxWidgets configuration.
If all possible wxWidgets settings are used, the Windows platform supports BMP file, BMP resource,
XPM data, and XPM. Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file.
Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file.

In addition, wxBitmap can read all formats that \helpref{wxImage}{wximage} can, which currently include
wxBITMAP\_TYPE\_JPEG, wxBITMAP\_TYPE\_TIF, wxBITMAP\_TYPE\_PNG, wxBITMAP\_TYPE\_GIF, wxBITMAP\_TYPE\_PCX,
and wxBITMAP\_TYPE\_PNM. Of course, you must have wxImage handlers loaded. }

\docparam{img}{Platform-independent wxImage object.}

\wxheading{Remarks}

The first form constructs a bitmap object with no data; an assignment or another member function such as Create
or LoadFile must be called subsequently.

The second and third forms provide copy constructors. Note that these do not copy the
bitmap data, but instead a pointer to the data, keeping a reference count. They are therefore
very efficient operations.

The fourth form constructs a bitmap from data whose type and value depends on
the value of the {\it type} argument.

The fifth form constructs a (usually monochrome) bitmap from an array of pixel values, under both
X and Windows.

The sixth form constructs a new bitmap.

The seventh form constructs a bitmap from pixmap (XPM) data, if wxWidgets has been configured
to incorporate this feature.

To use this constructor, you must first include an XPM file. For
example, assuming that the file {\tt mybitmap.xpm} contains an XPM array
of character pointers called mybitmap:

\begin{verbatim}
#include "mybitmap.xpm"

...

wxBitmap *bitmap = new wxBitmap(mybitmap);
\end{verbatim}

The eighth form constructs a bitmap from a file or resource. {\it name} can refer
to a resource name under MS Windows, or a filename under MS Windows and X.

Under Windows, {\it type} defaults to wxBITMAP\_TYPE\_BMP\_RESOURCE.
Under X, {\it type} defaults to wxBITMAP\_TYPE\_XPM.

\wxheading{See also}

\helpref{wxBitmap::LoadFile}{wxbitmaploadfile}

\pythonnote{Constructors supported by wxPython are:\par
\indented{2cm}{\begin{twocollist}
\twocolitem{{\bf wxBitmap(name, flag)}}{Loads a bitmap from a file}
\twocolitem{{\bf wxEmptyBitmap(width, height, depth = -1)}}{Creates an
empty bitmap with the given specifications}
\twocolitem{{\bf wxBitmapFromXPMData(listOfStrings)}}{Create a bitmap
from a Python list of strings whose contents are XPM data.}
\twocolitem{{\bf wxBitmapFromBits(bits, width, height,
depth=-1)}}{Create a bitmap from an array of bits contained in a
string.}
\twocolitem{{\bf wxBitmapFromImage(image, depth=-1)}}{Convert a
wxImage to a wxBitmap.}
\end{twocollist}}
}

\perlnote{Constructors supported by wxPerl are:\par
\begin{itemize}
\item{Wx::Bitmap->new( width, height, depth = -1 )}
\item{Wx::Bitmap->new( name, type )}
\item{Wx::Bitmap->new( icon )}
\item{Wx::Bitmap->newFromBits( bits, width, height, depth = 1 )}
\item{Wx::Bitmap->newFromXPM( data )}
\end{itemize}
}

\membersection{wxBitmap::\destruct{wxBitmap}}\label{wxbitmapdtor}

\func{}{\destruct{wxBitmap}}{\void}

Destructor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.

If the application omits to delete the bitmap explicitly, the bitmap will be
destroyed automatically by wxWidgets when the application exits.

Do not delete a bitmap that is selected into a memory device context.

\membersection{wxBitmap::AddHandler}\label{wxbitmapaddhandler}

\func{static void}{AddHandler}{\param{wxBitmapHandler*}{ handler}}

Adds a handler to the end of the static list of format handlers.

\docparam{handler}{A new bitmap format handler object. There is usually only one instance
of a given handler class in an application session.}

\wxheading{See also}

\helpref{wxBitmapHandler}{wxbitmaphandler}

\membersection{wxBitmap::CleanUpHandlers}\label{wxbitmapcleanuphandlers}

\func{static void}{CleanUpHandlers}{\void}

Deletes all bitmap handlers.

This function is called by wxWidgets on exit.

\membersection{wxBitmap::ConvertToImage}\label{wxbitmapconverttoimage}

\func{wxImage}{ConvertToImage}{\void}

Creates an image from a platform-dependent bitmap. This preserves
mask information so that bitmaps and images can be converted back
and forth without loss in that respect.

\membersection{wxBitmap::CopyFromIcon}\label{wxbitmapcopyfromicon}

\func{bool}{CopyFromIcon}{\param{const wxIcon\&}{ icon}}

Creates the bitmap from an icon.

\membersection{wxBitmap::Create}\label{wxbitmapcreate}

\func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}

Creates a fresh bitmap. If the final argument is omitted, the display depth of
the screen is used.

\func{virtual bool}{Create}{\param{const void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}

Creates a bitmap from the given data, which can be of arbitrary type.

\wxheading{Parameters}

\docparam{width}{The width of the bitmap in pixels.}

\docparam{height}{The height of the bitmap in pixels.}

\docparam{depth}{The depth of the bitmap in pixels. If this is -1, the screen depth is used.}

\docparam{data}{Data whose type depends on the value of {\it type}.}

\docparam{type}{A bitmap type identifier - see \helpref{wxBitmap::wxBitmap}{wxbitmapctor} for a list
of possible values.}

\wxheading{Return value}

true if the call succeeded, false otherwise.

\wxheading{Remarks}

The first form works on all platforms. The portability of the second form depends on the
type of data.

\wxheading{See also}

\helpref{wxBitmap::wxBitmap}{wxbitmapctor}

\membersection{wxBitmap::FindHandler}\label{wxbitmapfindhandler}

\func{static wxBitmapHandler*}{FindHandler}{\param{const wxString\& }{name}}

Finds the handler with the given name.

\func{static wxBitmapHandler*}{FindHandler}{\param{const wxString\& }{extension}, \param{wxBitmapType}{ bitmapType}}

Finds the handler associated with the given extension and type.

\func{static wxBitmapHandler*}{FindHandler}{\param{wxBitmapType }{bitmapType}}