]> git.saurik.com Git - wxWidgets.git/blobdiff - wxPython/src/mac/_misc.py
doc tweaks
[wxWidgets.git] / wxPython / src / mac / _misc.py
index e3b18b7a47f378652257bbe204bd50b41a88e0c4..a8e6ecea5e13c0273501f75dca1904e3f0a6118f 100644 (file)
@@ -484,7 +484,14 @@ def GetTopLevelParent(*args, **kwargs):
     return _misc_.GetTopLevelParent(*args, **kwargs)
 
 def GetKeyState(*args, **kwargs):
-    """GetKeyState(int key) -> bool"""
+    """
+    GetKeyState(int key) -> bool
+
+    Get the state of a key (true if pressed or toggled on, false if not.)
+    This is generally most useful getting the state of the modifier or
+    toggle keys.  On some platforms those may be the only keys that work.
+
+    """
     return _misc_.GetKeyState(*args, **kwargs)
 
 def WakeUpMainThread(*args, **kwargs):
@@ -2343,68 +2350,6 @@ class ArtProvider(object):
                 ...
                 return bmp
 
-
-    Identifying art resources
-    -------------------------
-
-    Every bitmap is known to wx.ArtProvider under an unique ID that is
-    used when requesting a resource from it. The IDs can have one of these
-    predefined values:
-
-        * wx.ART_ADD_BOOKMARK
-        * wx.ART_DEL_BOOKMARK
-        * wx.ART_HELP_SIDE_PANEL
-        * wx.ART_HELP_SETTINGS
-        * wx.ART_HELP_BOOK
-        * wx.ART_HELP_FOLDER
-        * wx.ART_HELP_PAGE
-        * wx.ART_GO_BACK
-        * wx.ART_GO_FORWARD
-        * wx.ART_GO_UP
-        * wx.ART_GO_DOWN
-        * wx.ART_GO_TO_PARENT
-        * wx.ART_GO_HOME
-        * wx.ART_FILE_OPEN
-        * wx.ART_PRINT
-        * wx.ART_HELP
-        * wx.ART_TIP
-        * wx.ART_REPORT_VIEW
-        * wx.ART_LIST_VIEW
-        * wx.ART_NEW_DIR
-        * wx.ART_FOLDER
-        * wx.ART_GO_DIR_UP
-        * wx.ART_EXECUTABLE_FILE
-        * wx.ART_NORMAL_FILE
-        * wx.ART_TICK_MARK
-        * wx.ART_CROSS_MARK
-        * wx.ART_ERROR
-        * wx.ART_QUESTION
-        * wx.ART_WARNING
-        * wx.ART_INFORMATION
-        * wx.ART_MISSING_IMAGE 
-
-
-    Clients
-    -------
-
-    The Client is the entity that calls wx.ArtProvider's `GetBitmap` or
-    `GetIcon` function.  Client IDs server as a hint to wx.ArtProvider
-    that is supposed to help it to choose the best looking bitmap. For
-    example it is often desirable to use slightly different icons in menus
-    and toolbars even though they represent the same action (e.g.
-    wx.ART_FILE_OPEN). Remember that this is really only a hint for
-    wx.ArtProvider -- it is common that `wx.ArtProvider.GetBitmap` returns
-    identical bitmap for different client values!
-
-        * wx.ART_TOOLBAR
-        * wx.ART_MENU
-        * wx.ART_FRAME_ICON
-        * wx.ART_CMN_DIALOG
-        * wx.ART_HELP_BROWSER
-        * wx.ART_MESSAGE_BOX
-        * wx.ART_OTHER (used for all requests that don't fit into any
-          of the categories above)
-
     """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxPyArtProvider instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
@@ -2429,68 +2374,6 @@ class ArtProvider(object):
                     ...
                     return bmp
 
-
-        Identifying art resources
-        -------------------------
-
-        Every bitmap is known to wx.ArtProvider under an unique ID that is
-        used when requesting a resource from it. The IDs can have one of these
-        predefined values:
-
-            * wx.ART_ADD_BOOKMARK
-            * wx.ART_DEL_BOOKMARK
-            * wx.ART_HELP_SIDE_PANEL
-            * wx.ART_HELP_SETTINGS
-            * wx.ART_HELP_BOOK
-            * wx.ART_HELP_FOLDER
-            * wx.ART_HELP_PAGE
-            * wx.ART_GO_BACK
-            * wx.ART_GO_FORWARD
-            * wx.ART_GO_UP
-            * wx.ART_GO_DOWN
-            * wx.ART_GO_TO_PARENT
-            * wx.ART_GO_HOME
-            * wx.ART_FILE_OPEN
-            * wx.ART_PRINT
-            * wx.ART_HELP
-            * wx.ART_TIP
-            * wx.ART_REPORT_VIEW
-            * wx.ART_LIST_VIEW
-            * wx.ART_NEW_DIR
-            * wx.ART_FOLDER
-            * wx.ART_GO_DIR_UP
-            * wx.ART_EXECUTABLE_FILE
-            * wx.ART_NORMAL_FILE
-            * wx.ART_TICK_MARK
-            * wx.ART_CROSS_MARK
-            * wx.ART_ERROR
-            * wx.ART_QUESTION
-            * wx.ART_WARNING
-            * wx.ART_INFORMATION
-            * wx.ART_MISSING_IMAGE 
-
-
-        Clients
-        -------
-
-        The Client is the entity that calls wx.ArtProvider's `GetBitmap` or
-        `GetIcon` function.  Client IDs server as a hint to wx.ArtProvider
-        that is supposed to help it to choose the best looking bitmap. For
-        example it is often desirable to use slightly different icons in menus
-        and toolbars even though they represent the same action (e.g.
-        wx.ART_FILE_OPEN). Remember that this is really only a hint for
-        wx.ArtProvider -- it is common that `wx.ArtProvider.GetBitmap` returns
-        identical bitmap for different client values!
-
-            * wx.ART_TOOLBAR
-            * wx.ART_MENU
-            * wx.ART_FRAME_ICON
-            * wx.ART_CMN_DIALOG
-            * wx.ART_HELP_BROWSER
-            * wx.ART_MESSAGE_BOX
-            * wx.ART_OTHER (used for all requests that don't fit into any
-              of the categories above)
-
         """
         newobj = _misc_.new_ArtProvider(*args, **kwargs)
         self.this = newobj.this
@@ -2652,23 +2535,22 @@ CONFIG_USE_NO_ESCAPE_CHARACTERS = _misc_.CONFIG_USE_NO_ESCAPE_CHARACTERS
 class ConfigBase(object):
     """
     wx.ConfigBase class defines the basic interface of all config
-    classes. It can not be used by itself (it is an abstract base
-    class) and you will always use one of its derivations: wx.Config
-    or wx.FileConfig.
-
-    wx.ConfigBase organizes the items in a tree-like structure,
-    modeled after the Unix/Dos filesystem. There are groups that act
-    like directories and entries, key/value pairs that act like
-    files.  There is always one current group given by the current
-    path.  As in the file system case, to specify a key in the config
-    class you must use a path to it.  Config classes also support the
-    notion of the current group, which makes it possible to use
-    relative paths.
+    classes. It can not be used by itself (it is an abstract base class)
+    and you will always use one of its derivations: wx.Config or
+    wx.FileConfig.
+
+    wx.ConfigBase organizes the items in a tree-like structure, modeled
+    after the Unix/Dos filesystem. There are groups that act like
+    directories and entries, key/value pairs that act like files.  There
+    is always one current group given by the current path.  As in the file
+    system case, to specify a key in the config class you must use a path
+    to it.  Config classes also support the notion of the current group,
+    which makes it possible to use relative paths.
 
     Keys are pairs "key_name = value" where value may be of string,
     integer floating point or boolean, you can not store binary data
-    without first encoding it as a string.  For performance reasons
-    items should be kept small, no more than a couple kilobytes.
+    without first encoding it as a string.  For performance reasons items
+    should be kept small, no more than a couple kilobytes.
 
     """
     def __init__(self): raise RuntimeError, "No constructor defined"
@@ -2689,8 +2571,8 @@ class ConfigBase(object):
         """
         Set(ConfigBase config) -> ConfigBase
 
-        Sets the global config object (the one returned by Get) and
-        returns a reference to the previous global config object.
+        Sets the global config object (the one returned by Get) and returns a
+        reference to the previous global config object.
         """
         return _misc_.ConfigBase_Set(*args, **kwargs)
 
@@ -2719,7 +2601,8 @@ class ConfigBase(object):
         """
         DontCreateOnDemand()
 
-        Should Get() try to create a new log object if there isn't a current one?
+        Should Get() try to create a new log object if there isn't a current
+        one?
         """
         return _misc_.ConfigBase_DontCreateOnDemand(*args, **kwargs)
 
@@ -2728,9 +2611,9 @@ class ConfigBase(object):
         """
         SetPath(self, String path)
 
-        Set current path: if the first character is '/', it's the absolute path,
-        otherwise it's a relative path. '..' is supported. If the strPath
-        doesn't exist it is created.
+        Set current path: if the first character is '/', it's the absolute
+        path, otherwise it's a relative path. '..' is supported. If the
+        strPath doesn't exist it is created.
         """
         return _misc_.ConfigBase_SetPath(*args, **kwargs)
 
@@ -2746,10 +2629,10 @@ class ConfigBase(object):
         """
         GetFirstGroup() -> (more, value, index)
 
-        Allows enumerating the subgroups in a config object.  Returns
-        a tuple containing a flag indicating there are more items, the
-        name of the current item, and an index to pass to GetNextGroup to
-        fetch the next item.
+        Allows enumerating the subgroups in a config object.  Returns a tuple
+        containing a flag indicating there are more items, the name of the
+        current item, and an index to pass to GetNextGroup to fetch the next
+        item.
         """
         return _misc_.ConfigBase_GetFirstGroup(*args, **kwargs)
 
@@ -2757,10 +2640,10 @@ class ConfigBase(object):
         """
         GetNextGroup(long index) -> (more, value, index)
 
-        Allows enumerating the subgroups in a config object.  Returns
-        a tuple containing a flag indicating there are more items, the
-        name of the current item, and an index to pass to GetNextGroup to
-        fetch the next item.
+        Allows enumerating the subgroups in a config object.  Returns a tuple
+        containing a flag indicating there are more items, the name of the
+        current item, and an index to pass to GetNextGroup to fetch the next
+        item.
         """
         return _misc_.ConfigBase_GetNextGroup(*args, **kwargs)
 
@@ -2769,8 +2652,8 @@ class ConfigBase(object):
         GetFirstEntry() -> (more, value, index)
 
         Allows enumerating the entries in the current group in a config
-        object.  Returns a tuple containing a flag indicating there are
-        more items, the name of the current item, and an index to pass to
+        object.  Returns a tuple containing a flag indicating there are more
+        items, the name of the current item, and an index to pass to
         GetNextGroup to fetch the next item.
         """
         return _misc_.ConfigBase_GetFirstEntry(*args, **kwargs)
@@ -2780,8 +2663,8 @@ class ConfigBase(object):
         GetNextEntry(long index) -> (more, value, index)
 
         Allows enumerating the entries in the current group in a config
-        object.  Returns a tuple containing a flag indicating there are
-        more items, the name of the current item, and an index to pass to
+        object.  Returns a tuple containing a flag indicating there are more
+        items, the name of the current item, and an index to pass to
         GetNextGroup to fetch the next item.
         """
         return _misc_.ConfigBase_GetNextEntry(*args, **kwargs)
@@ -2790,8 +2673,8 @@ class ConfigBase(object):
         """
         GetNumberOfEntries(self, bool recursive=False) -> size_t
 
-        Get the number of entries in the current group, with or
-        without its subgroups.
+        Get the number of entries in the current group, with or without its
+        subgroups.
         """
         return _misc_.ConfigBase_GetNumberOfEntries(*args, **kwargs)
 
@@ -2799,8 +2682,8 @@ class ConfigBase(object):
         """
         GetNumberOfGroups(self, bool recursive=False) -> size_t
 
-        Get the number of subgroups in the current group, with or
-        without its subgroups.
+        Get the number of subgroups in the current group, with or without its
+        subgroups.
         """
         return _misc_.ConfigBase_GetNumberOfGroups(*args, **kwargs)
 
@@ -2921,7 +2804,7 @@ class ConfigBase(object):
         """
         RenameGroup(self, String oldName, String newName) -> bool
 
-        Rename aa group.  Returns False on failure (probably because the new
+        Rename a group.  Returns False on failure (probably because the new
         name is already taken by an existing entry)
         """
         return _misc_.ConfigBase_RenameGroup(*args, **kwargs)
@@ -2930,8 +2813,8 @@ class ConfigBase(object):
         """
         DeleteEntry(self, String key, bool deleteGroupIfEmpty=True) -> bool
 
-        Deletes the specified entry and the group it belongs to if
-        it was the last key in it and the second parameter is True
+        Deletes the specified entry and the group it belongs to if it was the
+        last key in it and the second parameter is True
         """
         return _misc_.ConfigBase_DeleteEntry(*args, **kwargs)
 
@@ -2956,8 +2839,9 @@ class ConfigBase(object):
         """
         SetExpandEnvVars(self, bool doIt=True)
 
-        We can automatically expand environment variables in the config entries
-        (this option is on by default, you can turn it on/off at any time)
+        We can automatically expand environment variables in the config
+        entries this option is on by default, you can turn it on/off at any
+        time)
         """
         return _misc_.ConfigBase_SetExpandEnvVars(*args, **kwargs)
 
@@ -3029,8 +2913,8 @@ def ConfigBase_Set(*args, **kwargs):
     """
     ConfigBase_Set(ConfigBase config) -> ConfigBase
 
-    Sets the global config object (the one returned by Get) and
-    returns a reference to the previous global config object.
+    Sets the global config object (the one returned by Get) and returns a
+    reference to the previous global config object.
     """
     return _misc_.ConfigBase_Set(*args, **kwargs)
 
@@ -3056,7 +2940,8 @@ def ConfigBase_DontCreateOnDemand(*args, **kwargs):
     """
     ConfigBase_DontCreateOnDemand()
 
-    Should Get() try to create a new log object if there isn't a current one?
+    Should Get() try to create a new log object if there isn't a current
+    one?
     """
     return _misc_.ConfigBase_DontCreateOnDemand(*args, **kwargs)
 
@@ -3121,10 +3006,10 @@ _misc_.FileConfig_swigregister(FileConfigPtr)
 
 class ConfigPathChanger(object):
     """
-    A handy little class which changes current path to the path of
-    given entry and restores it in the destructoir: so if you declare
-    a local variable of this type, you work in the entry directory
-    and the path is automatically restored when the function returns.
+    A handy little class which changes current path to the path of given
+    entry and restores it in the destructoir: so if you declare a local
+    variable of this type, you work in the entry directory and the path is
+    automatically restored when the function returns.
     """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxConfigPathChanger instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
@@ -3162,9 +3047,9 @@ def ExpandEnvVars(*args, **kwargs):
     ExpandEnvVars(String sz) -> String
 
     Replace environment variables ($SOMETHING) with their values. The
-    format is $VARNAME or ${VARNAME} where VARNAME contains
-    alphanumeric characters and '_' only. '$' must be escaped ('\$')
-    in order to be taken literally.
+    format is $VARNAME or ${VARNAME} where VARNAME contains alphanumeric
+    characters and '_' only. '$' must be escaped ('\$') in order to be
+    taken literally.
     """
     return _misc_.ExpandEnvVars(*args, **kwargs)
 #---------------------------------------------------------------------------
@@ -3388,11 +3273,7 @@ class DateTime(object):
 
     GetWeekDayName = staticmethod(GetWeekDayName)
     def GetAmPmStrings(*args, **kwargs):
-        """
-        GetAmPmStrings() -> (am, pm)
-
-        Get the AM and PM strings in the current locale (may be empty)
-        """
+        """GetAmPmStrings() -> (am, pm)"""
         return _misc_.DateTime_GetAmPmStrings(*args, **kwargs)
 
     GetAmPmStrings = staticmethod(GetAmPmStrings)
@@ -3866,11 +3747,7 @@ def DateTime_GetWeekDayName(*args, **kwargs):
     return _misc_.DateTime_GetWeekDayName(*args, **kwargs)
 
 def DateTime_GetAmPmStrings(*args, **kwargs):
-    """
-    GetAmPmStrings() -> (am, pm)
-
-    Get the AM and PM strings in the current locale (may be empty)
-    """
+    """GetAmPmStrings() -> (am, pm)"""
     return _misc_.DateTime_GetAmPmStrings(*args, **kwargs)
 
 def DateTime_IsDSTApplicable(*args, **kwargs):
@@ -4398,14 +4275,11 @@ DF_MAX = _misc_.DF_MAX
 class DataFormat(object):
     """
     A wx.DataFormat is an encapsulation of a platform-specific format
-    handle which is used by the system for the clipboard and drag and
-    drop operations. The applications are usually only interested in,
-    for example, pasting data from the clipboard only if the data is
-    in a format the program understands.  A data format is is used to
-    uniquely identify this format.
-
-    On the system level, a data format is usually just a number
-    (CLIPFORMAT under Windows or Atom under X11, for example).
+    handle which is used by the system for the clipboard and drag and drop
+    operations. The applications are usually only interested in, for
+    example, pasting data from the clipboard only if the data is in a
+    format the program understands.  A data format is is used to uniquely
+    identify this format.
     """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxDataFormat instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
@@ -4413,9 +4287,8 @@ class DataFormat(object):
         """
         __init__(self, int type) -> DataFormat
 
-        Constructs a data format object for one of the standard data
-        formats or an empty data object (use SetType or SetId later in
-        this case)
+        Constructs a data format object for one of the standard data formats
+        or an empty data object (use SetType or SetId later in this case)
         """
         newobj = _misc_.new_DataFormat(*args, **kwargs)
         self.this = newobj.this
@@ -4445,7 +4318,8 @@ class DataFormat(object):
         """
         SetType(self, int format)
 
-        Sets the format to the given value, which should be one of wx.DF_XXX constants.
+        Sets the format to the given value, which should be one of wx.DF_XXX
+        constants.
         """
         return _misc_.DataFormat_SetType(*args, **kwargs)
 
@@ -4461,7 +4335,8 @@ class DataFormat(object):
         """
         GetId(self) -> String
 
-        Returns the name of a custom format (this function will fail for a standard format).
+        Returns the name of a custom format (this function will fail for a
+        standard format).
         """
         return _misc_.DataFormat_GetId(*args, **kwargs)
 
@@ -4486,13 +4361,28 @@ def CustomDataFormat(*args, **kwargs):
     """
     CustomDataFormat(String format) -> DataFormat
 
-    Constructs a data format object for a custom format identified by its name.
+    Constructs a data format object for a custom format identified by its
+    name.
     """
     val = _misc_.new_CustomDataFormat(*args, **kwargs)
     val.thisown = 1
     return val
 
 class DataObject(object):
+    """
+    A wx.DataObject represents data that can be copied to or from the
+    clipboard, or dragged and dropped. The important thing about
+    wx.DataObject is that this is a 'smart' piece of data unlike usual
+    'dumb' data containers such as memory buffers or files. Being 'smart'
+    here means that the data object itself should know what data formats
+    it supports and how to render itself in each of supported formats.
+
+    **NOTE**: This class is an abstract base class and can not be used
+    directly from Python.  If you need a custom type of data object then
+    you should instead derive from `wx.PyDataObjectSimple` or use
+    `wx.CustomDataObject`.
+
+    """
     def __init__(self): raise RuntimeError, "No constructor defined"
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxDataObject instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
@@ -4506,31 +4396,65 @@ class DataObject(object):
         except: pass
 
     def GetPreferredFormat(*args, **kwargs):
-        """GetPreferredFormat(self, int dir=Get) -> DataFormat"""
+        """
+        GetPreferredFormat(self, int dir=Get) -> DataFormat
+
+        Returns the preferred format for either rendering the data (if dir is
+        Get, its default value) or for setting it. Usually this will be the
+        native format of the wx.DataObject.
+        """
         return _misc_.DataObject_GetPreferredFormat(*args, **kwargs)
 
     def GetFormatCount(*args, **kwargs):
-        """GetFormatCount(self, int dir=Get) -> size_t"""
+        """
+        GetFormatCount(self, int dir=Get) -> size_t
+
+        Returns the number of available formats for rendering or setting the
+        data.
+        """
         return _misc_.DataObject_GetFormatCount(*args, **kwargs)
 
     def IsSupported(*args, **kwargs):
-        """IsSupported(self, DataFormat format, int dir=Get) -> bool"""
+        """
+        IsSupported(self, DataFormat format, int dir=Get) -> bool
+
+        Returns True if this format is supported.
+        """
         return _misc_.DataObject_IsSupported(*args, **kwargs)
 
     def GetDataSize(*args, **kwargs):
-        """GetDataSize(self, DataFormat format) -> size_t"""
+        """
+        GetDataSize(self, DataFormat format) -> size_t
+
+        Get the (total) size of data for the given format
+        """
         return _misc_.DataObject_GetDataSize(*args, **kwargs)
 
     def GetAllFormats(*args, **kwargs):
-        """GetAllFormats(self, DataFormat formats, int dir=Get)"""
+        """
+        GetAllFormats(self, int dir=Get) -> [formats]
+
+        Returns a list of all the wx.DataFormats that this dataobject supports
+        in the given direction.
+        """
         return _misc_.DataObject_GetAllFormats(*args, **kwargs)
 
     def GetDataHere(*args, **kwargs):
-        """GetDataHere(self, DataFormat format, void buf) -> bool"""
+        """
+        GetDataHere(self, DataFormat format) -> String
+
+        Get the data bytes in the specified format, returns None on failure.
+
+        """
         return _misc_.DataObject_GetDataHere(*args, **kwargs)
 
     def SetData(*args, **kwargs):
-        """SetData(self, DataFormat format, size_t len, void buf) -> bool"""
+        """
+        SetData(self, DataFormat format, String data) -> bool
+
+        Set the data in the specified format from the bytes in the the data string.
+
+        """
         return _misc_.DataObject_SetData(*args, **kwargs)
 
 
@@ -4543,22 +4467,73 @@ _misc_.DataObject_swigregister(DataObjectPtr)
 FormatInvalid = cvar.FormatInvalid
 
 class DataObjectSimple(DataObject):
+    """
+    wx.DataObjectSimple is a `wx.DataObject` which only supports one
+    format.  This is the simplest possible `wx.DataObject` implementation.
+
+    This is still an "abstract base class" meaning that you can't use it
+    directly.  You either need to use one of the predefined base classes,
+    or derive your own class from `wx.PyDataObjectSimple`.
+
+    """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxDataObjectSimple instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
     def __init__(self, *args, **kwargs):
-        """__init__(self, DataFormat format=FormatInvalid) -> DataObjectSimple"""
+        """
+        __init__(self, DataFormat format=FormatInvalid) -> DataObjectSimple
+
+        Constructor accepts the supported format (none by default) which may
+        also be set later with `SetFormat`.
+        """
         newobj = _misc_.new_DataObjectSimple(*args, **kwargs)
         self.this = newobj.this
         self.thisown = 1
         del newobj.thisown
     def GetFormat(*args, **kwargs):
-        """GetFormat(self) -> DataFormat"""
+        """
+        GetFormat(self) -> DataFormat
+
+        Returns the (one and only one) format supported by this object. It is
+        assumed that the format is supported in both directions.
+        """
         return _misc_.DataObjectSimple_GetFormat(*args, **kwargs)
 
     def SetFormat(*args, **kwargs):
-        """SetFormat(self, DataFormat format)"""
+        """
+        SetFormat(self, DataFormat format)
+
+        Sets the supported format.
+        """
         return _misc_.DataObjectSimple_SetFormat(*args, **kwargs)
 
+    def GetDataSize(*args, **kwargs):
+        """
+        GetDataSize(self) -> size_t
+
+        Get the size of our data.
+        """
+        return _misc_.DataObjectSimple_GetDataSize(*args, **kwargs)
+
+    def GetDataHere(*args, **kwargs):
+        """
+        GetDataHere(self) -> String
+
+        Returns the data bytes from the data object as a string, returns None
+        on failure.  Must be implemented in the derived class if the object
+        supports rendering its data.
+        """
+        return _misc_.DataObjectSimple_GetDataHere(*args, **kwargs)
+
+    def SetData(*args, **kwargs):
+        """
+        SetData(self, String data) -> bool
+
+        Copy the data value to the data object.  Must be implemented in the
+        derived class if the object supports setting its data.
+
+        """
+        return _misc_.DataObjectSimple_SetData(*args, **kwargs)
+
 
 class DataObjectSimplePtr(DataObjectSimple):
     def __init__(self, this):
@@ -4568,10 +4543,27 @@ class DataObjectSimplePtr(DataObjectSimple):
 _misc_.DataObjectSimple_swigregister(DataObjectSimplePtr)
 
 class PyDataObjectSimple(DataObjectSimple):
+    """
+    wx.PyDataObjectSimple is a version of `wx.DataObjectSimple` that is
+    Python-aware and knows how to reflect calls to its C++ virtual methods
+    to methods in the Python derived class.  You should derive from this
+    class and overload `GetDataSize`, `GetDataHere` and `SetData` when you
+    need to create your own simple single-format type of `wx.DataObject`.
+
+    """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxPyDataObjectSimple instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
     def __init__(self, *args, **kwargs):
-        """__init__(self, DataFormat format=FormatInvalid) -> PyDataObjectSimple"""
+        """
+        __init__(self, DataFormat format=FormatInvalid) -> PyDataObjectSimple
+
+        wx.PyDataObjectSimple is a version of `wx.DataObjectSimple` that is
+        Python-aware and knows how to reflect calls to its C++ virtual methods
+        to methods in the Python derived class.  You should derive from this
+        class and overload `GetDataSize`, `GetDataHere` and `SetData` when you
+        need to create your own simple single-format type of `wx.DataObject`.
+
+        """
         newobj = _misc_.new_PyDataObjectSimple(*args, **kwargs)
         self.this = newobj.this
         self.thisown = 1
@@ -4591,16 +4583,50 @@ class PyDataObjectSimplePtr(PyDataObjectSimple):
 _misc_.PyDataObjectSimple_swigregister(PyDataObjectSimplePtr)
 
 class DataObjectComposite(DataObject):
+    """
+    wx.DataObjectComposite is the simplest `wx.DataObject` derivation
+    which may be sued to support multiple formats. It contains several
+    'wx.DataObjectSimple` objects and supports any format supported by at
+    least one of them. Only one of these data objects is *preferred* (the
+    first one if not explicitly changed by using the second parameter of
+    `Add`) and its format determines the preferred format of the composite
+    data object as well.
+
+    See `wx.DataObject` documentation for the reasons why you might prefer
+    to use wx.DataObject directly instead of wx.DataObjectComposite for
+    efficiency reasons.
+
+    """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxDataObjectComposite instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
     def __init__(self, *args, **kwargs):
-        """__init__(self) -> DataObjectComposite"""
+        """
+        __init__(self) -> DataObjectComposite
+
+        wx.DataObjectComposite is the simplest `wx.DataObject` derivation
+        which may be sued to support multiple formats. It contains several
+        'wx.DataObjectSimple` objects and supports any format supported by at
+        least one of them. Only one of these data objects is *preferred* (the
+        first one if not explicitly changed by using the second parameter of
+        `Add`) and its format determines the preferred format of the composite
+        data object as well.
+
+        See `wx.DataObject` documentation for the reasons why you might prefer
+        to use wx.DataObject directly instead of wx.DataObjectComposite for
+        efficiency reasons.
+
+        """
         newobj = _misc_.new_DataObjectComposite(*args, **kwargs)
         self.this = newobj.this
         self.thisown = 1
         del newobj.thisown
     def Add(*args, **kwargs):
-        """Add(self, DataObjectSimple dataObject, int preferred=False)"""
+        """
+        Add(self, DataObjectSimple dataObject, bool preferred=False)
+
+        Adds the dataObject to the list of supported objects and it becomes
+        the preferred object if preferred is True.
+        """
         return _misc_.DataObjectComposite_Add(*args, **kwargs)
 
 
@@ -4612,24 +4638,62 @@ class DataObjectCompositePtr(DataObjectComposite):
 _misc_.DataObjectComposite_swigregister(DataObjectCompositePtr)
 
 class TextDataObject(DataObjectSimple):
+    """
+    wx.TextDataObject is a specialization of `wx.DataObject` for text
+    data. It can be used without change to paste data into the `wx.Clipboard`
+    or a `wx.DropSource`.
+
+    Alternativly, you may wish to derive a new class from the
+    `wx.PyTextDataObject` class for providing text on-demand in order to
+    minimize memory consumption when offering data in several formats,
+    such as plain text and RTF, because by default the text is stored in a
+    string in this class, but it might as well be generated on demand when
+    requested. For this, `GetTextLength` and `GetText` will have to be
+    overridden.
+    """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxTextDataObject instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
     def __init__(self, *args, **kwargs):
-        """__init__(self, String text=EmptyString) -> TextDataObject"""
+        """
+        __init__(self, String text=EmptyString) -> TextDataObject
+
+        Constructor, may be used to initialise the text (otherwise `SetText`
+        should be used later).
+        """
         newobj = _misc_.new_TextDataObject(*args, **kwargs)
         self.this = newobj.this
         self.thisown = 1
         del newobj.thisown
     def GetTextLength(*args, **kwargs):
-        """GetTextLength(self) -> size_t"""
+        """
+        GetTextLength(self) -> size_t
+
+        Returns the data size.  By default, returns the size of the text data
+        set in the constructor or using `SetText`.  This can be overridden (via
+        `wx.PyTextDataObject`) to provide text size data on-demand. It is
+        recommended to return the text length plus 1 for a trailing zero, but
+        this is not strictly required.
+        """
         return _misc_.TextDataObject_GetTextLength(*args, **kwargs)
 
     def GetText(*args, **kwargs):
-        """GetText(self) -> String"""
+        """
+        GetText(self) -> String
+
+        Returns the text associated with the data object.
+        """
         return _misc_.TextDataObject_GetText(*args, **kwargs)
 
     def SetText(*args, **kwargs):
-        """SetText(self, String text)"""
+        """
+        SetText(self, String text)
+
+        Sets the text associated with the data object. This method is called
+        when the data object receives the data and, by default, copies the
+        text into the member variable. If you want to process the text on the
+        fly you may wish to override this function (via
+        `wx.PyTextDataObject`.)
+        """
         return _misc_.TextDataObject_SetText(*args, **kwargs)
 
 
@@ -4641,10 +4705,27 @@ class TextDataObjectPtr(TextDataObject):
 _misc_.TextDataObject_swigregister(TextDataObjectPtr)
 
 class PyTextDataObject(TextDataObject):
+    """
+    wx.PyTextDataObject is a version of `wx.TextDataObject` that is
+    Python-aware and knows how to reflect calls to its C++ virtual methods
+    to methods in the Python derived class.  You should derive from this
+    class and overload `GetTextLength`, `GetText`, and `SetText` when you
+    want to be able to provide text on demand instead of preloading it
+    into the data object.
+    """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxPyTextDataObject instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
     def __init__(self, *args, **kwargs):
-        """__init__(self, String text=EmptyString) -> PyTextDataObject"""
+        """
+        __init__(self, String text=EmptyString) -> PyTextDataObject
+
+        wx.PyTextDataObject is a version of `wx.TextDataObject` that is
+        Python-aware and knows how to reflect calls to its C++ virtual methods
+        to methods in the Python derived class.  You should derive from this
+        class and overload `GetTextLength`, `GetText`, and `SetText` when you
+        want to be able to provide text on demand instead of preloading it
+        into the data object.
+        """
         newobj = _misc_.new_PyTextDataObject(*args, **kwargs)
         self.this = newobj.this
         self.thisown = 1
@@ -4664,20 +4745,45 @@ class PyTextDataObjectPtr(PyTextDataObject):
 _misc_.PyTextDataObject_swigregister(PyTextDataObjectPtr)
 
 class BitmapDataObject(DataObjectSimple):
+    """
+    wx.BitmapDataObject is a specialization of wxDataObject for bitmap
+    data. It can be used without change to paste data into the `wx.Clipboard`
+    or a `wx.DropSource`.
+
+    """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxBitmapDataObject instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
     def __init__(self, *args, **kwargs):
-        """__init__(self, Bitmap bitmap=wxNullBitmap) -> BitmapDataObject"""
+        """
+        __init__(self, Bitmap bitmap=wxNullBitmap) -> BitmapDataObject
+
+        Constructor, optionally passing a bitmap (otherwise use `SetBitmap`
+        later).
+        """
         newobj = _misc_.new_BitmapDataObject(*args, **kwargs)
         self.this = newobj.this
         self.thisown = 1
         del newobj.thisown
     def GetBitmap(*args, **kwargs):
-        """GetBitmap(self) -> Bitmap"""
+        """
+        GetBitmap(self) -> Bitmap
+
+        Returns the bitmap associated with the data object.  You may wish to
+        override this method (by deriving from `wx.PyBitmapDataObject`) when
+        offering data on-demand, but this is not required by wxWidgets'
+        internals. Use this method to get data in bitmap form from the
+        `wx.Clipboard`.
+        """
         return _misc_.BitmapDataObject_GetBitmap(*args, **kwargs)
 
     def SetBitmap(*args, **kwargs):
-        """SetBitmap(self, Bitmap bitmap)"""
+        """
+        SetBitmap(self, Bitmap bitmap)
+
+        Sets the bitmap associated with the data object. This method is called
+        when the data object receives data. Usually there will be no reason to
+        override this function.
+        """
         return _misc_.BitmapDataObject_SetBitmap(*args, **kwargs)
 
 
@@ -4689,10 +4795,23 @@ class BitmapDataObjectPtr(BitmapDataObject):
 _misc_.BitmapDataObject_swigregister(BitmapDataObjectPtr)
 
 class PyBitmapDataObject(BitmapDataObject):
+    """
+    wx.PyBitmapDataObject is a version of `wx.BitmapDataObject` that is
+    Python-aware and knows how to reflect calls to its C++ virtual methods
+    to methods in the Python derived class. To be able to provide bitmap
+    data on demand derive from this class and overload `GetBitmap`.
+    """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxPyBitmapDataObject instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
     def __init__(self, *args, **kwargs):
-        """__init__(self, Bitmap bitmap=wxNullBitmap) -> PyBitmapDataObject"""
+        """
+        __init__(self, Bitmap bitmap=wxNullBitmap) -> PyBitmapDataObject
+
+        wx.PyBitmapDataObject is a version of `wx.BitmapDataObject` that is
+        Python-aware and knows how to reflect calls to its C++ virtual methods
+        to methods in the Python derived class. To be able to provide bitmap
+        data on demand derive from this class and overload `GetBitmap`.
+        """
         newobj = _misc_.new_PyBitmapDataObject(*args, **kwargs)
         self.this = newobj.this
         self.thisown = 1
@@ -4712,6 +4831,20 @@ class PyBitmapDataObjectPtr(PyBitmapDataObject):
 _misc_.PyBitmapDataObject_swigregister(PyBitmapDataObjectPtr)
 
 class FileDataObject(DataObjectSimple):
+    """
+    wx.FileDataObject is a specialization of `wx.DataObjectSimple` for
+    file names. The program works with it just as if it were a list of
+    absolute file names, but internally it uses the same format as
+    Explorer and other compatible programs under Windows or GNOME/KDE
+    filemanager under Unix which makes it possible to receive files from
+    them using this class.
+
+    :Warning: Under all non-Windows platforms this class is currently
+        "input-only", i.e. you can receive the files from another
+        application, but copying (or dragging) file(s) from a wxWidgets
+        application is not currently supported.
+
+    """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxFileDataObject instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
     def __init__(self, *args, **kwargs):
@@ -4721,11 +4854,15 @@ class FileDataObject(DataObjectSimple):
         self.thisown = 1
         del newobj.thisown
     def GetFilenames(*args, **kwargs):
-        """GetFilenames(self) -> wxArrayString"""
+        """GetFilenames(self) -> [names]"""
         return _misc_.FileDataObject_GetFilenames(*args, **kwargs)
 
     def AddFile(*args, **kwargs):
-        """AddFile(self, String filename)"""
+        """
+        AddFile(self, String filename)
+
+        Adds a file to the list of files represented by this data object.
+        """
         return _misc_.FileDataObject_AddFile(*args, **kwargs)
 
 
@@ -4737,28 +4874,52 @@ class FileDataObjectPtr(FileDataObject):
 _misc_.FileDataObject_swigregister(FileDataObjectPtr)
 
 class CustomDataObject(DataObjectSimple):
+    """
+    wx.CustomDataObject is a specialization of `wx.DataObjectSimple` for
+    some application-specific data in arbitrary format.  Python strings
+    are used for getting and setting data, but any picklable object can
+    easily be transfered via strings.  A copy of the data is stored in the
+    data object.
+    """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxCustomDataObject instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
     def __init__(self, *args, **kwargs):
-        """__init__(self, DataFormat format=FormatInvalid) -> CustomDataObject"""
+        """
+        __init__(self, DataFormat format=FormatInvalid) -> CustomDataObject
+
+        wx.CustomDataObject is a specialization of `wx.DataObjectSimple` for
+        some application-specific data in arbitrary format.  Python strings
+        are used for getting and setting data, but any picklable object can
+        easily be transfered via strings.  A copy of the data is stored in the
+        data object.
+        """
         newobj = _misc_.new_CustomDataObject(*args, **kwargs)
         self.this = newobj.this
         self.thisown = 1
         del newobj.thisown
-    def TakeData(*args, **kwargs):
-        """TakeData(self, PyObject data)"""
-        return _misc_.CustomDataObject_TakeData(*args, **kwargs)
-
     def SetData(*args, **kwargs):
-        """SetData(self, PyObject data) -> bool"""
+        """
+        SetData(self, String data) -> bool
+
+        Copy the data value to the data object.
+        """
         return _misc_.CustomDataObject_SetData(*args, **kwargs)
 
+    TakeData = SetData 
     def GetSize(*args, **kwargs):
-        """GetSize(self) -> size_t"""
+        """
+        GetSize(self) -> size_t
+
+        Get the size of the data.
+        """
         return _misc_.CustomDataObject_GetSize(*args, **kwargs)
 
     def GetData(*args, **kwargs):
-        """GetData(self) -> PyObject"""
+        """
+        GetData(self) -> String
+
+        Returns the data bytes from the data object as a string.
+        """
         return _misc_.CustomDataObject_GetData(*args, **kwargs)
 
 
@@ -4770,20 +4931,37 @@ class CustomDataObjectPtr(CustomDataObject):
 _misc_.CustomDataObject_swigregister(CustomDataObjectPtr)
 
 class URLDataObject(DataObjectComposite):
+    """
+    This data object holds a URL in a format that is compatible with some
+    browsers such that it is able to be dragged to or from them.
+    """
     def __repr__(self):
         return "<%s.%s; proxy of C++ wxURLDataObject instance at %s>" % (self.__class__.__module__, self.__class__.__name__, self.this,)
     def __init__(self, *args, **kwargs):
-        """__init__(self) -> URLDataObject"""
+        """
+        __init__(self) -> URLDataObject
+
+        This data object holds a URL in a format that is compatible with some
+        browsers such that it is able to be dragged to or from them.
+        """
         newobj = _misc_.new_URLDataObject(*args, **kwargs)
         self.this = newobj.this
         self.thisown = 1
         del newobj.thisown
     def GetURL(*args, **kwargs):
-        """GetURL(self) -> String"""
+        """
+        GetURL(self) -> String
+
+        Returns a string containing the current URL.
+        """
         return _misc_.URLDataObject_GetURL(*args, **kwargs)
 
     def SetURL(*args, **kwargs):
-        """SetURL(self, String url)"""
+        """
+        SetURL(self, String url)
+
+        Set the URL.
+        """
         return _misc_.URLDataObject_SetURL(*args, **kwargs)
 
 
@@ -5238,8 +5416,8 @@ class VideoMode(object):
         """
         Matches(self, VideoMode other) -> bool
 
-        Returns true if this mode matches the other one in the sense that
-        all non zero fields of the other mode have the same value in this
+        Returns true if this mode matches the other one in the sense that all
+        non zero fields of the other mode have the same value in this
         one (except for refresh which is allowed to have a greater value)
         """
         return _misc_.VideoMode_Matches(*args, **kwargs)
@@ -5248,8 +5426,7 @@ class VideoMode(object):
         """
         GetWidth(self) -> int
 
-        Returns the screen width in pixels (e.g. 640*480), 0 means
-        unspecified
+        Returns the screen width in pixels (e.g. 640*480), 0 means unspecified
         """
         return _misc_.VideoMode_GetWidth(*args, **kwargs)
 
@@ -5266,8 +5443,8 @@ class VideoMode(object):
         """
         GetDepth(self) -> int
 
-        Returns the screen's bits per pixel (e.g. 32), 1 is monochrome
-        and 0 means unspecified/known
+        Returns the screen's bits per pixel (e.g. 32), 1 is monochrome and 0
+        means unspecified/known
         """
         return _misc_.VideoMode_GetDepth(*args, **kwargs)
 
@@ -5308,9 +5485,9 @@ class Display(object):
         """
         __init__(self, size_t index=0) -> Display
 
-        Set up a Display instance with the specified display.  The
-        displays are numbered from 0 to GetCount() - 1, 0 is always the
-        primary display and the only one which is always supported
+        Set up a Display instance with the specified display.  The displays
+        are numbered from 0 to GetCount() - 1, 0 is always the primary display
+        and the only one which is always supported
         """
         newobj = _misc_.new_Display(*args, **kwargs)
         self.this = newobj.this
@@ -5335,8 +5512,8 @@ class Display(object):
         """
         GetFromPoint(Point pt) -> int
 
-        Find the display where the given point lies, return wx.NOT_FOUND
-        if it doesn't belong to any display
+        Find the display where the given point lies, return wx.NOT_FOUND if it
+        doesn't belong to any display
         """
         return _misc_.Display_GetFromPoint(*args, **kwargs)
 
@@ -5345,8 +5522,8 @@ class Display(object):
         """
         GetFromWindow(Window window) -> int
 
-        Find the display where the given window lies, return wx.NOT_FOUND
-        if it is not shown at all.
+        Find the display where the given window lies, return wx.NOT_FOUND if
+        it is not shown at all.
         """
         return _misc_.Display_GetFromWindow(*args, **kwargs)
 
@@ -5364,8 +5541,8 @@ class Display(object):
         """
         GetGeometry(self) -> Rect
 
-        Returns the bounding rectangle of the display whose index was
-        passed to the constructor.
+        Returns the bounding rectangle of the display whose index was passed
+        to the constructor.
         """
         return _misc_.Display_GetGeometry(*args, **kwargs)
 
@@ -5390,14 +5567,13 @@ class Display(object):
         """
         GetModes(VideoMode mode=DefaultVideoMode) -> [videoMode...]
 
-        Enumerate all video modes supported by this display matching the
-        given one (in the sense of VideoMode.Match()).
+        Enumerate all video modes supported by this display matching the given
+        one (in the sense of VideoMode.Match()).
 
-        As any mode matches the default value of the argument and there
-        is always at least one video mode supported by display, the
-        returned array is only empty for the default value of the
-        argument if this function is not supported at all on this
-        platform.
+        As any mode matches the default value of the argument and there is
+        always at least one video mode supported by display, the returned
+        array is only empty for the default value of the argument if this
+        function is not supported at all on this platform.
         """
         return _misc_.Display_GetModes(*args, **kwargs)
 
@@ -5446,8 +5622,8 @@ def Display_GetFromPoint(*args, **kwargs):
     """
     Display_GetFromPoint(Point pt) -> int
 
-    Find the display where the given point lies, return wx.NOT_FOUND
-    if it doesn't belong to any display
+    Find the display where the given point lies, return wx.NOT_FOUND if it
+    doesn't belong to any display
     """
     return _misc_.Display_GetFromPoint(*args, **kwargs)
 
@@ -5455,8 +5631,8 @@ def Display_GetFromWindow(*args, **kwargs):
     """
     Display_GetFromWindow(Window window) -> int
 
-    Find the display where the given window lies, return wx.NOT_FOUND
-    if it is not shown at all.
+    Find the display where the given window lies, return wx.NOT_FOUND if
+    it is not shown at all.
     """
     return _misc_.Display_GetFromWindow(*args, **kwargs)