X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0346c9643464c3a88ea1f3844050df7ed3d9b84f..015fd9ef4833ec3d8b0043a1c7e448c8be4f734a:/wxPython/src/mac/_misc.py diff --git a/wxPython/src/mac/_misc.py b/wxPython/src/mac/_misc.py index 401b6c97da..40b0cd7a8c 100644 --- a/wxPython/src/mac/_misc.py +++ b/wxPython/src/mac/_misc.py @@ -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): @@ -950,7 +957,7 @@ class Timer(_core.EvtHandler): self.this = newobj.this self.thisown = 1 del newobj.thisown - self._setCallbackInfo(self, Timer, 0) + self._setCallbackInfo(self, Timer, 0); self._setOORInfo(self) def __del__(self, destroy=_misc_.delete_Timer): """__del__(self)""" @@ -966,6 +973,10 @@ class Timer(_core.EvtHandler): """SetOwner(self, EvtHandler owner, int id=-1)""" return _misc_.Timer_SetOwner(*args, **kwargs) + def GetOwner(*args, **kwargs): + """GetOwner(self) -> EvtHandler""" + return _misc_.Timer_GetOwner(*args, **kwargs) + def Start(*args, **kwargs): """Start(self, int milliseconds=-1, bool oneShot=False) -> bool""" return _misc_.Timer_Start(*args, **kwargs) @@ -2339,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,) @@ -2425,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 @@ -2648,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" @@ -2685,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) @@ -2715,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) @@ -2724,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) @@ -2742,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) @@ -2753,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) @@ -2765,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) @@ -2776,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) @@ -2786,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) @@ -2795,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) @@ -2917,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) @@ -2926,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) @@ -2952,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) @@ -3025,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) @@ -3052,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) @@ -3117,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,) @@ -3158,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) #--------------------------------------------------------------------------- @@ -4394,14 +4283,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,) @@ -4409,9 +4295,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 @@ -4441,7 +4326,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) @@ -4457,7 +4343,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) @@ -4482,13 +4369,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,) @@ -4502,31 +4404,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) @@ -4539,22 +4475,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): @@ -4564,10 +4551,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 @@ -4587,16 +4591,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) @@ -4608,24 +4646,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) @@ -4637,10 +4713,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 @@ -4660,20 +4753,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) @@ -4685,10 +4803,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 @@ -4708,6 +4839,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): @@ -4717,11 +4862,19 @@ class FileDataObject(DataObjectSimple): self.thisown = 1 del newobj.thisown def GetFilenames(*args, **kwargs): - """GetFilenames(self) -> wxArrayString""" + """ + GetFilenames(self) -> [names] + + Returns a list of file 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) @@ -4733,28 +4886,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) @@ -4766,20 +4943,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) @@ -5158,6 +5352,15 @@ class Clipboard(_core.Object): """ return _misc_.Clipboard_UsePrimarySelection(*args, **kwargs) + def Get(*args, **kwargs): + """ + Get() -> Clipboard + + Returns global instance (wxTheClipboard) of the object. + """ + return _misc_.Clipboard_Get(*args, **kwargs) + + Get = staticmethod(Get) class ClipboardPtr(Clipboard): def __init__(self, this): @@ -5166,6 +5369,31 @@ class ClipboardPtr(Clipboard): self.__class__ = Clipboard _misc_.Clipboard_swigregister(ClipboardPtr) +def Clipboard_Get(*args, **kwargs): + """ + Clipboard_Get() -> Clipboard + + Returns global instance (wxTheClipboard) of the object. + """ + return _misc_.Clipboard_Get(*args, **kwargs) + +class _wxPyDelayedInitWrapper(object): + def __init__(self, initfunc, *args, **kwargs): + self._initfunc = initfunc + self._args = args + self._kwargs = kwargs + self._instance = None + def _checkInstance(self): + if self._instance is None: + self._instance = self._initfunc(*self._args, **self._kwargs) + def __getattr__(self, name): + self._checkInstance() + return getattr(self._instance, name) + def __repr__(self): + self._checkInstance() + return repr(self._instance) +TheClipboard = _wxPyDelayedInitWrapper(Clipboard.Get) + class ClipboardLocker(object): """ A helpful class for opening the clipboard and automatically @@ -5206,7 +5434,6 @@ class ClipboardLockerPtr(ClipboardLocker): if not hasattr(self,"thisown"): self.thisown = 0 self.__class__ = ClipboardLocker _misc_.ClipboardLocker_swigregister(ClipboardLockerPtr) -TheClipboard = cvar.TheClipboard #--------------------------------------------------------------------------- @@ -5234,8 +5461,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) @@ -5244,8 +5471,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) @@ -5262,8 +5488,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) @@ -5304,9 +5530,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 @@ -5331,8 +5557,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) @@ -5341,8 +5567,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) @@ -5360,8 +5586,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) @@ -5386,14 +5612,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) @@ -5442,8 +5667,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) @@ -5451,8 +5676,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)