Author: Armin Rigo <ar...@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
----------------------
_______________________________________________
pypy-commit mailing list
pypy-commit@python.org
https://mail.python.org/mailman/listinfo/pypy-commit
