Ref counting overview.

[wxWidgets.git] / docs / latex / wx / bitmap.tex

diff --git a/docs/latex/wx/bitmap.tex b/docs/latex/wx/bitmap.tex
index 3fde13a915e36e7ac21b765491a6b3f8c08d2524..57eb5c05d8385fab5d619faf5bbf993c5fcd8a7f 100644 (file)
--- a/docs/latex/wx/bitmap.tex
+++ b/docs/latex/wx/bitmap.tex
@@ -3,14 +3,14 @@
 %\overview{Overview}{wxbitmapoverview}
 %
 This class encapsulates the concept of a platform-dependent bitmap,
-either monochrome or colour.
+either monochrome or colour or colour with alpha channel support.
 
 \wxheading{Derived from}
 
 \helpref{wxGDIObject}{wxgdiobject}\\
 \helpref{wxObject}{wxobject}
 
-\wxheading{Include file}
+\wxheading{Include files}
 
 <wx/bitmap.h>
 
@@ -30,7 +30,7 @@ Objects:
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
-\membersection{wxBitmap::wxBitmap}\label{wxbitmapconstr}
+\membersection{wxBitmap::wxBitmap}\label{wxbitmapctor}
 
 \func{}{wxBitmap}{\void}
 
@@ -38,9 +38,15 @@ Default constructor.
 
 \func{}{wxBitmap}{\param{const wxBitmap\& }{bitmap}}
 
-Copy constructor.
+Copy constructor, uses \helpref{reference counting}{trefcount}.
+To make a real copy, you can use:
 
-\func{}{wxBitmap}{\param{void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
+\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.
@@ -64,9 +70,10 @@ bitmaps from static data.
 
 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.
+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**}{ bits}}
+\func{}{wxBitmap}{\param{const char* const*}{ bits}}
 
 Creates a bitmap from XPM data.
 
@@ -110,11 +117,11 @@ Its meaning is determined by the {\it type} parameter.}
 \twocolwidtha{5cm}
 \begin{twocollist}
 \twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.}
-\twocolitem{\indexit{wxBITMAP\_TYPE\_BMP\_RESOURCE}}{Load a Windows bitmap from the resource database.}
+\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.}
-\twocolitem{\indexit{wxBITMAP\_TYPE\_RESOURCE}}{Load a Windows resource name.}
 \end{twocollist}
 
 The validity of these flags depends on the platform and wxWidgets configuration.
@@ -195,7 +202,7 @@ wxImage to a wxBitmap.}
 \end{itemize}
 }
 
-\membersection{wxBitmap::\destruct{wxBitmap}}
+\membersection{wxBitmap::\destruct{wxBitmap}}\label{wxbitmapdtor}
 
 \func{}{\destruct{wxBitmap}}{\void}
 
@@ -222,7 +229,7 @@ of a given handler class in an application session.}
 
 \helpref{wxBitmapHandler}{wxbitmaphandler}
 
-\membersection{wxBitmap::CleanUpHandlers}
+\membersection{wxBitmap::CleanUpHandlers}\label{wxbitmapcleanuphandlers}
 
 \func{static void}{CleanUpHandlers}{\void}
 
@@ -251,7 +258,7 @@ Creates the bitmap from an icon.
 Creates a fresh bitmap. If the final argument is omitted, the display depth of
 the screen is used.
 
-\func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
+\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.
 
@@ -265,7 +272,7 @@ Creates a bitmap from the given data, which can be of arbitrary type.
 
 \docparam{data}{Data whose type depends on the value of {\it type}.}
 
-\docparam{type}{A bitmap type identifier - see \helpref{wxBitmap::wxBitmap}{wxbitmapconstr} for a list
+\docparam{type}{A bitmap type identifier - see \helpref{wxBitmap::wxBitmap}{wxbitmapctor} for a list
 of possible values.}
 
 \wxheading{Return value}
@@ -279,19 +286,19 @@ type of data.
 
 \wxheading{See also}
 
-\helpref{wxBitmap::wxBitmap}{wxbitmapconstr}
+\helpref{wxBitmap::wxBitmap}{wxbitmapctor}
 
-\membersection{wxBitmap::FindHandler}
+\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{long}{ bitmapType}}
+\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{long }{bitmapType}}
+\func{static wxBitmapHandler*}{FindHandler}{\param{wxBitmapType }{bitmapType}}
 
 Finds the handler associated with the given bitmap type.
 
@@ -309,14 +316,14 @@ A pointer to the handler if found, NULL otherwise.
 
 \helpref{wxBitmapHandler}{wxbitmaphandler}
 
-\membersection{wxBitmap::GetDepth}
+\membersection{wxBitmap::GetDepth}\label{wxbitmapgetdepth}
 
 \constfunc{int}{GetDepth}{\void}
 
 Gets the colour depth of the bitmap. A value of 1 indicates a
 monochrome bitmap.
 
-\membersection{wxBitmap::GetHandlers}
+\membersection{wxBitmap::GetHandlers}\label{wxbitmapgethandlers}
 
 \func{static wxList\&}{GetHandlers}{\void}
 
@@ -371,7 +378,7 @@ Gets the width of the bitmap in pixels.
 Returns a sub bitmap of the current one as long as the rect belongs entirely to
 the bitmap. This function preserves bit depth and mask information.
 
-\membersection{wxBitmap::InitStandardHandlers}
+\membersection{wxBitmap::InitStandardHandlers}\label{wxbitmapinitstandardhandlers}
 
 \func{static void}{InitStandardHandlers}{\void}
 
@@ -384,7 +391,7 @@ This function is called by wxWidgets on startup.
 
 \helpref{wxBitmapHandler}{wxbitmaphandler}
 
-\membersection{wxBitmap::InsertHandler}
+\membersection{wxBitmap::InsertHandler}\label{wxbitmapinserthandler}
 
 \func{static void}{InsertHandler}{\param{wxBitmapHandler*}{ handler}}
 
@@ -399,7 +406,7 @@ of a given handler class in an application session.}
 
 \membersection{wxBitmap::LoadFile}\label{wxbitmaploadfile}
 
-\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type}}
+\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{wxBitmapType}{ type}}
 
 Loads a bitmap from a file or resource.
 
@@ -413,7 +420,8 @@ The meaning of {\it name} is determined by the {\it type} parameter.}
 \twocolwidtha{5cm}
 \begin{twocollist}
 \twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.}
-\twocolitem{{\bf wxBITMAP\_TYPE\_BMP\_RESOURCE}}{Load a Windows bitmap from the resource database.}
+\twocolitem{{\bf wxBITMAP\_TYPE\_BMP\_RESOURCE}}{Load a Windows bitmap resource from the executable.}
+\twocolitem{{\bf wxBITMAP\_TYPE\_PICT\_RESOURCE}}{Load a PICT image resource from the executable. Mac OS only.}
 \twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
 \twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Load an X bitmap file.}
 \twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.}
@@ -439,13 +447,13 @@ if one has been created by using the \helpref{GetPalette}{wxbitmapgetpalette} me
 
 \helpref{wxBitmap::SaveFile}{wxbitmapsavefile}
 
-\membersection{wxBitmap::Ok}\label{wxbitmapok}
+\membersection{wxBitmap::IsOk}\label{wxbitmapisok}
 
-\constfunc{bool}{Ok}{\void}
+\constfunc{bool}{IsOk}{\void}
 
 Returns true if bitmap data is present.
 
-\membersection{wxBitmap::RemoveHandler}
+\membersection{wxBitmap::RemoveHandler}\label{wxbitmapremovehandler}
 
 \func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}
 
@@ -464,7 +472,7 @@ true if the handler was found and removed, false otherwise.
 
 \membersection{wxBitmap::SaveFile}\label{wxbitmapsavefile}
 
-\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}, \param{wxPalette* }{palette = NULL}}
+\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{wxBitmapType}{ type}, \param{wxPalette* }{palette = NULL}}
 
 Saves a bitmap in the named file.
 
@@ -539,7 +547,7 @@ The bitmap object owns the mask once this has been called.
 \helpref{wxBitmap::GetMask}{wxbitmapgetmask}, \helpref{wxMask}{wxmask}
 
 %% VZ: this function is an implementation detail and shouldn't be documented
-%%\membersection{wxBitmap::SetOk}
+%%\membersection{wxBitmap::SetOk}\label{wxbitmapsetok}
 %%
 %%\func{void}{SetOk}{\param{int }{isOk}}
 %%
@@ -553,7 +561,7 @@ The bitmap object owns the mask once this has been called.
 
 \func{void}{SetPalette}{\param{const wxPalette\& }{palette}}
 
-Sets the associated palette.
+Sets the associated palette. (Not implemented under GTK+).
 
 \wxheading{Parameters}
 
@@ -563,7 +571,7 @@ Sets the associated palette.
 
 \helpref{wxPalette}{wxpalette}
 
-\membersection{wxBitmap::SetWidth}
+\membersection{wxBitmap::SetWidth}\label{wxbitmapsetwidth}
 
 \func{void}{SetWidth}{\param{int }{width}}
 
@@ -573,13 +581,11 @@ Sets the width member (does not affect the bitmap data).
 
 \docparam{width}{Bitmap width in pixels.}
 
-\membersection{wxBitmap::operator $=$}
+\membersection{wxBitmap::operator $=$}\label{wxbitmapassign}
 
 \func{wxBitmap\& }{operator $=$}{\param{const wxBitmap\& }{bitmap}}
 
-Assignment operator. This operator does not copy any data, but instead
-passes a pointer to the data in {\it bitmap} and increments a reference
-counter. It is a fast operation.
+Assignment operator, using \helpref{reference counting}{trefcount}.
 
 \wxheading{Parameters}
 
@@ -589,7 +595,7 @@ counter. It is a fast operation.
 
 Returns 'this' object.
 
-\membersection{wxBitmap::operator $==$}
+\membersection{wxBitmap::operator $==$}\label{wxbitmapequal}
 
 \func{bool}{operator $==$}{\param{const wxBitmap\& }{bitmap}}
 
@@ -604,7 +610,7 @@ equal (a fast test).
 
 Returns true if the bitmaps were effectively equal, false otherwise.
 
-\membersection{wxBitmap::operator $!=$}
+\membersection{wxBitmap::operator $!=$}\label{wxbitmapnotequal}
 
 \func{bool}{operator $!=$}{\param{const wxBitmap\& }{bitmap}}