add @DATE@, @TIME@ and @TITLE@ macros to HTML printing (extended/modified patch 1528679)

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

diff --git a/docs/latex/wx/colour.tex b/docs/latex/wx/colour.tex
index 06171474d8a097307a5c87319128b8194ecbd25d..4ba28808cda96562112100dcf044bb0e8375be90 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,


@@ -7,6 +18,8 @@ named colour may be returned instead of creating a new colour.
 
 Valid RGB values are in the range 0 to 255.
 
 
 Valid RGB values are in the range 0 to 255.
 

+You can retrieve the current system colour settings with \helpref{wxSystemSettings}{wxsystemsettings}.
+

 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}


@@ -34,24 +47,24 @@ wxLIGHT\_GREY}
 \wxheading{See also}
 
 \helpref{wxColourDatabase}{wxcolourdatabase}, \helpref{wxPen}{wxpen}, \helpref{wxBrush}{wxbrush},\rtfsp
 \wxheading{See also}
 
 \helpref{wxColourDatabase}{wxcolourdatabase}, \helpref{wxPen}{wxpen}, \helpref{wxBrush}{wxbrush},\rtfsp

-\helpref{wxColourDialog}{wxcolourdialog}
+\helpref{wxColourDialog}{wxcolourdialog}, \helpref{wxSystemSettings}{wxsystemsettings}

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

+

 \membersection{wxColour::wxColour}\label{wxcolourconstr}
 
 \func{}{wxColour}{\void}
 
 Default constructor.
 
 \membersection{wxColour::wxColour}\label{wxcolourconstr}
 
 \func{}{wxColour}{\void}
 
 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}}

 
 Constructs a colour from red, green and blue values.
 
 \func{}{wxColour}{\param{const wxString\& }{colourNname}}
 
 
 Constructs a colour from red, green and blue values.
 
 \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}}
 


@@ -81,12 +94,32 @@ Copy constructor.
 }
 
 
 }
 
 

+

 \membersection{wxColour::Blue}\label{wxcolourblue}
 
 \constfunc{unsigned char}{Blue}{\void}
 
 Returns the blue intensity.
 
 \membersection{wxColour::Blue}\label{wxcolourblue}
 
 \constfunc{unsigned char}{Blue}{\void}
 
 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 {\bf wxC2S\_NAME}, to obtain the colour
+name (e.g. wxColour(255,0,0) -> \texttt{``red"}), {\bf wxC2S\_CSS\_SYNTAX}, to obtain
+the colour in the \texttt{``rgb(r,g,b)"} syntax
+(e.g. wxColour(255,0,0) -> \texttt{``rgb(255,0,0)"}), and {\bf 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.
+
+\newsince{2.7.0}
+

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


@@ -96,17 +129,20 @@ On X, an allocated pixel value is returned.
 
 -1 is returned if the pixel is invalid (on X, unallocated).
 
 
 -1 is returned if the pixel is invalid (on X, unallocated).
 

+

 \membersection{wxColour::Green}\label{wxcolourgreen}
 
 \constfunc{unsigned char}{Green}{\void}
 
 Returns the green intensity.
 
 \membersection{wxColour::Green}\label{wxcolourgreen}
 
 \constfunc{unsigned char}{Green}{\void}
 
 Returns the green intensity.
 

+

 \membersection{wxColour::Ok}\label{wxcolourok}
 
 \constfunc{bool}{Ok}{\void}
 
 \membersection{wxColour::Ok}\label{wxcolourok}
 
 \constfunc{bool}{Ok}{\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).
+

 
 \membersection{wxColour::Red}\label{wxcolourred}
 
 
 \membersection{wxColour::Red}\label{wxcolourred}
 


@@ -114,11 +150,23 @@ Returns TRUE if the colour object is valid (the colour has been initialised with
 
 Returns the red intensity.
 
 
 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}}
+
+\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)"} 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}

 
 

-Sets the RGB intensity values.

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


@@ -134,12 +182,14 @@ Assignment operator, using a colour name to be found in the colour database.
 
 \helpref{wxColourDatabase}{wxcolourdatabase}
 
 
 \helpref{wxColourDatabase}{wxcolourdatabase}
 

+

 \membersection{wxColour::operator $==$}\label{wxcolourequality}
 
 \func{bool}{operator $==$}{\param{const wxColour\&}{ colour}}
 
 Tests the equality of two colours by comparing individual red, green blue colours.
 
 \membersection{wxColour::operator $==$}\label{wxcolourequality}
 
 \func{bool}{operator $==$}{\param{const wxColour\&}{ colour}}
 
 Tests the equality of two colours by comparing individual red, green blue colours.
 

+

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


@@ -164,27 +214,34 @@ 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
-to black, and the {\it choose full} setting to TRUE.
+Constructor. Initializes the custom colours to {\tt wxNullColour},
+the {\it data colour} setting
+to black, and the {\it choose full} setting to true.
+

 
 

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

 
 \func{}{\destruct{wxColourData}}{\void}
 
 Destructor.
 
 
 \func{}{\destruct{wxColourData}}{\void}
 
 Destructor.
 

+

 \membersection{wxColourData::GetChooseFull}\label{wxcolourdatagetchoosefull}
 
 \constfunc{bool}{GetChooseFull}{\void}
 
 Under Windows, determines whether the Windows colour dialog will display the full dialog
 \membersection{wxColourData::GetChooseFull}\label{wxcolourdatagetchoosefull}
 
 \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.

 
 \membersection{wxColourData::GetColour}\label{wxcolourdatagetcolour}
 
 
 \membersection{wxColourData::GetColour}\label{wxcolourdatagetcolour}
 


@@ -194,6 +251,7 @@ Gets the current colour associated with the colour dialog.
 
 The default colour is black.
 
 
 The default colour is black.
 

+

 \membersection{wxColourData::GetCustomColour}\label{wxcolourdatagetcustomcolour}
 
 \constfunc{wxColour\&}{GetCustomColour}{\param{int}{ i}}
 \membersection{wxColourData::GetCustomColour}\label{wxcolourdatagetcustomcolour}
 
 \constfunc{wxColour\&}{GetCustomColour}{\param{int}{ i}}


@@ -201,7 +259,8 @@ 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}
 


@@ -210,7 +269,8 @@ The default custom colours are all white.
 Under Windows, tells the Windows colour dialog to display the full dialog
 with custom colour selection controls. Under other platforms, has no effect.
 
 Under Windows, tells the Windows colour dialog to display the full dialog
 with custom colour selection controls. Under other platforms, has no effect.
 

-The default value is TRUE.
+The default value is true.
+

 
 \membersection{wxColourData::SetColour}\label{wxcolourdatasetcolour}
 
 
 \membersection{wxColourData::SetColour}\label{wxcolourdatasetcolour}
 


@@ -220,6 +280,7 @@ Sets the default colour for the colour dialog.
 
 The default colour is black.
 
 
 The default colour is black.
 

+

 \membersection{wxColourData::SetCustomColour}\label{wxcolourdatasetcustomcolour}
 
 \func{void}{SetCustomColour}{\param{int}{ i}, \param{const wxColour\&}{ colour}}
 \membersection{wxColourData::SetCustomColour}\label{wxcolourdatasetcustomcolour}
 
 \func{void}{SetCustomColour}{\param{int}{ i}, \param{const wxColour\&}{ colour}}


@@ -227,7 +288,8 @@ 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}
 


@@ -235,17 +297,24 @@ The default custom colours are all white.
 
 Assignment operator for the colour data.
 
 
 Assignment operator for the colour data.
 

+
+
+

 \section{\class{wxColourDatabase}}\label{wxcolourdatabase}
 
 \section{\class{wxColourDatabase}}\label{wxcolourdatabase}
 

-wxWindows maintains a database of standard RGB colours for a predefined
+wxWidgets maintains a database of standard RGB colours for a predefined

 set of named colours (such as ``BLACK'', ``LIGHT GREY''). The
 set of named colours (such as ``BLACK'', ``LIGHT GREY''). The

-application may add to this set if desired by using {\it Append}.  There
-is only one instance of this class: {\bf wxTheColourDatabase}.
+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}.
+
+There is one predefined instance of this class called
+{\bf wxTheColourDatabase}.

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 

-\helpref{wxList}{wxlist}\\
-\helpref{wxObject}{wxobject}
+None

 
 \wxheading{Include files}
 
 
 \wxheading{Include files}
 


@@ -253,7 +322,7 @@ is only one instance of this class: {\bf wxTheColourDatabase}.
 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-The colours in the standard database are as follows:
+The standard database contains at least the following colours:

 
 AQUAMARINE, BLACK, BLUE, BLUE VIOLET, BROWN, CADET BLUE, CORAL,
 CORNFLOWER BLUE, CYAN, DARK GREY, DARK GREEN, DARK OLIVE GREEN, DARK
 
 AQUAMARINE, BLACK, BLUE, BLUE VIOLET, BROWN, CADET BLUE, CORAL,
 CORNFLOWER BLUE, CYAN, DARK GREY, DARK GREEN, DARK OLIVE GREEN, DARK


@@ -274,29 +343,39 @@ YELLOW GREEN.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

+

 \membersection{wxColourDatabase::wxColourDatabase}\label{wxcolourdatabaseconstr}
 
 \func{}{wxColourDatabase}{\void}
 
 \membersection{wxColourDatabase::wxColourDatabase}\label{wxcolourdatabaseconstr}
 
 \func{}{wxColourDatabase}{\void}
 

-Constructs the colour database.
+Constructs the colour database. It will be initialized at the first use.

 
 

-\membersection{wxColourDatabase::FindColour}\label{wxcolourdatabasefindcolour}

 
 

-\func{wxColour*}{FindColour}{\param{const wxString\& }{colourName}}
+\membersection{wxColourDatabase::AddColour}\label{wxcolourdatabaseaddcolour}

 
 

-Finds a colour given the name. Returns NULL if not found.
+\func{void}{AddColour}{\param{const wxString\& }{colourName}, \param{const wxColour\&}{colour}}

 
 

-\membersection{wxColourDatabase::FindName}\label{wxcolourdatabasefindname}
+\func{void}{AddColour}{\param{const wxString\& }{colourName}, \param{wxColour* }{colour}}

 
 

-\constfunc{wxString}{FindName}{\param{const wxColour\&}{ colour}}
+Adds a colour to the database. If a colour with the same name already exists,
+it is replaced.

 
 

-Finds a colour name given the colour. Returns NULL if not found.
+Please note that the overload taking a pointer is deprecated and will be
+removed in the next wxWidgets version, please don't use it.

 
 

-\membersection{wxColourDatabase::Initialize}\label{wxcolourdatabaseinitialize}

 
 

-\func{void}{Initialize}{\void}
+\membersection{wxColourDatabase::Find}\label{wxcolourdatabasefind}

 
 

-Initializes the database with a number of stock colours.  Called by wxWindows
-on start-up.
+\func{wxColour}{Find}{\param{const wxString\& }{colourName}}

 
 

+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
+found in the database.
+
+
+\membersection{wxColourDatabase::FindName}\label{wxcolourdatabasefindname}
+
+\constfunc{wxString}{FindName}{\param{const wxColour\&}{ colour}}

 
 

+Finds a colour name given the colour. Returns an empty string if the colour is
+not found in the database.