Documented new menu label functions

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

diff --git a/docs/latex/wx/colour.tex b/docs/latex/wx/colour.tex
index 95b359d281af89a53dfbf6c5b1e4f556865b0cfe..0109378a5bf766ed36b5ed4301a2c9f1a4486d0c 100644 (file)
--- a/docs/latex/wx/colour.tex
+++ b/docs/latex/wx/colour.tex
@@ -1,3 +1,14 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        colour.tex
+%% Purpose:     wxColour docs
+%% Author:
+%% Modified by: Francesco Montorsi
+%% Created:
+%% RCS-ID:      $Id$
+%% Copyright:   (c) wxWidgets
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+

 \section{\class{wxColour}}\label{wxcolour}
 
 A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values,
 \section{\class{wxColour}}\label{wxcolour}
 
 A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values,


@@ -17,6 +28,10 @@ You can retrieve the current system colour settings with \helpref{wxSystemSettin
 
 <wx/colour.h>
 
 
 <wx/colour.h>
 

+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+

 \wxheading{Predefined objects}
 
 Objects:
 \wxheading{Predefined objects}
 
 Objects:


@@ -47,14 +62,13 @@ wxLIGHT\_GREY}
 
 Default constructor.
 
 
 Default constructor.
 

-\func{}{wxColour}{\param{const unsigned char}{ red}, \param{const unsigned char}{ green}, \param{const unsigned char}{ blue}}
+\func{}{wxColour}{\param{unsigned char}{ red}, \param{unsigned char}{ green}, \param{unsigned char}{ blue}, \param{unsigned char}{ alpha=wxALPHA\_OPAQUE}}

 
 

-Constructs a colour from red, green and blue values.
+Constructs a colour from red, green, blue and alpha values.

 
 \func{}{wxColour}{\param{const wxString\& }{colourNname}}
 
 
 \func{}{wxColour}{\param{const wxString\& }{colourNname}}
 

-Constructs a colour object using a colour name
-listed in {\bf wxTheColourDatabase}.
+Constructs a colour using the given string. See \helpref{Set}{wxcolourset} for more info.

 
 \func{}{wxColour}{\param{const wxColour\&}{ colour}}
 
 
 \func{}{wxColour}{\param{const wxColour\&}{ colour}}
 


@@ -68,6 +82,8 @@ Copy constructor.
 
 \docparam{blue}{The blue value.}
 
 
 \docparam{blue}{The blue value.}
 

+\docparam{alpha}{The alpha value. Alpha values range from 0 (wxALPHA\_TRANSPARENT) to 255 (wxALPHA\_OPAQUE).}
+

 \docparam{colourName}{The colour name.}
 
 \docparam{colour}{The colour to copy.}
 \docparam{colourName}{The colour name.}
 
 \docparam{colour}{The colour to copy.}


@@ -85,6 +101,13 @@ Copy constructor.
 
 
 
 
 
 

+\membersection{wxColour::Alpha}\label{wxcolouralpha}
+
+\constfunc{unsigned char}{Alpha}{\void}
+
+Returns the alpha value, on platforms where alpha is not yet supported, this always returns wxALPHA\_OPAQUE.
+
+

 \membersection{wxColour::Blue}\label{wxcolourblue}
 
 \constfunc{unsigned char}{Blue}{\void}
 \membersection{wxColour::Blue}\label{wxcolourblue}
 
 \constfunc{unsigned char}{Blue}{\void}


@@ -92,6 +115,28 @@ Copy constructor.
 Returns the blue intensity.
 
 
 Returns the blue intensity.
 
 

+\membersection{wxColour::GetAsString}\label{wxcolourgetasstring}
+
+\constfunc{wxString}{GetAsString}{\param{long}{ flags}}
+
+Converts this colour to a \helpref{wxString}{wxstring} 
+using the given {\it flags}.
+
+The supported flags are \textbf{wxC2S\_NAME}, to obtain the colour name (e.g.
+wxColour(255,0,0) -> \texttt{``red"}), \textbf{wxC2S\_CSS\_SYNTAX}, to obtain
+the colour in the \texttt{``rgb(r,g,b)"} or \texttt{``rgba(r,g,b,a)"} syntax
+(e.g. wxColour(255,0,0,85) -> \texttt{``rgba(255,0,0,0.333)"}), and 
+\textbf{wxC2S\_HTML\_SYNTAX}, to obtain the colour as  \texttt{``\#"} followed
+by 6 hexadecimal digits (e.g. wxColour(255,0,0) -> \texttt{``\#FF0000"}).
+
+This function never fails and always returns a non-empty string but asserts if
+the colour has alpha channel (i.e. is non opaque) but
+\textbf{wxC2S\_CSS\_SYNTAX} (which is the only one supporting alpha) is not
+specified in flags.
+
+\newsince{2.7.0}
+
+

 \membersection{wxColour::GetPixel}\label{wxcolourgetpixel}
 
 \constfunc{long}{GetPixel}{\void}
 \membersection{wxColour::GetPixel}\label{wxcolourgetpixel}
 
 \constfunc{long}{GetPixel}{\void}


@@ -109,9 +154,9 @@ On X, an allocated pixel value is returned.
 Returns the green intensity.
 
 
 Returns the green intensity.
 
 

-\membersection{wxColour::Ok}\label{wxcolourok}
+\membersection{wxColour::IsOk}\label{wxcolourisok}

 
 

-\constfunc{bool}{Ok}{\void}
+\constfunc{bool}{IsOk}{\void}

 
 Returns \true if the colour object is valid (the colour has been initialised with RGB values).
 
 
 Returns \true if the colour object is valid (the colour has been initialised with RGB values).
 


@@ -125,9 +170,23 @@ Returns the red intensity.
 
 \membersection{wxColour::Set}\label{wxcolourset}
 
 
 \membersection{wxColour::Set}\label{wxcolourset}
 

-\func{void}{Set}{\param{const unsigned char}{ red}, \param{const unsigned char}{ green}, \param{const unsigned char}{ blue}}
+\func{void}{Set}{\param{unsigned char}{ red}, \param{unsigned char}{ green}, \param{unsigned char}{ blue}, \param{unsigned char}{ alpha=wxALPHA\_OPAQUE}}

 
 

-Sets the RGB intensity values.
+\func{void}{Set}{\param{unsigned long}{ RGB}}
+
+\func{bool}{Set}{\param{const wxString \&}{ str}}
+
+Sets the RGB intensity values using the given values (first overload), extracting them from the packed long (second overload), using the given string (third overloard).
+
+When using third form, Set() accepts: colour names (those listed in 
+\helpref{wxTheColourDatabase}{wxcolourdatabase}), the CSS-like 
+\texttt{``rgb(r,g,b)"} or \texttt{``rgba(r,g,b,a)"} syntax (case insensitive) 
+and the HTML-like syntax (i.e. \texttt{``\#"} followed by 6 hexadecimal digits 
+for red, green, blue components).
+
+Returns \true if the conversion was successful, \false otherwise.
+
+\newsince{2.7.0}

 
 
 \membersection{wxColour::operator $=$}\label{wxcolourassign}
 
 
 \membersection{wxColour::operator $=$}\label{wxcolourassign}


@@ -149,14 +208,14 @@ Assignment operator, using a colour name to be found in the colour database.
 
 \func{bool}{operator $==$}{\param{const wxColour\&}{ colour}}
 
 
 \func{bool}{operator $==$}{\param{const wxColour\&}{ colour}}
 

-Tests the equality of two colours by comparing individual red, green blue colours.
+Tests the equality of two colours by comparing individual red, green, blue colours and alpha values.

 
 
 \membersection{wxColour::operator $!=$}\label{wxcolourinequality}
 
 \func{bool}{operator $!=$}{\param{const wxColour\&}{ colour}}
 
 
 
 \membersection{wxColour::operator $!=$}\label{wxcolourinequality}
 
 \func{bool}{operator $!=$}{\param{const wxColour\&}{ colour}}
 

-Tests the inequality of two colours by comparing individual red, green blue colours.
+Tests the inequality of two colours by comparing individual red, green, blue colours and alpha values.

 
 \section{\class{wxColourData}}\label{wxcolourdata}
 
 
 \section{\class{wxColourData}}\label{wxcolourdata}
 


@@ -170,6 +229,10 @@ This class holds a variety of information related to colour dialogs.
 
 <wx/cmndata.h>
 
 
 <wx/cmndata.h>
 

+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+

 \wxheading{See also}
 
 \helpref{wxColour}{wxcolour}, \helpref{wxColourDialog}{wxcolourdialog}, \helpref{wxColourDialog overview}{wxcolourdialogoverview}
 \wxheading{See also}
 
 \helpref{wxColour}{wxcolour}, \helpref{wxColourDialog}{wxcolourdialog}, \helpref{wxColourDialog overview}{wxcolourdialogoverview}


@@ -177,15 +240,16 @@ This class holds a variety of information related to colour dialogs.
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 

-\membersection{wxColourData::wxColourData}\label{wxcolourdataconstr}
+\membersection{wxColourData::wxColourData}\label{wxcolourdatactor}

 
 \func{}{wxColourData}{\void}
 
 
 \func{}{wxColourData}{\void}
 

-Constructor. Initializes the custom colours to white, the {\it data colour} setting
+Constructor. Initializes the custom colours to {\tt wxNullColour},
+the {\it data colour} setting

 to black, and the {\it choose full} setting to true.
 
 
 to black, and the {\it choose full} setting to true.
 
 

-\membersection{wxColourData::\destruct{wxColourData}}
+\membersection{wxColourData::\destruct{wxColourData}}\label{wxcolourdatadtor}

 
 \func{}{\destruct{wxColourData}}{\void}
 
 
 \func{}{\destruct{wxColourData}}{\void}
 


@@ -197,7 +261,9 @@ Destructor.
 \constfunc{bool}{GetChooseFull}{\void}
 
 Under Windows, determines whether the Windows colour dialog will display the full dialog
 \constfunc{bool}{GetChooseFull}{\void}
 
 Under Windows, determines whether the Windows colour dialog will display the full dialog

-with custom colour selection controls. Has no meaning under other platforms.
+with custom colour selection controls. Under PalmOS, determines whether colour dialog
+will display full rgb colour picker or only available palette indexer.
+Has no meaning under other platforms.

 
 The default value is true.
 
 
 The default value is true.
 


@@ -218,7 +284,7 @@ The default colour is black.
 Gets the {\it i}th custom colour associated with the colour dialog. {\it i} should
 be an integer between 0 and 15.
 
 Gets the {\it i}th custom colour associated with the colour dialog. {\it i} should
 be an integer between 0 and 15.
 

-The default custom colours are all white.
+The default custom colours are invalid colours.

 
 
 \membersection{wxColourData::SetChooseFull}\label{wxcolourdatasetchoosefull}
 
 
 \membersection{wxColourData::SetChooseFull}\label{wxcolourdatasetchoosefull}


@@ -247,7 +313,7 @@ The default colour is black.
 Sets the {\it i}th custom colour for the colour dialog. {\it i} should
 be an integer between 0 and 15.
 
 Sets the {\it i}th custom colour for the colour dialog. {\it i} should
 be an integer between 0 and 15.
 

-The default custom colours are all white.
+The default custom colours are invalid colours.

 
 
 \membersection{wxColourData::operator $=$}\label{wxcolourdataassign}
 
 
 \membersection{wxColourData::operator $=$}\label{wxcolourdataassign}


@@ -263,12 +329,12 @@ Assignment operator for the colour data.
 
 wxWidgets maintains a database of standard RGB colours for a predefined
 set of named colours (such as ``BLACK'', ``LIGHT GREY''). The
 
 wxWidgets maintains a database of standard RGB colours for a predefined
 set of named colours (such as ``BLACK'', ``LIGHT GREY''). The

-application may add to this set if desired by using 
+application may add to this set if desired by using

 \helpref{AddColour}{wxcolourdatabaseaddcolour} and may use it to look up
 colours by names using \helpref{Find}{wxcolourdatabasefind} or find the names
 for the standard colour suing \helpref{FindName}{wxcolourdatabasefindname}.
 
 \helpref{AddColour}{wxcolourdatabaseaddcolour} and may use it to look up
 colours by names using \helpref{Find}{wxcolourdatabasefind} or find the names
 for the standard colour suing \helpref{FindName}{wxcolourdatabasefindname}.
 

-There is one predefined instance of this class called 
+There is one predefined instance of this class called

 {\bf wxTheColourDatabase}.
 
 \wxheading{Derived from}
 {\bf wxTheColourDatabase}.
 
 \wxheading{Derived from}


@@ -279,6 +345,10 @@ None
 
 <wx/gdicmn.h>
 
 
 <wx/gdicmn.h>
 

+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+

 \wxheading{Remarks}
 
 The standard database contains at least the following colours:
 \wxheading{Remarks}
 
 The standard database contains at least the following colours:


@@ -325,25 +395,13 @@ removed in the next wxWidgets version, please don't use it.
 
 \membersection{wxColourDatabase::Find}\label{wxcolourdatabasefind}
 
 
 \membersection{wxColourDatabase::Find}\label{wxcolourdatabasefind}
 

-\func{wxColour}{FindColour}{\param{const wxString\& }{colourName}}
+\func{wxColour}{Find}{\param{const wxString\& }{colourName}}

 
 Finds a colour given the name. Returns an invalid colour object (that is, such
 
 Finds a colour given the name. Returns an invalid colour object (that is, such

-that its \helpref{Ok()}{wxcolourok} method returns \false) if the colour wasn't
+that its \helpref{Ok()}{wxcolourisok} method returns \false) if the colour wasn't

 found in the database.
 
 
 found in the database.
 
 

-\membersection{wxColourDatabase::FindColour}\label{wxcolourdatabasefindcolour}
-
-\func{wxColour*}{FindColour}{\param{const wxString\& }{colourName}}
-
-Finds a colour given the name. Returns \tt{NULL} if not found or a pointer which
-must be deleted by the caller otherwise.
-
-Please note that this method is deprecated and will be removed in the next
-wxWidgets version, please use \helpref{Find}{wxcolourdatabasefind} instead of
-it.
-
-

 \membersection{wxColourDatabase::FindName}\label{wxcolourdatabasefindname}
 
 \constfunc{wxString}{FindName}{\param{const wxColour\&}{ colour}}
 \membersection{wxColourDatabase::FindName}\label{wxcolourdatabasefindname}
 
 \constfunc{wxString}{FindName}{\param{const wxColour\&}{ colour}}


@@ -351,4 +409,3 @@ it.
 Finds a colour name given the colour. Returns an empty string if the colour is
 not found in the database.
 
 Finds a colour name given the colour. Returns an empty string if the colour is
 not found in the database.
 

-