X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8f520a56b7bacb0c685526188dd5f7bdbf186470..3cc305b2b4a0674c56c84d7088cfd70676b850f0:/docs/latex/wx/colour.tex diff --git a/docs/latex/wx/colour.tex b/docs/latex/wx/colour.tex index 40437b1cf5..0109378a5b 100644 --- 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, @@ -17,6 +28,10 @@ You can retrieve the current system colour settings with \helpref{wxSystemSettin +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + \wxheading{Predefined objects} Objects: @@ -40,20 +55,20 @@ wxLIGHT\_GREY} \latexignore{\rtfignore{\wxheading{Members}}} + \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}, \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}} -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}} @@ -67,6 +82,8 @@ Copy constructor. \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.} @@ -83,12 +100,43 @@ 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} 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} @@ -98,17 +146,20 @@ On X, an allocated pixel value is returned. -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::Ok}\label{wxcolourok} -\constfunc{bool}{Ok}{\void} +\membersection{wxColour::IsOk}\label{wxcolourisok} + +\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). \membersection{wxColour::Red}\label{wxcolourred} @@ -116,11 +167,27 @@ Returns true if the colour object is valid (the colour has been initialised with Returns the red intensity. + \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}} + +\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} -Sets the RGB intensity values. \membersection{wxColour::operator $=$}\label{wxcolourassign} @@ -136,17 +203,19 @@ Assignment operator, using a colour name to be found in the colour database. \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. +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}} -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} @@ -160,34 +229,45 @@ This class holds a variety of information related to colour dialogs. +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + \wxheading{See also} \helpref{wxColour}{wxcolour}, \helpref{wxColourDialog}{wxcolourdialog}, \helpref{wxColourDialog overview}{wxcolourdialogoverview} \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxColourData::wxColourData}\label{wxcolourdataconstr} + +\membersection{wxColourData::wxColourData}\label{wxcolourdatactor} \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. -\membersection{wxColourData::\destruct{wxColourData}} + +\membersection{wxColourData::\destruct{wxColourData}}\label{wxcolourdatadtor} \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 -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. + \membersection{wxColourData::GetColour}\label{wxcolourdatagetcolour} \constfunc{wxColour\&}{GetColour}{\void} @@ -196,6 +276,7 @@ Gets the current colour associated with the colour dialog. The default colour is black. + \membersection{wxColourData::GetCustomColour}\label{wxcolourdatagetcustomcolour} \constfunc{wxColour\&}{GetCustomColour}{\param{int}{ i}} @@ -203,7 +284,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. -The default custom colours are all white. +The default custom colours are invalid colours. + \membersection{wxColourData::SetChooseFull}\label{wxcolourdatasetchoosefull} @@ -214,6 +296,7 @@ with custom colour selection controls. Under other platforms, has no effect. The default value is true. + \membersection{wxColourData::SetColour}\label{wxcolourdatasetcolour} \func{void}{SetColour}{\param{const wxColour\&}{ colour}} @@ -222,6 +305,7 @@ Sets the default colour for the colour dialog. The default colour is black. + \membersection{wxColourData::SetCustomColour}\label{wxcolourdatasetcustomcolour} \func{void}{SetCustomColour}{\param{int}{ i}, \param{const wxColour\&}{ colour}} @@ -229,7 +313,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. -The default custom colours are all white. +The default custom colours are invalid colours. + \membersection{wxColourData::operator $=$}\label{wxcolourdataassign} @@ -237,12 +322,20 @@ The default custom colours are all white. Assignment operator for the colour data. + + + \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 -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} @@ -252,9 +345,13 @@ None +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + \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 @@ -275,36 +372,40 @@ YELLOW GREEN. \latexignore{\rtfignore{\wxheading{Members}}} + \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::AddColour}\label{wxcolourdatabaseaddcolour} +\func{void}{AddColour}{\param{const wxString\& }{colourName}, \param{const wxColour\&}{colour}} + \func{void}{AddColour}{\param{const wxString\& }{colourName}, \param{wxColour* }{colour}} Adds a colour to the database. If a colour with the same name already exists, it is replaced. -\membersection{wxColourDatabase::FindColour}\label{wxcolourdatabasefindcolour} - -\func{wxColour*}{FindColour}{\param{const wxString\& }{colourName}} +Please note that the overload taking a pointer is deprecated and will be +removed in the next wxWidgets version, please don't use it. -Finds a colour given the name. Returns NULL if not found. -\membersection{wxColourDatabase::FindName}\label{wxcolourdatabasefindname} +\membersection{wxColourDatabase::Find}\label{wxcolourdatabasefind} -\constfunc{wxString}{FindName}{\param{const wxColour\&}{ colour}} +\func{wxColour}{Find}{\param{const wxString\& }{colourName}} -Finds a colour name given the colour. Returns NULL if not found. +Finds a colour given the name. Returns an invalid colour object (that is, such +that its \helpref{Ok()}{wxcolourisok} method returns \false) if the colour wasn't +found in the database. -\membersection{wxColourDatabase::Initialize}\label{wxcolourdatabaseinitialize} -\func{void}{Initialize}{\void} +\membersection{wxColourDatabase::FindName}\label{wxcolourdatabasefindname} -Initializes the database with a number of stock colours. Called by wxWindows -on start-up. +\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.