From 0a67eeac3def703ca733305d107088ec01c8cbc2 Mon Sep 17 00:00:00 2001
From: Mattia Barbon <mbarbon@cpan.org>
Date: Fri, 23 Nov 2001 22:08:45 +0000
Subject: [PATCH] wxPerl documentation updates

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@12632 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/latex/wx/dataform.tex |  4 ++++
 docs/latex/wx/dataobj.tex  |  4 ++++
 docs/latex/wx/dc.tex       |  8 ++++----
 docs/latex/wx/fildrptg.tex |  2 ++
 docs/latex/wx/layout.tex   |  6 +++---
 docs/latex/wx/locale.tex   | 32 +++++++++++++++++++++++++++-----
 docs/latex/wx/menu.tex     |  2 +-
 docs/latex/wx/print.tex    | 16 ++++++++++++++++
 docs/latex/wx/regex.tex    |  2 +-
 docs/latex/wx/statusbr.tex |  3 +++
 10 files changed, 65 insertions(+), 14 deletions(-)

diff --git a/docs/latex/wx/dataform.tex b/docs/latex/wx/dataform.tex
index 3b9991e140..292c086835 100644
--- a/docs/latex/wx/dataform.tex
+++ b/docs/latex/wx/dataform.tex
@@ -70,6 +70,8 @@ Constructs a data format object for one of the standard data formats or an
 empty data object (use \helpref{SetType}{wxdataformatsettype} or 
 \helpref{SetId}{wxdataformatsetid} later in this case)
 
+\perlnote{In wxPerl this function is named {\tt newNative}.}
+
 \membersection{wxDataFormat::wxDataFormat}\label{wxdataformatwxdataformat}
 
 \func{}{wxDataFormat}{\param{const wxChar }{*format}}
@@ -77,6 +79,8 @@ empty data object (use \helpref{SetType}{wxdataformatsettype} or
 Constructs a data format object for a custom format identified by its name 
 {\it format}.
 
+\perlnote{In wxPerl this function is named {\tt newUser}.}
+
 \membersection{wxDataFormat::operator $==$}\label{wxdataformatoperatoreq}
 
 \constfunc{bool}{operator $==$}{\param{const wxDataFormat\&}{ format}}
diff --git a/docs/latex/wx/dataobj.tex b/docs/latex/wx/dataobj.tex
index 5a62f8532e..8292bb58ba 100644
--- a/docs/latex/wx/dataobj.tex
+++ b/docs/latex/wx/dataobj.tex
@@ -155,6 +155,10 @@ Destructor.
 Copy all supported formats in the given direction to the array pointed to by 
 {\it formats}. There is enough space for GetFormatCount(dir) formats in it.
 
+\perlnote{In wxPerl this method only takes the {\tt dir} parameter. 
+In scalar context it returns the first format,
+in list context it returns a list containing all the supported formats.}
+
 \membersection{wxDataObject::GetDataHere}\label{wxdataobjectgetdatahere}
 
 \constfunc{virtual bool}{GetDataHere}{\param{const wxDataFormat\&}{ format}, \param{void }{*buf} }
diff --git a/docs/latex/wx/dc.tex b/docs/latex/wx/dc.tex
index 95d44545be..5bb946f363 100644
--- a/docs/latex/wx/dc.tex
+++ b/docs/latex/wx/dc.tex
@@ -525,7 +525,7 @@ Gets the rectangle surrounding the current clipping region.
 rectangle are returned as a tuple.}
 
 \perlnote{This method takes no arguments and returns a four element list
-{\tt ( \$x, \$y, \$width, \$height )}}
+{\tt ( x, y, width, height )}}
 
 \membersection{wxDC::GetFont}\label{wxdcgetfont}
 
@@ -609,7 +609,7 @@ implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
 \twocolitem{{\bf GetSize()}}{Returns a Wx::Size}
 \twocolitem{{\bf GetSizeWH()}}{Returns a 2-element list
-  {\tt ( \$width, \$height )}}
+  {\tt ( width, height )}}
 \end{twocollist}
 }}
 
@@ -650,7 +650,7 @@ See also \helpref{wxFont}{wxfont}, \helpref{wxDC::SetFont}{wxdcsetfont}.
 
 \perlnote{In wxPerl this method is implemented as 
   {\bf GetTextExtent( string, font = undef )} returning a four element
-  array {\tt ( \$width, \$height, \$descent, \$externalLeading )}
+  array {\tt ( width, height, descent, externalLeading )}
 }
 
 \membersection{wxDC::GetTextForeground}\label{wxdcgettextforeground}
@@ -669,7 +669,7 @@ Gets the current text foreground colour (see \helpref{wxDC::SetTextForeground}{w
 Gets the current user scale factor (set by \helpref{SetUserScale}{wxdcsetuserscale}).
 
 \perlnote{In wxPerl this method takes no arguments and returna a two element
- array {\tt ( \$x, \$y )}}
+ array {\tt ( x, y )}}
 
 \membersection{wxDC::LogicalToDeviceX}\label{wxdclogicaltodevicex}
 
diff --git a/docs/latex/wx/fildrptg.tex b/docs/latex/wx/fildrptg.tex
index 3c92446d98..dfcf44d458 100644
--- a/docs/latex/wx/fildrptg.tex
+++ b/docs/latex/wx/fildrptg.tex
@@ -50,3 +50,5 @@ Override this function to receive dropped files.
 
 Return TRUE to accept the data, FALSE to veto the operation.
 
+\perlnote{In wxPerl there is just an array reference in place of {\tt nFiles}
+and {\tt files}.}
diff --git a/docs/latex/wx/layout.tex b/docs/latex/wx/layout.tex
index ac9f3bffc3..018b1f3064 100644
--- a/docs/latex/wx/layout.tex
+++ b/docs/latex/wx/layout.tex
@@ -28,9 +28,9 @@ not be changed.
 
 \perlnote{In wxPerl the constraints are accessed as
 \begin{verbatim}
-  my( \$constraint ) = Wx::LayoutConstraints->new();
-  \$constraint->centreX->AsIs();
-  \$constraint->centreY->Unconstrained();
+  constraint = Wx::LayoutConstraints->new();
+  constraint->centreX->AsIs();
+  constraint->centreY->Unconstrained();
 \end{verbatim}
 }
 
diff --git a/docs/latex/wx/locale.tex b/docs/latex/wx/locale.tex
index 4f529eb69a..121ef3feb5 100644
--- a/docs/latex/wx/locale.tex
+++ b/docs/latex/wx/locale.tex
@@ -6,16 +6,36 @@ generalization of the C locale concept.
 In wxWindows this class manages message catalogs which contain the translations
 of the strings used to the current language.
 
-\perlnote{In wxPerl the {\tt Wx} module exports a '\_' function
-that corresponds to the '\_' C++ macro.
+\perlnote{In wxPerl you can't use the '\_' function name, so
+the {\tt Wx::Locale} module can export the {\tt gettext} and 
+{\tt gettext\_noop} under any given name. 
 \begin{verbatim}
-  use Wx qw(_);
+  # this imports gettext ( equivalent to Wx::GetTranslation
+  # and gettext_noop ( a noop )
+  # into your module
+  use Wx::Locale qw(:default);
 
   # ....
 
-  print _( ``Panic!'' );
+  # use the functions
+  print gettext( ``Panic!'' ); 
 
-  my( \$button ) = Wx::Button->new( \$window, -1, _( ``Label'' ) );
+  button = Wx::Button->new( window, -1, gettext( ``Label'' ) );
+\end{verbatim}
+If you need to translate a lot of strings, then adding gettext( ) around
+each one is a long task ( that is why \_( ) was introduced ), so just choose
+a shorter name for gettext:
+\begin{verbatim}
+  #
+  use Wx::Locale 'gettext' => 't',
+                 'gettext_noop' => 'gettext_noop';
+
+  # ...
+
+  # use the functions
+  print t( ``Panic!!'' );
+
+  # ...
 \end{verbatim}
 }
 
@@ -371,6 +391,8 @@ struct WXDLLEXPORT wxLanguageInfo
 
 {\it Language} should be greater than wxLANGUAGE\_USER\_DEFINED.
 
+\perlnote{In wxPerl Wx::LanguageInfo has only one method:\par
+Wx::LanguageInfo->new( language, canonicalName, WinLang, WinSubLang, Description )}
 
 
 \membersection{wxLocale::GetCanonicalName}\label{wxlocalegetcanonicalname}
diff --git a/docs/latex/wx/menu.tex b/docs/latex/wx/menu.tex
index cbcd3148ad..33946872fe 100644
--- a/docs/latex/wx/menu.tex
+++ b/docs/latex/wx/menu.tex
@@ -236,7 +236,7 @@ optionally, the (sub)menu it belongs to.
 
 \perlnote{In wxPerl this method takes just the {\tt id} parameter;
 in scalar context it returns the associated {\tt Wx::MenuItem}, in list
-context it returns a two element list ( item, submenu )}
+context it returns a 2-element list ( item, submenu )}
 
 \wxheading{Parameters}
 
diff --git a/docs/latex/wx/print.tex b/docs/latex/wx/print.tex
index 088dca0e5f..b498836b50 100644
--- a/docs/latex/wx/print.tex
+++ b/docs/latex/wx/print.tex
@@ -760,6 +760,10 @@ it should be designed to take no parameters (other than the self
 reference) and to return a tuple of four integers.
 }
 
+\perlnote{When this method is overridden in a derived class,
+it must not take any parameters, an return a 4-element list.
+}
+
 \membersection{wxPrintout::GetPageSizeMM}\label{wxprintoutgetpagesizemm}
 
 \func{void}{GetPageSizeMM}{\param{int *}{w}, \param{int *}{h}}
@@ -768,6 +772,9 @@ Returns the size of the printer page in millimetres.
 
 \pythonnote{This method returns the output-only parameters as a tuple.}
 
+\perlnote{In wxPerl this method takes no arguments and returns a
+2-element list {\tt ( w, h )}}
+
 \membersection{wxPrintout::GetPageSizePixels}\label{wxprintoutgetpagesizepixels}
 
 \func{void}{GetPageSizePixels}{\param{int *}{w}, \param{int *}{h}}
@@ -781,6 +788,9 @@ previewing is to be supported.
 
 \pythonnote{This method returns the output-only parameters as a tuple.}
 
+\perlnote{In wxPerl this method takes no arguments and returns a
+2-element list {\tt ( w, h )}}
+
 \membersection{wxPrintout::GetPPIPrinter}\label{wxprintoutgetppiprinter}
 
 \func{void}{GetPPIPrinter}{\param{int *}{w}, \param{int *}{h}}
@@ -792,6 +802,9 @@ this by a scaling factor to take the preview DC size into account.
 
 \pythonnote{This method returns the output-only parameters as a tuple.}
 
+\perlnote{In wxPerl this method takes no arguments and returns a
+2-element list {\tt ( w, h )}}
+
 \membersection{wxPrintout::GetPPIScreen}\label{wxprintoutgetppiscreen}
 
 \func{void}{GetPPIScreen}{\param{int *}{w}, \param{int *}{h}}
@@ -803,6 +816,9 @@ this by a scaling factor to take the preview DC size into account.
 
 \pythonnote{This method returns the output-only parameters as a tuple.}
 
+\perlnote{In wxPerl this method takes no arguments and returns a
+2-element list {\tt ( w, h )}}
+
 \membersection{wxPrintout::HasPage}\label{wxprintouthaspage}
 
 \func{bool}{HasPage}{\param{int}{ pageNum}}
diff --git a/docs/latex/wx/regex.tex b/docs/latex/wx/regex.tex
index 012a03ee1d..175fcd0aa4 100644
--- a/docs/latex/wx/regex.tex
+++ b/docs/latex/wx/regex.tex
@@ -80,7 +80,7 @@ enum
 Flags for regex matching to be used with \helpref{Matches()}{wxregexmatches}.
 
 These flags are mainly useful when doing several matches in a long string
-to prevent erroneous matches for \verb|'^'| and {\tt '\$'}:
+to prevent erroneous matches for {\tt '^'} and {\tt '\$'}:
 
 \begin{verbatim}
 enum
diff --git a/docs/latex/wx/statusbr.tex b/docs/latex/wx/statusbr.tex
index 6985cc883e..976d90ddc7 100644
--- a/docs/latex/wx/statusbr.tex
+++ b/docs/latex/wx/statusbr.tex
@@ -111,6 +111,9 @@ TRUE if the field index is valid, FALSE otherwise.
 
 \helpref{wxRect}{wxrect}
 
+\perlnote{In wxPerl this function returns a {\tt Wx::Rect} if the field
+  index is valid, {\tt undef} otherwise.}
+
 \membersection{wxStatusBar::GetFieldsCount}\label{wxstatusbargetfieldscount}
 
 \constfunc{int}{GetFieldsCount}{\void}
-- 
2.45.2

