[pypy-commit] cffi default: Document ffi.set_unicode()

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r1621:e5f44c1fd9f7
Date: 2015-01-07 18:51 +0100
http://bitbucket.org/cffi/cffi/changeset/e5f44c1fd9f7/

Log:	Document ffi.set_unicode()

diff --git a/cffi/api.py b/cffi/api.py
--- a/cffi/api.py
+++ b/cffi/api.py
@@ -411,16 +411,16 @@
     def from_handle(self, x):
         return self._backend.from_handle(x)
 
-    def set_unicode(self, unicode_enabled):
-        """Windows: if 'unicode_enabled' is True, enable the UNICODE and
+    def set_unicode(self, enabled_flag):
+        """Windows: if 'enabled_flag' is True, enable the UNICODE and
         _UNICODE defines in C, and declare the types like TCHAR and LPTCSTR
-        to be (pointers to) wchar_t.  If 'unicode_enabled' is False,
+        to be (pointers to) wchar_t.  If 'enabled_flag' is False,
         declare these types to be (pointers to) plain 8-bit characters.
         This is mostly for backward compatibility; you usually want True.
         """
         if self._windows_unicode is not None:
             raise ValueError("set_unicode() can only be called once")
-        if unicode_enabled:
+        if enabled_flag:
             self.cdef("typedef wchar_t TBYTE;"
                       "typedef wchar_t TCHAR;"
                       "typedef const wchar_t *LPCTSTR;"
@@ -438,7 +438,7 @@
                       "typedef char *PTSTR;"
                       "typedef TBYTE *PTBYTE;"
                       "typedef TCHAR *PTCHAR;")
-        self._windows_unicode = unicode_enabled
+        self._windows_unicode = enabled_flag
 
     def _apply_windows_unicode(self, kwds):
         defmacros = kwds.get('define_macros', ())
diff --git a/doc/source/index.rst b/doc/source/index.rst
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1374,6 +1374,27 @@
 
 .. "versionadded:: 0.4" --- inlined in the previous paragraph
 
+**ffi.set_unicode(enabled_flag)**: Windows: if ``enabled_flag`` is
+True, enable the ``UNICODE`` and ``_UNICODE`` defines in C, and
+declare the types like ``TCHAR`` and ``LPTCSTR`` to be (pointers to)
+``wchar_t``.  If ``enabled_flag`` is False, declare these types to be
+(pointers to) plain 8-bit characters.  *New in version 0.9.*
+
+The reason behind this method is that a lot of standard functions have
+two versions, like ``MessageBoxA()`` and ``MessageBoxW()``.  The
+official interface is ``MessageBox()`` with arguments like
+``LPTCSTR``.  Depending on whether ``UNICODE`` is defined or not, the
+standard header renames the generic function name to one of the two
+specialized versions, and declares the correct (unicode or not) types.
+
+Usually, the right thing to do is to call this method with True.  Be
+aware (particularly on Python 2) that you then need to pass unicode
+strings as arguments, not byte strings.  (Before cffi version 0.9,
+``TCHAR`` and friends where hard-coded as unicode, but ``UNICODE`` was,
+inconsistently, not defined by default.)
+
+.. "versionadded:: 0.9" --- inlined in the previous paragraph
+
 
 Unimplemented features
 ----------------------