add events API to wxHtmlWindow (patch #1504493 by Francesco Montorsi)

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

diff --git a/docs/latex/wx/dc.tex b/docs/latex/wx/dc.tex
index 2dbc2f184661ad9e3bef041d232d5f96e2850577..c7242bf74f11f4dc0673f4b1e2798acf30870dfb 100644 (file)
--- a/docs/latex/wx/dc.tex
+++ b/docs/latex/wx/dc.tex
@@ -6,8 +6,10 @@ so a window can have a device context associated with it, and a printer also has
 In this way, the same piece of code may write to a number of different devices,
 if the device context is used as a parameter.
 
 In this way, the same piece of code may write to a number of different devices,
 if the device context is used as a parameter.
 

-Derived types of wxDC have documentation for specific features
-only, so refer to this section for most device context information.
+Notice that wxDC is an abstract base class and can't be created directly,
+please use \helpref{wxPaintDC}{wxpaintdc}, \helpref{wxClientDC}{wxclientdc}, 
+\helpref{wxWindowDC}{wxwindowdc}, \helpref{wxScreenDC}{wxscreendc}, 
+\helpref{wxMemoryDC}{wxmemorydc} or \helpref{wxPrinterDC}{wxprinterdc}.

 
 % VZ: we should really document them instead of this lame excuse, but I don't
 %     have time for it now, when it is done please remove this
 
 % VZ: we should really document them instead of this lame excuse, but I don't
 %     have time for it now, when it is done please remove this


@@ -16,6 +18,12 @@ there are also versions which accept single {\tt wxPoint} parameter instead of
 two {\tt wxCoord} ones or {\tt wxPoint} and {\tt wxSize} instead of four of
 them.
 
 two {\tt wxCoord} ones or {\tt wxPoint} and {\tt wxSize} instead of four of
 them.
 

+\wxheading{Support for Transparency / Alpha Channel}
+
+On Mac OS X when using Core Graphics (wx\_MAC\_USE\_CORE\_GRAPHICS set to 1) 
+colors with alpha are supported, so instances  {\tt wxPen} or  {\tt wxBrush} that are built from  {\tt wxColour} use
+the color's alpha values when stroking or filling.
+

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


@@ -31,36 +39,6 @@ them.
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 

-\membersection{wxDC::wxDC}\label{wxdcctor}
-
-\func{}{wxDC}{\void}
-
-Constructor.
-
-
-\membersection{wxDC::\destruct{wxDC}}\label{wxdcdtor}
-
-\func{}{\destruct{wxDC}}{\void}
-
-Destructor.
-
-
-\membersection{wxDC::BeginDrawing}\label{wxdcbegindrawing}
-
-\func{void}{BeginDrawing}{\void}
-
-Allows optimization of drawing code under MS Windows. Enclose
-drawing primitives between {\bf BeginDrawing} and {\bf EndDrawing}\rtfsp
-calls.
-
-Drawing to a wxDialog panel device context outside of a
-system-generated OnPaint event {\it requires} this pair of calls to
-enclose drawing code. This is because a Windows dialog box does not have
-a retained device context associated with it, and selections such as pen
-and brush settings would be lost if the device context were obtained and
-released for each drawing operation.
-
-

 \membersection{wxDC::Blit}\label{wxdcblit}
 
 \func{bool}{Blit}{\param{wxCoord}{ xdest}, \param{wxCoord}{ ydest}, \param{wxCoord}{ width}, \param{wxCoord}{ height},
 \membersection{wxDC::Blit}\label{wxdcblit}
 
 \func{bool}{Blit}{\param{wxCoord}{ xdest}, \param{wxCoord}{ ydest}, \param{wxCoord}{ width}, \param{wxCoord}{ height},


@@ -193,6 +171,15 @@ wxUSE\_DC\_CACHEING preprocessor symbol for portability.
 \end{comment}
 
 
 \end{comment}
 
 

+\membersection{wxDC::ComputeScaleAndOrigin}\label{wxdccomputescaleandorigin}
+
+\func{virtual void}{ComputeScaleAndOrigin}{\void}
+
+Performs all necessary computations for given platform and context type
+after each change of scale and origin parameters. Usually called automatically 
+internally after such changes.
+
+

 \membersection{wxDC::CrossHair}\label{wxdccrosshair}
 
 \func{void}{CrossHair}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}
 \membersection{wxDC::CrossHair}\label{wxdccrosshair}
 
 \func{void}{CrossHair}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}


@@ -336,6 +323,24 @@ Draw an icon on the display (does nothing if the device context is PostScript).
 This can be the simplest way of drawing bitmaps on a window.
 
 
 This can be the simplest way of drawing bitmaps on a window.
 
 

+\membersection{wxDC::DrawLabel}\label{wxdcdrawlabel}
+
+\func{virtual void}{DrawLabel}{\param{const wxString\&}{ text},
+                               \param{const wxBitmap\&}{ image},
+                               \param{const wxRect\&}{ rect},
+                               \param{int}{ alignment = wxALIGN\_LEFT | wxALIGN\_TOP},
+                               \param{int}{ indexAccel = -1},
+                               \param{wxRect *}{rectBounding = NULL}}
+
+\func{void}{DrawLabel}{\param{const wxString\&}{ text}, \param{const wxRect\&}{ rect},
+                       \param{int}{ alignment = wxALIGN\_LEFT | wxALIGN\_TOP},
+                       \param{int}{ indexAccel = -1}}
+
+Draw optional bitmap and the text into the given rectangle and aligns it as specified
+by alignment parameter; it also will emphasize the character with the given index if
+it is != -1 and return the bounding rectangle if required.
+
+

 \membersection{wxDC::DrawLine}\label{wxdcdrawline}
 
 \func{void}{DrawLine}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}}
 \membersection{wxDC::DrawLine}\label{wxdcdrawline}
 
 \func{void}{DrawLine}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}}


@@ -459,7 +464,7 @@ which is.
 
 \membersection{wxDC::DrawRoundedRectangle}\label{wxdcdrawroundedrectangle}
 
 
 \membersection{wxDC::DrawRoundedRectangle}\label{wxdcdrawroundedrectangle}
 

-\func{void}{DrawRoundedRectangle}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}, \param{double}{ radius = 20}}
+\func{void}{DrawRoundedRectangle}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}, \param{double}{ radius}}

 
 Draws a rectangle with the given top left corner, and with the given
 size.  The corners are quarter-circles using the given radius. The
 
 Draws a rectangle with the given top left corner, and with the given
 size.  The corners are quarter-circles using the given radius. The


@@ -477,12 +482,15 @@ the rectangle.
 
 \membersection{wxDC::DrawSpline}\label{wxdcdrawspline}
 
 
 \membersection{wxDC::DrawSpline}\label{wxdcdrawspline}
 

+\func{void}{DrawSpline}{\param{int }{n}, \param{wxPoint }{points[]}}
+
+Draws a spline between all given control points, using the current
+pen.
+

 \func{void}{DrawSpline}{\param{wxList *}{points}}
 
 Draws a spline between all given control points, using the current
 \func{void}{DrawSpline}{\param{wxList *}{points}}
 
 Draws a spline between all given control points, using the current

-pen.  Doesn't delete the wxList and contents. The spline is drawn
-using a series of lines, using an algorithm taken from the X drawing
-program `XFIG'.
+pen.  Doesn't delete the wxList and contents.

 
 \func{void}{DrawSpline}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}, \param{wxCoord}{ x3}, \param{wxCoord}{ y3}}
 
 
 \func{void}{DrawSpline}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}, \param{wxCoord}{ x3}, \param{wxCoord}{ y3}}
 


@@ -538,15 +546,6 @@ wxUSE\_DC\_CACHEING preprocessor symbol for portability.
 Ends a document (only relevant when outputting to a printer).
 
 
 Ends a document (only relevant when outputting to a printer).
 
 

-\membersection{wxDC::EndDrawing}\label{wxdcenddrawing}
-
-\func{void}{EndDrawing}{\void}
-
-Allows optimization of drawing code under MS Windows. Enclose
-drawing primitives between {\bf BeginDrawing} and {\bf EndDrawing}\rtfsp
-calls.
-
-

 \membersection{wxDC::EndPage}\label{wxdcendpage}
 
 \func{void}{EndPage}{\void}
 \membersection{wxDC::EndPage}\label{wxdcendpage}
 
 \func{void}{EndPage}{\void}


@@ -629,7 +628,24 @@ rectangle are returned as a tuple.}
 
 \constfunc{const wxFont\&}{GetFont}{\void}
 
 
 \constfunc{const wxFont\&}{GetFont}{\void}
 

-Gets the current font (see \helpref{wxDC::SetFont}{wxdcsetfont}).
+Gets the current font. Notice that even although each device context object has
+some default font after creation, this method would return a \texttt{wxNullFont} 
+initially and only after calling \helpref{wxDC::SetFont}{wxdcsetfont} a valid
+font is returned.
+
+
+\membersection{wxDC::GetLayoutDirection}\label{wxdcgetlayoutdirection}
+
+\constfunc{wxLayoutDirection}{GetLayoutDirection}{\void}
+
+Gets the current layout direction of the device context. On platforms where RTL layout
+is supported, the return value will either be \texttt{wxLayout\_LeftToRight} or 
+\texttt{wxLayout\_RightToLeft}. If RTL layout is not supported, the return value will 
+be \texttt{wxLayout\_Default}.
+
+\wxheading{See also}
+
+\helpref{SetLayoutDirection}{wxdcsetlayoutdirection}

 
 
 \membersection{wxDC::GetLogicalFunction}\label{wxdcgetlogicalfunction}
 
 
 \membersection{wxDC::GetLogicalFunction}\label{wxdcgetlogicalfunction}


@@ -646,25 +662,17 @@ Gets the current logical function (see \helpref{wxDC::SetLogicalFunction}{wxdcse
 Gets the {\it mapping mode} for the device context (see \helpref{wxDC::SetMapMode}{wxdcsetmapmode}).
 
 
 Gets the {\it mapping mode} for the device context (see \helpref{wxDC::SetMapMode}{wxdcsetmapmode}).
 
 

-\membersection{wxDC::GetOptimization}\label{wxdcgetoptimization}
-
-\func{bool}{GetOptimization}{\void}
-
-Returns true if device context optimization is on.
-See \helpref{wxDC::SetOptimization}{wxsetoptimization} for details.
-
-

 \membersection{wxDC::GetPartialTextExtents}\label{wxdcgetpartialtextextents}
 
 \constfunc{bool}{GetPartialTextExtents}{\param{const wxString\&  }{text}, 
 \param{wxArrayInt\& }{widths}}
 
 \membersection{wxDC::GetPartialTextExtents}\label{wxdcgetpartialtextextents}
 
 \constfunc{bool}{GetPartialTextExtents}{\param{const wxString\&  }{text}, 
 \param{wxArrayInt\& }{widths}}
 

-Fills the {\it widths} array with the widths from the begining of 
-{\it text} to the coresponding character of {\it text}.  The generic
+Fills the {\it widths} array with the widths from the beginning of 
+{\it text} to the corresponding character of {\it text}.  The generic

 version simply builds a running total of the widths of each character
 using \helpref{GetTextExtent}{wxdcgettextextent}, however if the
 various platforms have a native API function that is faster or more
 version simply builds a running total of the widths of each character
 using \helpref{GetTextExtent}{wxdcgettextextent}, however if the
 various platforms have a native API function that is faster or more

-accurate than the generic implementaiton then it should be used
+accurate than the generic implementation then it should be used

 instead. 
 
 \pythonnote{This method only takes the {\it text} parameter and
 instead. 
 
 \pythonnote{This method only takes the {\it text} parameter and


@@ -682,9 +690,11 @@ Gets the current pen (see \helpref{wxDC::SetPen}{wxdcsetpen}).
 
 \func{bool}{GetPixel}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxColour *}{colour}}
 
 
 \func{bool}{GetPixel}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxColour *}{colour}}
 

-Sets {\it colour} to the colour at the specified location.
+Gets in {\it colour} the colour at the specified location.

 Not available for wxPostScriptDC or wxMetafileDC.
 
 Not available for wxPostScriptDC or wxMetafileDC.
 

+Note that setting a pixel can be done using \helpref{DrawPoint}{wxdcdrawpoint}.
+

 \pythonnote{For wxPython the wxColour value is returned and is not
 required as a parameter.}
 
 \pythonnote{For wxPython the wxColour value is returned and is not
 required as a parameter.}
 


@@ -760,10 +770,8 @@ dimension from the baseline of the font to the bottom of the
 descender, and {\it externalLeading} is any extra vertical space added
 to the font by the font designer (usually is zero).
 
 descender, and {\it externalLeading} is any extra vertical space added
 to the font by the font designer (usually is zero).
 

-The optional parameter {\it font} specifies an alternative
-to the currently selected font: but note that this does not
-yet work under Windows, so you need to set a font for
-the device context first.
+If the optional parameter {\it font} is specified and valid, then it is used
+for the text extent calculation. Otherwise the currently selected font is.

 
 See also \helpref{wxFont}{wxfont}, \helpref{wxDC::SetFont}{wxdcsetfont}.
 
 
 See also \helpref{wxFont}{wxfont}, \helpref{wxDC::SetFont}{wxdcsetfont}.
 


@@ -798,6 +806,35 @@ Gets the current user scale factor (set by \helpref{SetUserScale}{wxdcsetusersca
  array {\tt ( x, y )}}
 
 
  array {\tt ( x, y )}}
 
 

+\membersection{wxDC::GradientFillConcentric}\label{wxdcgradientfillconcentric}
+
+\func{void}{GradientFillConcentric}{\param{const wxRect\&}{ rect}, \param{const wxColour\&}{ initialColour}, \param{const wxColour\&}{ destColour}}
+
+\func{void}{GradientFillConcentric}{\param{const wxRect\&}{ rect}, \param{const wxColour\&}{ initialColour}, \param{const wxColour\&}{ destColour}, \param{const wxPoint\& }{circleCenter}}
+
+Fill the area specified by rect with a radial gradient, starting from 
+\arg{initialColour} at the centre of the circle and fading to \arg{destColour} 
+on the circle outside.
+
+\arg{circleCenter} are the relative coordinates of centre of the circle in
+the specified \arg{rect}. If not specified, the cercle is placed at the
+centre of rect.
+
+\textbf{Note: } Currently this function is very slow, don't use it for
+real-time drawing.
+
+
+\membersection{wxDC::GradientFillLinear}\label{wxdcgradientfilllinear}
+
+\func{void}{GradientFillLinear}{\param{const wxRect\&}{ rect}, \param{const wxColour\&}{ initialColour}, \param{const wxColour\&}{ destColour}, \param{wxDirection}{ nDirection = wxEAST}}
+
+Fill the area specified by \arg{rect} with a linear gradient, starting from 
+\arg{initialColour} and eventually fading to \arg{destColour}. The 
+\arg{nDirection} specifies the direction of the colour change, default is to
+use \arg{initialColour} on the left part of the rectangle and 
+\arg{destColour} on the right one.
+
+

 \membersection{wxDC::LogicalToDeviceX}\label{wxdclogicaltodevicex}
 
 \func{wxCoord}{LogicalToDeviceX}{\param{wxCoord}{ x}}
 \membersection{wxDC::LogicalToDeviceX}\label{wxdclogicaltodevicex}
 
 \func{wxCoord}{LogicalToDeviceX}{\param{wxCoord}{ x}}


@@ -860,7 +897,7 @@ Gets the minimum horizontal extent used in drawing commands so far.
 Gets the minimum vertical extent used in drawing commands so far.
 
 
 Gets the minimum vertical extent used in drawing commands so far.
 
 

-\membersection{wxDC::Ok}\label{wxdcok}
+\membersection{wxDC::IsOk}\label{wxdcisok}

 
 \func{bool}{Ok}{\void}
 
 
 \func{bool}{Ok}{\void}
 


@@ -885,8 +922,8 @@ doesn't contain anything.
                                 \param{bool}{ yBottomUp}}
 
 Sets the x and y axis orientation (i.e., the direction from lowest to
                                 \param{bool}{ yBottomUp}}
 
 Sets the x and y axis orientation (i.e., the direction from lowest to

-highest values on the axis). The default orientation is the natural
-orientation, e.g. x axis from left to right and y axis from bottom up.
+highest values on the axis). The default orientation is 
+x axis from left to right and y axis from top down.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -974,6 +1011,18 @@ should not pass {\tt wxNullFont} to this method.
 See also \helpref{wxFont}{wxfont}.
 
 
 See also \helpref{wxFont}{wxfont}.
 
 

+\membersection{wxDC::SetLayoutDirection}\label{wxdcsetlayoutdirection}
+
+\func{void}{SetLayoutDirection}{\param{wxLayoutDirection}{ dir}}
+
+Sets the current layout direction for the device context. \arg{dir} may be either
+\texttt{wxLayout\_Default}, \texttt{wxLayout\_LeftToRight} or \texttt{wxLayout\_RightToLeft}.
+
+\wxheading{See also}
+
+\helpref{GetLayoutDirection}{wxdcgetlayoutdirection}
+
+

 \membersection{wxDC::SetLogicalFunction}\label{wxdcsetlogicalfunction}
 
 \func{void}{SetLogicalFunction}{\param{int}{ function}}
 \membersection{wxDC::SetLogicalFunction}\label{wxdcsetlogicalfunction}
 
 \func{void}{SetLogicalFunction}{\param{int}{ function}}


@@ -1041,21 +1090,6 @@ The mapping mode can be one of the following:
 \end{twocollist}
 
 
 \end{twocollist}
 
 

-\membersection{wxDC::SetOptimization}\label{wxsetoptimization}
-
-\func{void}{SetOptimization}{\param{bool }{optimize}}
-
-If {\it optimize} is true (the default), this function sets optimization mode on.
-This currently means that under X, the device context will not try to set a pen or brush
-property if it is known to be set already. This approach can fall down
-if non-wxWidgets code is using the same device context or window, for example
-when the window is a panel on which the windowing system draws panel items.
-The wxWidgets device context 'memory' will now be out of step with reality.
-
-Setting optimization off, drawing, then setting it back on again, is a trick
-that must occasionally be employed.
-
-

 \membersection{wxDC::SetPalette}\label{wxdcsetpalette}
 
 \func{void}{SetPalette}{\param{const wxPalette\& }{palette}}
 \membersection{wxDC::SetPalette}\label{wxdcsetpalette}
 
 \func{void}{SetPalette}{\param{const wxPalette\& }{palette}}


@@ -1111,7 +1145,7 @@ Sets the user scaling factor, useful for applications which require
 \func{bool}{StartDoc}{\param{const wxString\& }{message}}
 
 Starts a document (only relevant when outputting to a printer).
 \func{bool}{StartDoc}{\param{const wxString\& }{message}}
 
 Starts a document (only relevant when outputting to a printer).

-Message is a message to show whilst printing.
+Message is a message to show while printing.

 
 
 \membersection{wxDC::StartPage}\label{wxdcstartpage}
 
 
 \membersection{wxDC::StartPage}\label{wxdcstartpage}


@@ -1120,40 +1154,3 @@ Message is a message to show whilst printing.
 
 Starts a document page (only relevant when outputting to a printer).
 
 
 Starts a document page (only relevant when outputting to a printer).
 

-\section{\class{wxDCClipper}}\label{wxdcclipper}
-
-This is a small helper class which sets the specified to its constructor
-clipping region and then automatically destroys it in its destructor. Using
-it ensures that unwanted clipping region is not left set on the DC.
-
-\wxheading{Derived from}
-
-No base class
-
-\wxheading{Include files}
-
-<wx/dc.h>
-
-\wxheading{See also}
-
-\helpref{wxDC}{wxdc}
-
-\latexignore{\rtfignore{\wxheading{Members}}}
-
-
-\membersection{wxDCClipper::wxDCClipper}\label{wxdcclipperctor}
-
-\func{}{wxDCClipper}{\param{wxDC\& }{dc}, \param{wxCoord }{x},\param{wxCoord }{y},\param{wxCoord }{w},\param{wxCoord }{h},}
-
-\func{}{wxDCClipper}{\param{wxDC\& }{dc}, \param{const wxRect\&}{ rect}}
-
-Constructor: sets the the clipping region for the given device context to the
-specified rectangle.
-
-
-\membersection{wxDCClipper::\destruct{wxDCClipper}}\label{wxdcclipperdtor}
-
-\func{}{\destruct{wxDCClipper}}{\void}
-
-Destructor: destroys the clipping region set in the constructor.
-