From: Robin Dunn Date: Fri, 30 Apr 2004 06:14:22 +0000 (+0000) Subject: Docstring updates and tweaks for epydoc X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/dce2bd223c2370f001f9ca93e04cbd437ff3f988 Docstring updates and tweaks for epydoc git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@27016 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/wxPython/src/_accel.i b/wxPython/src/_accel.i index 28e6c5bad2..40eade94d6 100644 --- a/wxPython/src/_accel.i +++ b/wxPython/src/_accel.i @@ -30,35 +30,97 @@ //--------------------------------------------------------------------------- %newgroup; +DocStr(wxAcceleratorEntry, +"A class used to define items in an `wx.AcceleratorTable`. wxPython +programs can choose to use wx.AcceleratorEntry objects, but using a +list of 3-tuple of integers (flags, keyCode, cmdID) usually works just +as well. See `__init__` for details of the tuple values. + +:see: `wx.AcceleratorTable`"); class wxAcceleratorEntry { public: - wxAcceleratorEntry(int flags = 0, int keyCode = 0, int cmd = 0, wxMenuItem *item = NULL); + DocCtorStr( + wxAcceleratorEntry(int flags = 0, int keyCode = 0, int cmdID = 0/*, wxMenuItem *menuitem = NULL*/), + "Construct a wx.AcceleratorEntry. + + :param flags: A bitmask of wx.ACCEL_ALT, wx.ACCEL_SHIFT, + wx.ACCEL_CTRL or wx.ACCEL_NORMAL used to specify + which modifier keys are held down. + :param keyCode: The keycode to be detected + :param cmdID: The menu or control command ID to use for the + accellerator event. +"); ~wxAcceleratorEntry(); - void Set(int flags, int keyCode, int cmd, wxMenuItem *item = NULL); + DocDeclStr( + void , Set(int flags, int keyCode, int cmd/*, wxMenuItem *menuItem = NULL*/), + "(Re)set the attributes of a wx.AcceleratorEntry. +:see `__init__`"); + + +// void SetMenuItem(wxMenuItem *item); +// wxMenuItem *GetMenuItem() const; + + DocDeclStr( + int , GetFlags(), + "Get the AcceleratorEntry's flags."); + + DocDeclStr( + int , GetKeyCode(), + "Get the AcceleratorEntry's keycode."); + + DocDeclStr( + int , GetCommand(), + "Get the AcceleratorEntry's command ID."); +}; + - void SetMenuItem(wxMenuItem *item); - wxMenuItem *GetMenuItem() const; - int GetFlags(); - int GetKeyCode(); - int GetCommand(); -}; +DocStr(wxAcceleratorTable, +"An accelerator table allows the application to specify a table of +keyboard shortcuts for menus or other commands. On Windows, menu or +button commands are supported; on GTK, only menu commands are +supported. + +The object ``wx.NullAcceleratorTable`` is defined to be a table with +no data, and is the initial accelerator table for a window. + +An accelerator takes precedence over normal processing and can be a +convenient way to program some event handling. For example, you can +use an accelerator table to make a hotkey generate an event no matter +which window within a frame has the focus. + +Foe example:: + + aTable = wx.AcceleratorTable([(wx.ACCEL_ALT, ord('X'), exitID), + (wx.ACCEL_CTRL, ord('H'), helpID), + (wx.ACCEL_CTRL, ord('F'), findID), + (wx.ACCEL_NORMAL, wx.WXK_F3, findnextID) + ]) + self.SetAcceleratorTable(aTable) + + +:see: `wx.AcceleratorEntry`, `wx.Window.SetAcceleratorTable` +"); + class wxAcceleratorTable : public wxObject { public: DocAStr(wxAcceleratorTable, "__init__(entries) -> AcceleratorTable", - "Construct an AcceleratorTable from a list of AcceleratorEntry items or\n" - "3-tuples (flags, keyCode, cmdID)"); + "Construct an AcceleratorTable from a list of `wx.AcceleratorEntry` +items or or of 3-tuples (flags, keyCode, cmdID) + +:see: `wx.AcceleratorEntry`"); wxAcceleratorTable(int n, const wxAcceleratorEntry* entries); ~wxAcceleratorTable(); bool Ok() const; }; + %immutable; // See also wxPy_ReinitStockObjects in helpers.cpp diff --git a/wxPython/src/_app.i b/wxPython/src/_app.i index ce26488679..b5f9b7fbe1 100644 --- a/wxPython/src/_app.i +++ b/wxPython/src/_app.i @@ -40,6 +40,9 @@ enum +DocStr(wxPyApp, +"The ``wx.PyApp`` class is an *implementation detail*, please use the +`wx.App` class (or some other derived class) instead."); class wxPyApp : public wxEvtHandler { public: @@ -67,73 +70,81 @@ public: "Get the application name."); DocDeclStr( void, SetAppName(const wxString& name), - "Set the application name. This value may be used automatically\n" - "by wx.Config and such."); + "Set the application name. This value may be used automatically by +`wx.Config` and such."); DocDeclStr( wxString, GetClassName() const, "Get the application's class name."); DocDeclStr( void, SetClassName(const wxString& name), - "Set the application's class name. This value may be used for X-resources if\n" - "applicable for the platform"); + "Set the application's class name. This value may be used for +X-resources if applicable for the platform"); DocDeclStr( const wxString&, GetVendorName() const, "Get the application's vendor name."); DocDeclStr( void, SetVendorName(const wxString& name), - "Set the application's vendor name. This value may be used automatically\n" - "by wx.Config and such."); + "Set the application's vendor name. This value may be used +automatically by `wx.Config` and such."); DocDeclStr( wxAppTraits*, GetTraits(), - "Create the app traits object to which we delegate for everything which either\n" - "should be configurable by the user (then he can change the default behaviour\n" - "simply by overriding CreateTraits() and returning his own traits object) or\n" - "which is GUI/console dependent as then wx.AppTraits allows us to abstract the\n" - "differences behind the common facade"); + "Return (and create if necessary) the app traits object to which we +delegate for everything which either should be configurable by the +user (then he can change the default behaviour simply by overriding +CreateTraits() and returning his own traits object) or which is +GUI/console dependent as then wx.AppTraits allows us to abstract the +differences behind the common facade. + +:todo: Add support for overriding CreateAppTraits in wxPython."); DocDeclStr( virtual void, ProcessPendingEvents(), - "Process all events in the Pending Events list -- it is necessary to call this\n" - "function to process posted events. This happens during each event loop\n" - "iteration."); + "Process all events in the Pending Events list -- it is necessary to +call this function to process posted events. This normally happens +during each event loop iteration."); DocDeclStr( virtual bool, Yield(bool onlyIfNeeded = False), - "Process all currently pending events right now, instead of waiting until\n" - "return to the event loop. It is an error to call Yield() recursively unless\n" - "the value of onlyIfNeeded is True.\n" - "\n" - "WARNING: This function is dangerous as it can lead to unexpected\n" - " reentrancies (i.e. when called from an event handler it\n" - " may result in calling the same event handler again), use\n" - " with _extreme_ care or, better, don't use at all!\n"); + "Process all currently pending events right now, instead of waiting +until return to the event loop. It is an error to call ``Yield`` +recursively unless the value of ``onlyIfNeeded`` is True. + +:warning: This function is dangerous as it can lead to unexpected + reentrancies (i.e. when called from an event handler it may + result in calling the same event handler again), use with + _extreme_ care or, better, don't use at all! + +:see: `wx.Yield`, `wx.YieldIfNeeded`, `wx.SafeYield`"); DocDeclStr( virtual void, WakeUpIdle(), - "Make sure that idle events are sent again"); + "Make sure that idle events are sent again. +:see: `wx.WakeUpIdle`"); DocDeclStr( virtual int, MainLoop(), - "Execute the main GUI loop, the function returns when the loop ends."); + "Execute the main GUI loop, the function doesn't normally return until +all top level windows have been closed and destroyed."); DocDeclStr( virtual void, Exit(), - "Exit the main loop thus terminating the application."); + "Exit the main loop thus terminating the application. +:see: `wx.Exit`"); DocDeclStr( virtual void, ExitMainLoop(), - "Exit the main GUI loop during the next iteration (i.e. it does not\n" - "stop the program immediately!)"); + "Exit the main GUI loop during the next iteration of the main +loop, (i.e. it does not stop the program immediately!)"); DocDeclStr( @@ -143,21 +154,21 @@ public: DocDeclStr( virtual bool, Dispatch(), - "Process the first event in the event queue (blocks until an event\n" - "appears if there are none currently)"); + "Process the first event in the event queue (blocks until an event +appears if there are none currently)"); DocDeclStr( virtual bool, ProcessIdle(), - "Called from the MainLoop when the application becomes idle and sends an\n" - "IdleEvent to all interested parties. Returns True is more idle events are\n" - "needed, False if not."); + "Called from the MainLoop when the application becomes idle (there are +no pending events) and sends a `wx.IdleEvent` to all interested +parties. Returns True if more idle events are needed, False if not."); DocDeclStr( virtual bool, SendIdleEvents(wxWindow* win, wxIdleEvent& event), - "Send idle event to window and all subwindows. Returns True if more idle time\n" - "is requested."); + "Send idle event to window and all subwindows. Returns True if more +idle time is requested."); DocDeclStr( @@ -167,22 +178,22 @@ public: DocDeclStr( void, SetTopWindow(wxWindow *win), - "Set the \"main\" top level window"); + "Set the *main* top level window"); DocDeclStr( virtual wxWindow*, GetTopWindow() const, - "Return the \"main\" top level window (if it hadn't been set previously with\n" - "SetTopWindow(), will return just some top level window and, if there not any,\n" - "will return None)"); + "Return the *main* top level window (if it hadn't been set previously +with SetTopWindow(), will return just some top level window and, if +there not any, will return None)"); DocDeclStr( void, SetExitOnFrameDelete(bool flag), - "Control the exit behaviour: by default, the program will exit the main loop\n" - "(and so, usually, terminate) when the last top-level program window is\n" - "deleted. Beware that if you disable this behaviour (with\n" - "SetExitOnFrameDelete(False)), you'll have to call ExitMainLoop() explicitly\n" - "from somewhere.\n"); + "Control the exit behaviour: by default, the program will exit the main +loop (and so, usually, terminate) when the last top-level program +window is deleted. Beware that if you disable this behaviour (with +SetExitOnFrameDelete(False)), you'll have to call ExitMainLoop() +explicitly from somewhere."); DocDeclStr( @@ -203,8 +214,8 @@ public: DocDeclStr( void, SetUseBestVisual( bool flag ), - "Set whether the app should try to use the best available visual on systems\n" - "where more than one is available, (Sun, SGI, XFree86 4, etc.)"); + "Set whether the app should try to use the best available visual on +systems where more than one is available, (Sun, SGI, XFree86 4, etc.)"); DocDeclStr( bool, GetUseBestVisual() const, @@ -221,13 +232,18 @@ public: DocDeclStr( void, SetAssertMode(int mode), - "Set the OnAssert behaviour for debug and hybrid builds. The following flags\n" - "may be or'd together:\n" - "\n" - " wx.PYAPP_ASSERT_SUPPRESS Don't do anything\n" - " wx.PYAPP_ASSERT_EXCEPTION Turn it into a Python exception if possible (default)\n" - " wx.PYAPP_ASSERT_DIALOG Display a message dialog\n" - " wx.PYAPP_ASSERT_LOG Write the assertion info to the wx.Log\n"); + "Set the OnAssert behaviour for debug and hybrid builds. The following +flags may be or'd together: + + ========================= ======================================= + wx.PYAPP_ASSERT_SUPPRESS Don't do anything + wx.PYAPP_ASSERT_EXCEPTION Turn it into a Python exception if possible + (default) + wx.PYAPP_ASSERT_DIALOG Display a message dialog + wx.PYAPP_ASSERT_LOG Write the assertion info to the wx.Log + ========================= ======================================= + +"); DocDeclStr( int, GetAssertMode(), @@ -252,9 +268,8 @@ public: "For internal use only"); DocStr(GetComCtl32Version, - "Returns 400, 470, 471, etc. for comctl32.dll 4.00, 4.70, 4.71 or -0 if it wasn't found at all. Raises an exception on non-Windows -platforms."); + "Returns 400, 470, 471, etc. for comctl32.dll 4.00, 4.70, 4.71 or 0 if +it wasn't found at all. Raises an exception on non-Windows platforms."); #ifdef __WXMSW__ static int GetComCtl32Version(); #else @@ -287,26 +302,30 @@ DocDeclStr( DocDeclStr( bool, wxSafeYield(wxWindow* win=NULL, bool onlyIfNeeded=False), - "This function is similar to wx.Yield, except that it disables the user input\n" - "to all program windows before calling wx.Yield and re-enables it again\n" - "afterwards. If win is not None, this window will remain enabled, allowing the\n" - "implementation of some limited user interaction.\n" - "\n" - "Returns the result of the call to wx.Yield."); + "This function is similar to `wx.Yield`, except that it disables the +user input to all program windows before calling `wx.Yield` and +re-enables it again afterwards. If ``win`` is not None, this window +will remain enabled, allowing the implementation of some limited user +interaction. + +:Returns: the result of the call to `wx.Yield`."); DocDeclStr( void, wxWakeUpIdle(), - "Cause the message queue to become empty again, so idle events will be sent."); + "Cause the message queue to become empty again, so idle events will be +sent."); DocDeclStr( void, wxPostEvent(wxEvtHandler *dest, wxEvent& event), - "Send an event to a window or other wx.EvtHandler to be processed later."); + "Send an event to a window or other wx.EvtHandler to be processed +later."); DocStr(wxApp_CleanUp, - "For internal use only, it is used to cleanup after wxWindows when Python shuts down."); + "For internal use only, it is used to cleanup after wxWindows when +Python shuts down."); %inline %{ void wxApp_CleanUp() { __wxPyCleanup(); diff --git a/wxPython/src/_app_ex.py b/wxPython/src/_app_ex.py index 15778e811a..808743dd33 100644 --- a/wxPython/src/_app_ex.py +++ b/wxPython/src/_app_ex.py @@ -67,12 +67,56 @@ _defRedirect = (wx.Platform == '__WXMSW__' or wx.Platform == '__WXMAC__') class App(wx.PyApp): """ - The main application class. Derive from this and implement an OnInit - method that creates a frame and then calls self.SetTopWindow(frame) + The ``wx.App`` class represents the application and is used to: + + * bootstrap the wxPython system and initialize the underlying + gui toolkit + * set and get application-wide properties + * implement the windowing system main message or event loop, + and to dispatch events to window instances + * etc. + + Every application must have a ``wx.App`` instance, and all + creation of UI objects should be delayed until after the + ``wx.App`` object has been created in order to ensure that the + gui platform and wxWidgets have been fully initialized. + + Normally you would derive from this class and implement an + ``OnInit`` method that creates a frame and then calls + ``self.SetTopWindow(frame)``. + + :see: `wx.PySimpleApp` for a simpler app class that can be used directly. """ + outputWindowClass = PyOnDemandOutputWindow def __init__(self, redirect=_defRedirect, filename=None, useBestVisual=False): + """ + Construct a ``wx.App`` object. + + :param redirect: Should ``sys.stdout`` and ``sys.stderr`` + be redirected? Defaults to True on Windows and Mac, + False otherwise. If `filename` is None then output + will be redirected to a window that pops up as + needed. (You can control what kind of window is + created for the output by resetting the class + variable ``outputWindowClass`` to a class of your + choosing.) + + :param filename: The name of a file to redirect output + to, if redirect is True. + + :param useBestVisual: Should the app try to use the best + available visual provided by the system (only + relevant on systems that have more than one visual.) + This parameter must be used instead of calling + `SetUseBestVisual` later on because it must be set + before the underlying GUI toolkit is initialized. + + :note: You should override OnInit to do applicaition + initialization to ensure that the system, toolkit and + wxWidgets are fully initialized. + """ wx.PyApp.__init__(self) if wx.Platform == "__WXMAC__": @@ -147,7 +191,7 @@ your Mac.""" -# change from wxPyApp_ to wxApp_ +# change from wx.PyApp_XX to wx.App_XX App_GetMacSupportPCMenuShortcuts = _core_.PyApp_GetMacSupportPCMenuShortcuts App_GetMacAboutMenuItemId = _core_.PyApp_GetMacAboutMenuItemId App_GetMacPreferencesMenuItemId = _core_.PyApp_GetMacPreferencesMenuItemId @@ -166,9 +210,20 @@ class PySimpleApp(wx.App): """ A simple application class. You can just create one of these and then then make your top level windows later, and not have to worry - about OnInit.""" + about OnInit. For example:: + + app = wx.PySimpleApp() + frame = wx.Frame(None, title='Hello World') + frame.Show() + app.MainLoop() + + :see: `wx.App` + """ def __init__(self, redirect=False, filename=None, useBestVisual=False): + """ + :see: `wx.App.__init__` + """ wx.App.__init__(self, redirect, filename, useBestVisual) def OnInit(self): @@ -176,6 +231,7 @@ class PySimpleApp(wx.App): return True + # Is anybody using this one? class PyWidgetTester(wx.App): def __init__(self, size = (250, 100)): @@ -187,15 +243,15 @@ class PyWidgetTester(wx.App): self.SetTopWindow(self.frame) return True - def SetWidget(self, widgetClass, *args): - w = widgetClass(self.frame, *args) + def SetWidget(self, widgetClass, *args, **kwargs): + w = widgetClass(self.frame, *args, **kwargs) self.frame.Show(True) #---------------------------------------------------------------------------- # DO NOT hold any other references to this object. This is how we -# know when to cleanup system resources that wxWin is holding. When +# know when to cleanup system resources that wxWidgets is holding. When # the sys module is unloaded, the refcount on sys.__wxPythonCleanup -# goes to zero and it calls the wxApp_CleanUp function. +# goes to zero and it calls the wx.App_CleanUp function. class __wxPyCleanup: def __init__(self): @@ -206,11 +262,8 @@ class __wxPyCleanup: _sys.__wxPythonCleanup = __wxPyCleanup() ## # another possible solution, but it gets called too early... -## if sys.version[0] == '2': -## import atexit -## atexit.register(_core_.wxApp_CleanUp) -## else: -## sys.exitfunc = _core_.wxApp_CleanUp +## import atexit +## atexit.register(_core_.wxApp_CleanUp) #---------------------------------------------------------------------------- diff --git a/wxPython/src/_artprov.i b/wxPython/src/_artprov.i index 1f6fe34cf3..e8f19c9eb6 100644 --- a/wxPython/src/_artprov.i +++ b/wxPython/src/_artprov.i @@ -102,6 +102,90 @@ public: %} // The one for SWIG to see + + + +DocStr(wxPyArtProvider, +"The wx.ArtProvider class is used to customize the look of wxWidgets +application. When wxWidgets needs to display an icon or a bitmap (e.g. +in the standard file dialog), it does not use hard-coded resource but +asks wx.ArtProvider for it instead. This way the users can plug in +their own wx.ArtProvider class and easily replace standard art with +his/her own version. It is easy thing to do: all that is needed is +to derive a class from wx.ArtProvider, override it's CreateBitmap +method and register the provider with wx.ArtProvider.PushProvider:: + + class MyArtProvider(wx.ArtProvider): + def __init__(self): + wx.ArtProvider.__init__(self) + + def CreateBitmap(self, artid, client, size): + ... + 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) +"); + %name(ArtProvider) class wxPyArtProvider /*: public wxObject*/ { public: @@ -111,30 +195,37 @@ public: void _setCallbackInfo(PyObject* self, PyObject* _class); - DocStr(PushProvider, "Add new provider to the top of providers stack."); - static void PushProvider(wxPyArtProvider *provider); + DocDeclStr( + static void , PushProvider(wxPyArtProvider *provider), + "Add new provider to the top of providers stack."); + - DocStr(PopProvider, "Remove latest added provider and delete it."); - static bool PopProvider(); + DocDeclStr( + static bool , PopProvider(), + "Remove latest added provider and delete it."); + - DocStr(RemoveProvider, - "Remove provider. The provider must have been added previously!\n" - "The provider is _not_ deleted."); - static bool RemoveProvider(wxPyArtProvider *provider); + DocDeclStr( + static bool , RemoveProvider(wxPyArtProvider *provider), + "Remove provider. The provider must have been added previously! The +provider is _not_ deleted."); + - DocStr(GetBitmap, - "Query the providers for bitmap with given ID and return it. Return\n" - "wx.NullBitmap if no provider provides it."); - static wxBitmap GetBitmap(const wxString& id, - const wxString& client = wxPyART_OTHER, - const wxSize& size = wxDefaultSize); + DocDeclStr( + static wxBitmap , GetBitmap(const wxString& id, + const wxString& client = wxPyART_OTHER, + const wxSize& size = wxDefaultSize), + "Query the providers for bitmap with given ID and return it. Return +wx.NullBitmap if no provider provides it."); + - DocStr(GetIcon, - "Query the providers for icon with given ID and return it. Return\n" - "wx.NullIcon if no provider provides it."); - static wxIcon GetIcon(const wxString& id, + DocDeclStr( + static wxIcon , GetIcon(const wxString& id, const wxString& client = wxPyART_OTHER, - const wxSize& size = wxDefaultSize); + const wxSize& size = wxDefaultSize), + "Query the providers for icon with given ID and return it. Return +wx.NullIcon if no provider provides it."); + %extend { void Destroy() { delete self; }} }; diff --git a/wxPython/src/_bitmap.i b/wxPython/src/_bitmap.i index 44f39290e6..2b4aaca596 100644 --- a/wxPython/src/_bitmap.i +++ b/wxPython/src/_bitmap.i @@ -43,34 +43,83 @@ // TODO: When the API stabalizes and is available on other platforms, add // wrappers for the new wxBitmap, wxRawBitmap, wxDIB stuff... +DocStr(wxBitmap, +"The wx.Bitmap class encapsulates the concept of a platform-dependent +bitmap. It can be either monochrome or colour, and either loaded from +a file or created dynamically. A bitmap can be selected into a memory +device context (instance of `wx.MemoryDC`). This enables the bitmap to +be copied to a window or memory device context using `wx.DC.Blit`, or +to be used as a drawing surface. + +The BMP and XMP image file formats are supported on all platforms by +wx.Bitmap. Other formats are automatically loaded by `wx.Image` and +converted to a wx.Bitmap, so any image file format supported by +`wx.Image` can be used. + +:todo: Add wrappers and support for raw bitmap data access. Can this + be be put into Python without losing the speed benefits of the + teplates and iterators in rawbmp.h? + +:todo: Find a way to do very efficient PIL Image <--> wx.Bitmap + converstions. +"); + class wxBitmap : public wxGDIObject { public: DocCtorStr( wxBitmap(const wxString& name, wxBitmapType type=wxBITMAP_TYPE_ANY), - "Loads a bitmap from a file."); + "Loads a bitmap from a file. + +:param name: Name of the file to load the bitmap from. +:param type: The type of image to expect. Can be one of the following + constants (assuming that the neccessary `wx.Image` handlers are + loaded): + + * wx.BITMAP_TYPE_ANY + * wx.BITMAP_TYPE_BMP + * wx.BITMAP_TYPE_ICO + * wx.BITMAP_TYPE_CUR + * wx.BITMAP_TYPE_XBM + * wx.BITMAP_TYPE_XPM + * wx.BITMAP_TYPE_TIF + * wx.BITMAP_TYPE_GIF + * wx.BITMAP_TYPE_PNG + * wx.BITMAP_TYPE_JPEG + * wx.BITMAP_TYPE_PNM + * wx.BITMAP_TYPE_PCX + * wx.BITMAP_TYPE_PICT + * wx.BITMAP_TYPE_ICON + * wx.BITMAP_TYPE_ANI + * wx.BITMAP_TYPE_IFF + +:see: Alternate constructors `wx.EmptyBitmap`, `wx.BitmapFromIcon`, + `wx.BitmapFromImage`, `wx.BitmapFromXPMData`, + `wx.BitmapFromBits` +"); ~wxBitmap(); -// DocCtorStrName( -// wxBitmap(int width, int height, int depth=-1), -// "Creates a new bitmap of the given size. A depth of -1 indicates the depth of\n" -// "the current screen or visual. Some platforms only support 1 for monochrome and\n" -// "-1 for the current colour setting.", -// EmptyBitmap); + DocCtorStrName( + wxBitmap(int width, int height, int depth=-1), + "Creates a new bitmap of the given size. A depth of -1 indicates the +depth of the current screen or visual. Some platforms only support 1 +for monochrome and -1 for the current colour setting.", + EmptyBitmap); DocCtorStrName( wxBitmap(const wxIcon& icon), - "Create a new bitmap from an Icon object.", + "Create a new bitmap from a `wx.Icon` object.", BitmapFromIcon); DocCtorStrName( wxBitmap(const wxImage& image, int depth=-1), - "Creates bitmap object from the image. This has to be done to actually display\n" - "an image as you cannot draw an image directly on a window. The resulting\n" - "bitmap will use the provided colour depth (or that of the current system if\n" - "depth is -1) which entails that a colour reduction has to take place.", + "Creates bitmap object from a `wx.Image`. This has to be done to +actually display a `wx.Image` as you cannot draw an image directly on +a window. The resulting bitmap will use the provided colour depth (or +that of the current screen colour depth if depth is -1) which entails +that a colour reduction may have to take place.", BitmapFromImage); @@ -90,31 +139,16 @@ public: } DocStr(wxBitmap(PyObject* bits, int width, int height, int depth=1 ), - "Creates a bitmap from an array of bits. You should only use this function for\n" - "monochrome bitmaps (depth 1) in portable programs: in this case the bits\n" - "parameter should contain an XBM image. For other bit depths, the behaviour is\n" - "platform dependent."); + "Creates a bitmap from an array of bits. You should only use this +function for monochrome bitmaps (depth 1) in portable programs: in +this case the bits parameter should contain an XBM image. For other +bit depths, the behaviour is platform dependent."); %name(BitmapFromBits) wxBitmap(PyObject* bits, int width, int height, int depth=1 ) { char* buf; int length; PyString_AsStringAndSize(bits, &buf, &length); return new wxBitmap(buf, width, height, depth); } - - - DocStr(wxBitmap(const wxSize& size, int depth=-1), - "Creates a new bitmap of the given size. A depth of -1 indicates -the depth of the current screen or visual. Some platforms only -support 1 for monochrome and -1 for the current colour setting."); - - %nokwargs wxBitmap(int width, int height, int depth=-1); - %nokwargs wxBitmap(const wxSize& size, int depth=-1); - %name(EmptyBitmap)wxBitmap(int width, int height, int depth=-1) { - return new wxBitmap(width, height, depth); - } - %name(EmptyBitmap)wxBitmap(const wxSize& size, int depth=-1) { - return new wxBitmap(size.x, size.y, depth); - } } @@ -132,16 +166,21 @@ support 1 for monochrome and -1 for the current colour setting."); bool Ok(); - DocStr(GetWidth, "Gets the width of the bitmap in pixels."); - int GetWidth(); + DocDeclStr( + int , GetWidth(), + "Gets the width of the bitmap in pixels."); + - DocStr(GetHeight, "Gets the height of the bitmap in pixels."); - int GetHeight(); + DocDeclStr( + int , GetHeight(), + "Gets the height of the bitmap in pixels."); + - DocStr(GetDepth, - "Gets the colour depth of the bitmap. A value of 1 indicates a\n" - "monochrome bitmap."); - int GetDepth(); + DocDeclStr( + int , GetDepth(), + "Gets the colour depth of the bitmap. A value of 1 indicates a +monochrome bitmap."); + %extend { @@ -153,20 +192,29 @@ support 1 for monochrome and -1 for the current colour setting."); } - DocStr(ConvertToImage, - "Creates a platform-independent image from a platform-dependent bitmap. This\n" - "preserves mask information so that bitmaps and images can be converted back\n" - "and forth without loss in that respect."); - virtual wxImage ConvertToImage() const; - - DocStr(GetMask, - "Gets the associated mask (if any) which may have been loaded from a file\n" - "or explpicitly set for the bitmap."); - virtual wxMask* GetMask() const; - - DocStr(SetMask, - "Sets the mask for this bitmap."); - virtual void SetMask(wxMask* mask); + DocDeclStr( + virtual wxImage , ConvertToImage() const, + "Creates a platform-independent image from a platform-dependent +bitmap. This preserves mask information so that bitmaps and images can +be converted back and forth without loss in that respect."); + + + DocDeclStr( + virtual wxMask* , GetMask() const, + "Gets the associated mask (if any) which may have been loaded from a +file or explpicitly set for the bitmap. + +:see: `SetMask`, `wx.Mask` +"); + + + DocDeclStr( + virtual void , SetMask(wxMask* mask), + "Sets the mask for this bitmap. + +:see: `GetMask`, `wx.Mask` +"); + %extend { DocStr(SetMaskColour, @@ -177,17 +225,26 @@ support 1 for monochrome and -1 for the current colour setting."); } } - DocStr(GetSubBitmap, - "Returns a sub bitmap of the current one as long as the rect belongs entirely\n" - "to the bitmap. This function preserves bit depth and mask information."); - virtual wxBitmap GetSubBitmap(const wxRect& rect) const; - DocStr(SaveFile, "Saves a bitmap in the named file."); - virtual bool SaveFile(const wxString &name, wxBitmapType type, - wxPalette *palette = (wxPalette *)NULL); + DocDeclStr( + virtual wxBitmap , GetSubBitmap(const wxRect& rect) const, + "Returns a sub-bitmap of the current one as long as the rect belongs +entirely to the bitmap. This function preserves bit depth and mask +information."); + + + DocDeclStr( + virtual bool , SaveFile(const wxString &name, wxBitmapType type, + wxPalette *palette = NULL), + "Saves a bitmap in the named file. See `__init__` for a description of +the ``type`` parameter."); + - DocStr(LoadFile, "Loads a bitmap from a file"); - virtual bool LoadFile(const wxString &name, wxBitmapType type); + DocDeclStr( + virtual bool , LoadFile(const wxString &name, wxBitmapType type), + "Loads a bitmap from a file. See `__init__` for a description of the +``type`` parameter."); + #if wxUSE_PALETTE @@ -198,17 +255,23 @@ support 1 for monochrome and -1 for the current colour setting."); virtual bool CopyFromIcon(const wxIcon& icon); - DocStr(SetHeight, "Set the height property (does not affect the bitmap data).") - virtual void SetHeight(int height); + DocDeclStr( + virtual void , SetHeight(int height), + "Set the height property (does not affect the existing bitmap data)."); + + + DocDeclStr( + virtual void , SetWidth(int width), + "Set the width property (does not affect the existing bitmap data)."); - DocStr(SetWidth, "Set the width property (does not affect the bitmap data).") - virtual void SetWidth(int width); - DocStr(SetDepth, "Set the depth property (does not affect the bitmap data).") - virtual void SetDepth(int depth); + DocDeclStr( + virtual void , SetDepth(int depth), + "Set the depth property (does not affect the existing bitmap data)."); + %extend { - DocStr(SetSize, "Set the bitmap size"); + DocStr(SetSize, "Set the bitmap size (does not affect the existing bitmap data)."); void SetSize(const wxSize& size) { self->SetWidth(size.x); self->SetHeight(size.y); @@ -233,22 +296,28 @@ support 1 for monochrome and -1 for the current colour setting."); //--------------------------------------------------------------------------- DocStr(wxMask, - "This class encapsulates a monochrome mask bitmap, where the masked area is\n" - "black and the unmasked area is white. When associated with a bitmap and drawn\n" - "in a device context, the unmasked area of the bitmap will be drawn, and the\n" - "masked area will not be drawn."); +"This class encapsulates a monochrome mask bitmap, where the masked +area is black and the unmasked area is white. When associated with a +bitmap and drawn in a device context, the unmasked area of the bitmap +will be drawn, and the masked area will not be drawn. + +A mask may be associated with a `wx.Bitmap`. It is used in +`wx.DC.DrawBitmap` or `wx.DC.Blit` when the source device context is a +`wx.MemoryDC` with a `wx.Bitmap` selected into it that contains a +mask. +"); class wxMask : public wxObject { public: -#if 0 - DocCtorStr( - wxMask(const wxBitmap& bitmap), - "Constructs a mask from a monochrome bitmap."); -#endif DocStr(wxMask, - "Constructs a mask from a bitmap and a colour in that bitmap that indicates\n" - "the transparent portions of the mask, by default BLACK is used."); + "Constructs a mask from a `wx.Bitmap` and a `wx.Colour` in that bitmap +that indicates the transparent portions of the mask. In other words, +the pixels in ``bitmap`` that match ``colour`` will be the transparent +portions of the mask. If no ``colour`` or an invalid ``colour`` is +passed then BLACK is used. + +:see: `wx.Bitmap`, `wx.Colour`"); %extend { wxMask(const wxBitmap& bitmap, const wxColour& colour = wxNullColour) { @@ -262,7 +331,7 @@ public: //~wxMask(); }; -%pythoncode { MaskColour = Mask } +%pythoncode { MaskColour = wx._deprecated(Mask, "wx.MaskColour is deprecated, use `wx.Mask` instead.") } //--------------------------------------------------------------------------- //--------------------------------------------------------------------------- diff --git a/wxPython/src/_brush.i b/wxPython/src/_brush.i index c3e27280d5..45503e817f 100644 --- a/wxPython/src/_brush.i +++ b/wxPython/src/_brush.i @@ -17,25 +17,81 @@ %newgroup DocStr(wxBrush, - "A brush is a drawing tool for filling in areas. It is used for painting the\n" - "background of rectangles, ellipses, etc. It has a colour and a style."); +"A brush is a drawing tool for filling in areas. It is used for +painting the background of rectangles, ellipses, etc. when drawing on +a `wx.DC`. It has a colour and a style. + +:warning: Do not create instances of wx.Brush before the `wx.App` + object has been created because, depending on the platform, + required internal data structures may not have been initialized + yet. Instead create your brushes in the app's OnInit or as they + are needed for drawing. + +:note: On monochrome displays all brushes are white, unless the colour + really is black. + +:see: `wx.BrushList`, `wx.DC`, `wx.DC.SetBrush` +"); class wxBrush : public wxGDIObject { public: - DocStr(wxBrush, "Constructs a brush from a colour object and style."); - wxBrush(const wxColour& colour, int style=wxSOLID); + DocCtorStr( + wxBrush(const wxColour& colour, int style=wxSOLID), + "Constructs a brush from a `wx.Colour` object and a style. The style +parameter may be one of the following: + + =================== ============================= + Style Meaning + =================== ============================= + wx.TRANSPARENT Transparent (no fill). + wx.SOLID Solid. + wx.STIPPLE Uses a bitmap as a stipple. + wx.BDIAGONAL_HATCH Backward diagonal hatch. + wx.CROSSDIAG_HATCH Cross-diagonal hatch. + wx.FDIAGONAL_HATCH Forward diagonal hatch. + wx.CROSS_HATCH Cross hatch. + wx.HORIZONTAL_HATCH Horizontal hatch. + wx.VERTICAL_HATCH Vertical hatch. + =================== ============================= + +"); + ~wxBrush(); - - - virtual void SetColour(const wxColour& col); - virtual void SetStyle(int style); - virtual void SetStipple(const wxBitmap& stipple); - wxColour GetColour() const; - int GetStyle() const; - wxBitmap *GetStipple() const; - bool Ok(); + DocDeclStr( + virtual void , SetColour(const wxColour& col), + "Set the brush's `wx.Colour`."); + + DocDeclStr( + virtual void , SetStyle(int style), + "Sets the style of the brush. See `__init__` for a listing of styles."); + + DocDeclStr( + virtual void , SetStipple(const wxBitmap& stipple), + "Sets the stipple `wx.Bitmap`."); + + + DocDeclStr( + wxColour , GetColour() const, + "Returns the `wx.Colour` of the brush."); + + DocDeclStr( + int , GetStyle() const, + "Returns the style of the brush. See `__init__` for a listing of +styles."); + + DocDeclStr( + wxBitmap *, GetStipple() const, + "Returns the stiple `wx.Bitmap` of the brush. If the brush does not +have a wx.STIPPLE style, then the return value may be non-None but an +uninitialised bitmap (`wx.Bitmap.Ok` returns False)."); + + + DocDeclStr( + bool , Ok(), + "Returns True if the brush is initialised and valid."); + #ifdef __WXMAC__ short MacGetTheme(); diff --git a/wxPython/src/_button.i b/wxPython/src/_button.i index 320f480990..be6ec069cc 100644 --- a/wxPython/src/_button.i +++ b/wxPython/src/_button.i @@ -31,21 +31,31 @@ enum { //--------------------------------------------------------------------------- DocStr(wxButton, - "A button is a control that contains a text string, and is one of the most\n" - "common elements of a GUI. It may be placed on a dialog box or panel, or\n" - "indeed almost any other window."); - -RefDoc(wxButton, " - Styles - wx.BU_LEFT: Left-justifies the label. WIN32 only. - wx.BU_TOP: Aligns the label to the top of the button. WIN32 only. - wx.BU_RIGHT: Right-justifies the bitmap label. WIN32 only. - wx.BU_BOTTOM: Aligns the label to the bottom of the button. WIN32 only. - wx.BU_EXACTFIT: Creates the button as small as possible instead of making - it of the standard size (which is the default behaviour.) - - Events - EVT_BUTTON: Sent when the button is clicked. +"A button is a control that contains a text string, and is one of the most +common elements of a GUI. It may be placed on a dialog box or panel, or +indeed almost any other window. + +Window Styles +------------- + ============== ========================================== + wx.BU_LEFT Left-justifies the label. WIN32 only. + wx.BU_TOP Aligns the label to the top of the button. + WIN32 only. + wx.BU_RIGHT Right-justifies the bitmap label. WIN32 only. + wx.BU_BOTTOM Aligns the label to the bottom of the button. + WIN32 only. + wx.BU_EXACTFIT Creates the button as small as possible + instead of making it of the standard size + (which is the default behaviour.) + ============== ========================================== + +Events +------ + ============ ========================================== + EVT_BUTTON Sent when the button is clicked. + ============ ========================================== + +:see: `wx.BitmapButton` "); class wxButton : public wxControl @@ -55,41 +65,40 @@ public: %pythonAppend wxButton() "" - DocStr(wxButton, "Create and show a button."); RefDoc(wxButton, ""); - wxButton(wxWindow* parent, wxWindowID id, const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxPyButtonNameStr); - - DocStr(wxButton(), "Precreate a Button for 2-phase creation."); - %name(PreButton)wxButton(); - - DocStr(Create, "Acutally create the GUI Button for 2-phase creation."); - bool Create(wxWindow* parent, wxWindowID id, const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxPyButtonNameStr); - - - DocStr(SetDefault, "This sets the button to be the default item for the panel or dialog box."); - void SetDefault(); - + DocCtorStr( + wxButton(wxWindow* parent, wxWindowID id, const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxPyButtonNameStr), + "Create and show a button."); + + DocCtorStrName( + wxButton(), + "Precreate a Button for 2-phase creation.", + PreButton); + + DocDeclStr( + bool , Create(wxWindow* parent, wxWindowID id, const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxPyButtonNameStr), + "Acutally create the GUI Button for 2-phase creation."); + -// #ifdef __WXMSW__ -// // show the image in the button in addition to the label -// void SetImageLabel(const wxBitmap& bitmap); -// // set the margins around the image -// void SetImageMargins(wxCoord x, wxCoord y); -// #endif + DocDeclStr( + void , SetDefault(), + "This sets the button to be the default item for the panel or dialog box."); + - DocStr(GetDefaultButtonSize, "Returns the default button size for this platform."); - static wxSize GetDefaultSize(); + DocDeclStr( + static wxSize , GetDefaultSize(), + "Returns the default button size for this platform."); }; @@ -99,27 +108,37 @@ public: DocStr(wxBitmapButton, "A Button that contains a bitmap. A bitmap button can be supplied with a -single bitmap, and wxWindows will draw all button states using this bitmap. If +single bitmap, and wxWidgets will draw all button states using this bitmap. If the application needs more control, additional bitmaps for the selected state, unpressed focused state, and greyed-out state may be supplied. -"); -RefDoc(wxBitmapButton, " - Styles - wx.BU_AUTODRAW: If this is specified, the button will be drawn - automatically using the label bitmap only, providing a - 3D-look border. If this style is not specified, the button - will be drawn without borders and using all provided +Window Styles +------------- + ============== ============================================= + wx.BU_AUTODRAW If this is specified, the button will be drawn + automatically using the label bitmap only, + providing a 3D-look border. If this style is + not specified, the button will be drawn + without borders and using all provided bitmaps. WIN32 only. - wx.BU_LEFT: Left-justifies the label. WIN32 only. - wx.BU_TOP: Aligns the label to the top of the button. WIN32 only. - wx.BU_RIGHT: Right-justifies the bitmap label. WIN32 only. - wx.BU_BOTTOM: Aligns the label to the bottom of the button. WIN32 only. - wx.BU_EXACTFIT: Creates the button as small as possible instead of making - it of the standard size (which is the default behaviour.) - - Events - EVT_BUTTON: Sent when the button is clicked. + wx.BU_LEFT Left-justifies the label. WIN32 only. + wx.BU_TOP Aligns the label to the top of the button. WIN32 + only. + wx.BU_RIGHT Right-justifies the bitmap label. WIN32 only. + wx.BU_BOTTOM Aligns the label to the bottom of the + button. WIN32 only. + wx.BU_EXACTFIT Creates the button as small as possible + instead of making it of the standard size + (which is the default behaviour.) + ============== ============================================= + +Events +------ + =========== ================================== + EVT_BUTTON Sent when the button is clicked. + =========== ================================== + +:see: `wx.Button`, `wx.Bitmap` "); class wxBitmapButton : public wxButton @@ -128,52 +147,70 @@ public: %pythonAppend wxBitmapButton "self._setOORInfo(self)" %pythonAppend wxBitmapButton() "" - DocStr(wxBitmapButton, "Create and show a button with a bitmap for the label.") RefDoc(wxBitmapButton, ""); // turn it off for the ctors - - wxBitmapButton(wxWindow* parent, wxWindowID id, const wxBitmap& bitmap, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxBU_AUTODRAW, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxPyButtonNameStr); - - DocStr(wxBitmapButton(), "Precreate a BitmapButton for 2-phase creation."); - %name(PreBitmapButton)wxBitmapButton(); - - DocStr(Create, "Acutally create the GUI BitmapButton for 2-phase creation."); - bool Create(wxWindow* parent, wxWindowID id, const wxBitmap& bitmap, + + DocCtorStr( + wxBitmapButton(wxWindow* parent, wxWindowID id, const wxBitmap& bitmap, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBU_AUTODRAW, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxPyButtonNameStr), + "Create and show a button with a bitmap for the label."); + + DocCtorStrName( + wxBitmapButton(), + "Precreate a BitmapButton for 2-phase creation.", + PreBitmapButton); + + DocDeclStr( + bool , Create(wxWindow* parent, wxWindowID id, const wxBitmap& bitmap, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxBU_AUTODRAW, const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxPyButtonNameStr); - - DocStr(GetBitmapLabel, "Returns the label bitmap (the one passed to the constructor)."); - wxBitmap GetBitmapLabel(); - - DocStr(GetBitmapDisabled, "Returns the bitmap for the disabled state."); - wxBitmap GetBitmapDisabled(); + const wxString& name = wxPyButtonNameStr), + "Acutally create the GUI BitmapButton for 2-phase creation."); + - DocStr(GetBitmapFocus, "Returns the bitmap for the focused state."); - wxBitmap GetBitmapFocus(); + DocDeclStr( + wxBitmap , GetBitmapLabel(), + "Returns the label bitmap (the one passed to the constructor)."); + + DocDeclStr( + wxBitmap , GetBitmapDisabled(), + "Returns the bitmap for the disabled state."); + + DocDeclStr( + wxBitmap , GetBitmapFocus(), + "Returns the bitmap for the focused state."); + - DocStr(GetBitmapSelected, "Returns the bitmap for the selected state."); - wxBitmap GetBitmapSelected(); + DocDeclStr( + wxBitmap , GetBitmapSelected(), + "Returns the bitmap for the selected state."); + - DocStr(SetBitmapDisabled, "Sets the bitmap for the disabled button appearance."); - void SetBitmapDisabled(const wxBitmap& bitmap); + DocDeclStr( + void , SetBitmapDisabled(const wxBitmap& bitmap), + "Sets the bitmap for the disabled button appearance."); + - DocStr(SetBitmapFocus, "Sets the bitmap for the button appearance when it has the keyboard focus."); - void SetBitmapFocus(const wxBitmap& bitmap); + DocDeclStr( + void , SetBitmapFocus(const wxBitmap& bitmap), + "Sets the bitmap for the button appearance when it has the keyboard focus."); + - DocStr(SetBitmapSelected, "Sets the bitmap for the selected (depressed) button appearance."); - void SetBitmapSelected(const wxBitmap& bitmap); + DocDeclStr( + void , SetBitmapSelected(const wxBitmap& bitmap), + "Sets the bitmap for the selected (depressed) button appearance."); + - DocStr(SetBitmapLabel, - "Sets the bitmap label for the button. This is the bitmap used for the\n" - "unselected state, and for all other states if no other bitmaps are provided."); - void SetBitmapLabel(const wxBitmap& bitmap); + DocDeclStr( + void , SetBitmapLabel(const wxBitmap& bitmap), + "Sets the bitmap label for the button. This is the bitmap used for the +unselected state, and for all other states if no other bitmaps are provided."); + void SetMargins(int x, int y); int GetMarginX() const; diff --git a/wxPython/src/_checkbox.i b/wxPython/src/_checkbox.i index 74b6bbc3e4..ae785bad99 100644 --- a/wxPython/src/_checkbox.i +++ b/wxPython/src/_checkbox.i @@ -45,24 +45,35 @@ enum wxCheckBoxState //--------------------------------------------------------------------------- DocStr(wxCheckBox, -"A checkbox is a labelled box which by default is either on (checkmark is -visible) or off (no checkmark). Optionally (When the wxCHK_3STATE style flag -is set) it can have a third state, called the mixed or undetermined -state. Often this is used as a \"Does Not Apply\" state."); - -RefDoc(wxCheckBox, " - Styles - wx.CHK_2STATE: Create a 2-state checkbox. This is the default. - wx.CHK_3STATE: Create a 3-state checkbox. - wx.CHK_ALLOW_3RD_STATE_FOR_USER: By default a user can't set a 3-state - checkbox to the third state. It can only - be done from code. Using this flags - allows the user to set the checkbox to - the third state by clicking. - wx.ALIGN_RIGHT: Makes the text appear on the left of the checkbox. - - Events - EVT_CHECKBOX: Sent when checkbox is clicked. +"A checkbox is a labelled box which by default is either on (the +checkmark is visible) or off (no checkmark). Optionally (When the +wx.CHK_3STATE style flag is set) it can have a third state, called the +mixed or undetermined state. Often this is used as a \"Does Not +Apply\" state. + +Window Styles +------------- + ================================= =============================== + wx.CHK_2STATE Create a 2-state checkbox. + This is the default. + wx.CHK_3STATE Create a 3-state checkbox. + wx.CHK_ALLOW_3RD_STATE_FOR_USER By default a user can't set a + 3-state checkbox to the + third state. It can only be + done from code. Using this + flags allows the user to set + the checkbox to the third + state by clicking. + wx.ALIGN_RIGHT Makes the + text appear on the left of + the checkbox. + ================================= =============================== + +Events +------ + =============================== =============================== + EVT_CHECKBOX Sent when checkbox is clicked. + =============================== =============================== "); @@ -102,31 +113,33 @@ public: DocDeclStr( bool, GetValue(), - "Gets the state of a 2-state CheckBox. Returns True if it is checked,\n" - "False otherwise."); + "Gets the state of a 2-state CheckBox. Returns True if it is checked, +False otherwise."); DocDeclStr( bool, IsChecked(), - "Similar to GetValue, but raises an exception if it is not a 2-state CheckBox."); + "Similar to GetValue, but raises an exception if it is not a 2-state +CheckBox."); DocDeclStr( void, SetValue(const bool state), - "Set the state of a 2-state CheckBox. Pass True for checked,\n" - "False for unchecked."); + "Set the state of a 2-state CheckBox. Pass True for checked, False for +unchecked."); DocDeclStr( wxCheckBoxState, Get3StateValue() const, - "Returns wx.CHK_UNCHECKED when the CheckBox is unchecked, wx.CHK_CHECKED when\n" - "it is checked and wx.CHK_UNDETERMINED when it's in the undetermined state.\n" - "Raises an exceptiion when the function is used with a 2-state CheckBox."); + "Returns wx.CHK_UNCHECKED when the CheckBox is unchecked, +wx.CHK_CHECKED when it is checked and wx.CHK_UNDETERMINED when it's in +the undetermined state. Raises an exceptiion when the function is +used with a 2-state CheckBox."); DocDeclStr( void, Set3StateValue(wxCheckBoxState state), - "Sets the CheckBox to the given state. The state parameter can be\n" - "one of the following: wx.CHK_UNCHECKED (Check is off), wx.CHK_CHECKED\n" - "(Check is on) or wx.CHK_UNDETERMINED (Check is mixed). Raises an\n" - "exception when the CheckBox is a 2-state checkbox and setting the state\n" - "to wx.CHK_UNDETERMINED."); + "Sets the CheckBox to the given state. The state parameter can be one +of the following: wx.CHK_UNCHECKED (Check is off), wx.CHK_CHECKED (the +Check is on) or wx.CHK_UNDETERMINED (Check is mixed). Raises an +exception when the CheckBox is a 2-state checkbox and setting the +state to wx.CHK_UNDETERMINED."); DocDeclStr( bool, Is3State() const, @@ -134,7 +147,8 @@ public: DocDeclStr( bool, Is3rdStateAllowedForUser() const, - "Returns whether or not the user can set the CheckBox to the third state."); + "Returns whether or not the user can set the CheckBox to the third +state."); }; diff --git a/wxPython/src/_choice.i b/wxPython/src/_choice.i index a4b46b980e..fa5deae4ca 100644 --- a/wxPython/src/_choice.i +++ b/wxPython/src/_choice.i @@ -22,12 +22,15 @@ MAKE_CONST_WXSTRING(ChoiceNameStr); DocStr(wxChoice, -"A Choice control is used to select one of a list of strings. Unlike a ListBox, -only the selection is visible until the user pulls down the menu of choices."); - -RefDoc(wxChoice, " - Events - EVT_CHOICE: Sent when an item in the list is selected. +"A Choice control is used to select one of a list of strings. +Unlike a `wx.ListBox`, only the selection is visible until the +user pulls down the menu of choices. + +Events +------ + ================ ========================================== + EVT_CHOICE Sent when an item in the list is selected. + ================ ========================================== "); @@ -47,9 +50,9 @@ public: long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = wxPyChoiceNameStr), - "__init__(Window parent, int id, Point pos=DefaultPosition, Size size=DefaultSize,\n" - " List choices=[], long style=0, Validator validator=DefaultValidator,\n" - " String name=ChoiceNameStr) -> Choice", + "__init__(Window parent, int id, Point pos=DefaultPosition, Size size=DefaultSize, + List choices=[], long style=0, Validator validator=DefaultValidator, + String name=ChoiceNameStr) -> Choice", "Create and show a Choice control"); DocCtorStrName( @@ -66,9 +69,9 @@ public: long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = wxPyChoiceNameStr), - "Create(Window parent, int id, Point pos=DefaultPosition, Size size=DefaultSize,\n" - " List choices=[], long style=0, Validator validator=DefaultValidator,\n" - " String name=ChoiceNameStr) -> bool", + "Create(Window parent, int id, Point pos=DefaultPosition, Size size=DefaultSize, + List choices=[], long style=0, Validator validator=DefaultValidator, + String name=ChoiceNameStr) -> bool", "Actually create the GUI Choice control for 2-phase creation"); diff --git a/wxPython/src/_clipbrd.i b/wxPython/src/_clipbrd.i index f0a2dde60e..7fd9be4534 100644 --- a/wxPython/src/_clipbrd.i +++ b/wxPython/src/_clipbrd.i @@ -20,33 +20,38 @@ %} DocStr(wxClipboard, - -"wx.Clipboard represents the system clipboard and provides methods to copy data -to or paste data from it. Normally, you should only use wx.TheClipboard which -is a reference to a global wx.Clipboard instance. - -Call wx.TheClipboard.Open to get ownership of the clipboard. If this operation -returns True, you now own the clipboard. Call wx.TheClipboard.SetData to put -data on the clipboard, or wx.TheClipboard.GetData to retrieve data from the -clipboard. Call wx.TheClipboard.Close to close the clipboard and relinquish -ownership. You should keep the clipboard open only momentarily. +"wx.Clipboard represents the system clipboard and provides methods to +copy data to it or paste data from it. Normally, you should only use +``wx.TheClipboard`` which is a reference to a global wx.Clipboard +instance. + +Call ``wx.TheClipboard``'s `Open` method to get ownership of the +clipboard. If this operation returns True, you now own the +clipboard. Call `SetData` to put data on the clipboard, or `GetData` +to retrieve data from the clipboard. Call `Close` to close the +clipboard and relinquish ownership. You should keep the clipboard open +only momentarily. + +:see: `wx.DataObject` "); class wxClipboard : public wxObject { public: - DocCtorStr( wxClipboard(), "" ); + DocCtorStr( + wxClipboard(), + ""); ~wxClipboard(); DocDeclStr( virtual bool , Open(), - "Call this function to open the clipboard before calling SetData\n" - "and GetData. Call Close when you have finished with the clipboard.\n" - "You should keep the clipboard open for only a very short time.\n" - "Returns true on success. "); + "Call this function to open the clipboard before calling SetData and +GetData. Call Close when you have finished with the clipboard. You +should keep the clipboard open for only a very short time. Returns +True on success."); DocDeclStr( @@ -64,50 +69,54 @@ public: DocDeclStr( virtual bool , AddData( wxDataObject *data ), - "Call this function to add the data object to the clipboard. You\n" - "may call this function repeatedly after having cleared the clipboard.\n" - "After this function has been called, the clipboard owns the data, so\n" - "do not delete the data explicitly."); + "Call this function to add the data object to the clipboard. You may +call this function repeatedly after having cleared the clipboard. +After this function has been called, the clipboard owns the data, so +do not delete the data explicitly. + +:see: `wx.DataObject`"); DocDeclStr( virtual bool , SetData( wxDataObject *data ), - "Set the clipboard data, this is the same as Clear followed by AddData."); + "Set the clipboard data, this is the same as `Clear` followed by +`AddData`. + +:see: `wx.DataObject`"); %clear wxDataObject *data; - DocDeclStr( virtual bool , IsSupported( const wxDataFormat& format ), - "Returns True if the given format is available in the data object(s) on\n" - "the clipboard."); + "Returns True if the given format is available in the data object(s) on +the clipboard."); DocDeclStr( virtual bool , GetData( wxDataObject& data ), - "Call this function to fill data with data on the clipboard, if available\n" - "in the required format. Returns true on success."); + "Call this function to fill data with data on the clipboard, if +available in the required format. Returns true on success."); DocDeclStr( virtual void , Clear(), - "Clears data from the clipboard object and also the system's clipboard\n" - "if possible."); + "Clears data from the clipboard object and also the system's clipboard +if possible."); DocDeclStr( virtual bool , Flush(), - "Flushes the clipboard: this means that the data which is currently on\n" - "clipboard will stay available even after the application exits (possibly\n" - "eating memory), otherwise the clipboard will be emptied on exit.\n" - "Returns False if the operation is unsuccesful for any reason."); + "Flushes the clipboard: this means that the data which is currently on +clipboard will stay available even after the application exits, +possibly eating memory, otherwise the clipboard will be emptied on +exit. Returns False if the operation is unsuccesful for any reason."); DocDeclStr( virtual void , UsePrimarySelection( bool primary = True ), - "On platforms supporting it (the X11 based platforms), selects the so\n" - "called PRIMARY SELECTION as the clipboard as opposed to the normal\n" - "clipboard, if primary is True."); + "On platforms supporting it (the X11 based platforms), selects the +so called PRIMARY SELECTION as the clipboard as opposed to the +normal clipboard, if primary is True."); }; @@ -121,8 +130,8 @@ wxClipboard* const wxTheClipboard; DocStr(wxClipboardLocker, -"A helpful class for opening the clipboard and automatically closing it when -the locker is destroyed."); +"A helpful class for opening the clipboard and automatically +closing it when the locker is destroyed."); class wxClipboardLocker { @@ -131,8 +140,8 @@ public: ~wxClipboardLocker(); DocStr(__nonzero__, - "A ClipboardLocker instance evaluates to True if the clipboard was\n" - "successfully opened.") + "A ClipboardLocker instance evaluates to True if the clipboard was +successfully opened.") %extend { bool __nonzero__() { return !!(*self); } } diff --git a/wxPython/src/_cmndlgs.i b/wxPython/src/_cmndlgs.i index 8cf834ec39..e898f3fabe 100644 --- a/wxPython/src/_cmndlgs.i +++ b/wxPython/src/_cmndlgs.i @@ -27,7 +27,9 @@ MAKE_CONST_WXSTRING(MessageBoxCaptionStr); DocStr(wxColourData, - "This class holds a variety of information related to colour dialogs."); +"This class holds a variety of information related to the colour +chooser dialog, used to transfer settings and results to and from the +`wx.ColourDialog`."); class wxColourData : public wxObject { public: @@ -40,9 +42,9 @@ public: DocDeclStr( bool , GetChooseFull(), - "Under Windows, determines whether the Windows colour dialog will display\n" - "the full dialog with custom colour selection controls. Has no meaning\n" - "under other platforms. The default value is true."); + "Under Windows, determines whether the Windows colour dialog will +display the full dialog with custom colour selection controls. Has no +meaning under other platforms. The default value is true."); DocDeclStr( wxColour , GetColour(), @@ -50,27 +52,31 @@ public: DocDeclStr( wxColour , GetCustomColour(int i), - "Gets the i'th custom colour associated with the colour dialog. i should\n" - "be an integer between 0 and 15. The default custom colours are all white."); + "Gets the i'th custom colour associated with the colour dialog. i +should be an integer between 0 and 15. The default custom colours are +all white."); DocDeclStr( void , SetChooseFull(int flag), - "Under Windows, tells the Windows colour dialog to display the full dialog\n" - "with custom colour selection controls. Under other platforms, has no effect.\n" - "The default value is true."); + "Under Windows, tells the Windows colour dialog to display the full +dialog with custom colour selection controls. Under other platforms, +has no effect. The default value is true."); DocDeclStr( void , SetColour(const wxColour& colour), - "Sets the default colour for the colour dialog. The default colour is black."); + "Sets the default colour for the colour dialog. The default colour is +black."); DocDeclStr( void , SetCustomColour(int i, const wxColour& colour), - "Sets the i'th custom colour for the colour dialog. i should be an integer\n" - "between 0 and 15. The default custom colours are all white."); + "Sets the i'th custom colour for the colour dialog. i should be an +integer between 0 and 15. The default custom colours are all white."); }; + + DocStr(wxColourDialog, "This class represents the colour chooser dialog."); @@ -80,12 +86,13 @@ public: DocCtorStr( wxColourDialog(wxWindow* parent, wxColourData* data = NULL), - "Constructor. Pass a parent window, and optionally a ColourData, which\n" - "will be copied to the colour dialog's internal ColourData instance."); + "Constructor. Pass a parent window, and optionally a `wx.ColourData`, +which will be copied to the colour dialog's internal ColourData +instance."); DocDeclStr( wxColourData& , GetColourData(), - "Returns a reference to the ColourData used by the dialog."); + "Returns a reference to the `wx.ColourData` used by the dialog."); }; @@ -93,14 +100,19 @@ public: DocStr(wxDirDialog, - "This class represents the directory chooser dialog."); - -RefDoc(wxDirDialog, " - Styles - wxDD_NEW_DIR_BUTTON Add \"Create new directory\" button and allow - directory names to be editable. On Windows the new - directory button is only available with recent - versions of the common dialogs."); + "wx.DirDialog allows the user to select a directory by browising the +file system. + + +Window Styles +-------------- + ==================== ========================================== + wx.DD_NEW_DIR_BUTTON Add 'Create new directory' button and allow + directory names to be editable. On Windows + the new directory button is only available + with recent versions of the common dialogs. + ==================== ========================================== +"); class wxDirDialog : public wxDialog { public: @@ -145,40 +157,46 @@ public: //--------------------------------------------------------------------------- DocStr(wxFileDialog, - "This class represents the file chooser dialog."); - -RefDoc(wxFileDialog, " -In Windows, this is the common file selector dialog. In X, this is a file -selector box with somewhat less functionality. The path and filename are -distinct elements of a full file pathname. If path is \"\", the current -directory will be used. If filename is \"\", no default filename will be -supplied. The wildcard determines what files are displayed in the file -selector, and file extension supplies a type extension for the required -filename. - -Both the X and Windows versions implement a wildcard filter. Typing a filename -containing wildcards (*, ?) in the filename text item, and clicking on Ok, -will result in only those files matching the pattern being displayed. The -wildcard may be a specification for multiple types of file with a description -for each, such as: +"wx.FileDialog allows the user to select one or more files from the +filesystem. + +In Windows, this is the common file selector dialog. On X based +platforms a generic alternative is used. The path and filename are +distinct elements of a full file pathname. If path is \"\", the +current directory will be used. If filename is \"\", no default +filename will be supplied. The wildcard determines what files are +displayed in the file selector, and file extension supplies a type +extension for the required filename. + +Both the X and Windows versions implement a wildcard filter. Typing a +filename containing wildcards (*, ?) in the filename text item, and +clicking on Ok, will result in only those files matching the pattern +being displayed. The wildcard may be a specification for multiple +types of file with a description for each, such as:: \"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif\" - Styles + +Window Styles +-------------- + ================== ========================================== wx.OPEN This is an open dialog. wx.SAVE This is a save dialog. - wx.HIDE_READONLY For open dialog only: hide the checkbox allowing to - open the file in read-only mode. + wx.HIDE_READONLY For open dialog only: hide the checkbox + allowing to open the file in read-only mode. - wx.OVERWRITE_PROMPT For save dialog only: prompt for a confirmation if a - file will be overwritten. + wx.OVERWRITE_PROMPT For save dialog only: prompt for a confirmation + if a file will be overwritten. - wx.MULTIPLE For open dialog only: allows selecting multiple files. + wx.MULTIPLE For open dialog only: allows selecting multiple + files. - wx.CHANGE_DIR Change the current working directory to the directory - where the file(s) chosen by the user are. + wx.CHANGE_DIR Change the current working directory to the + directory where the file(s) chosen by the user + are. + ================== ========================================== "); @@ -206,8 +224,8 @@ public: DocDeclStr( void , SetPath(const wxString& path), - "Sets the path (the combined directory and filename that will\n" - "be returned when the dialog is dismissed)."); + "Sets the path (the combined directory and filename that will be +returned when the dialog is dismissed)."); DocDeclStr( void , SetDirectory(const wxString& dir), @@ -219,8 +237,11 @@ public: DocDeclStr( void , SetWildcard(const wxString& wildCard), - "Sets the wildcard, which can contain multiple file types, for example:\n" - " \"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif\""); + "Sets the wildcard, which can contain multiple file types, for +example:: + + \"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif\" +"); DocDeclStr( void , SetStyle(long style), @@ -257,21 +278,21 @@ public: DocDeclStr( int , GetFilterIndex() const, - "Returns the index into the list of filters supplied, optionally, in\n" - "the wildcard parameter. Before the dialog is shown, this is the index\n" - "which will be used when the dialog is first displayed. After the dialog\n" - "is shown, this is the index selected by the user."); + "Returns the index into the list of filters supplied, optionally, in +the wildcard parameter. Before the dialog is shown, this is the index +which will be used when the dialog is first displayed. After the +dialog is shown, this is the index selected by the user."); DocStr(GetFilenames, - "Returns a list of filenames chosen in the dialog. This function should\n" - "only be used with the dialogs which have wx.MULTIPLE style, use\n" - "GetFilename for the others."); + "Returns a list of filenames chosen in the dialog. This function +should only be used with the dialogs which have wx.MULTIPLE style, use +GetFilename for the others."); DocStr(GetPaths, - "Fills the array paths with the full paths of the files chosen. This\n" - "function should only be used with the dialogs which have wx.MULTIPLE style,\n" - "use GetPath for the others."); + "Fills the array paths with the full paths of the files chosen. This +function should only be used with the dialogs which have wx.MULTIPLE +style, use GetPath for the others."); %extend { PyObject* GetFilenames() { @@ -330,16 +351,17 @@ public: int choices=0, wxString* choices_array, long style = wxCHOICEDLG_STYLE, const wxPoint& pos = wxDefaultPosition), - "__init__(Window parent, String message, String caption,\n" - " List choices=[], long style=CHOICEDLG_STYLE,\n" - " Point pos=DefaultPosition) -> MultiChoiceDialog", + "__init__(Window parent, String message, String caption, + List choices=[], long style=CHOICEDLG_STYLE, + Point pos=DefaultPosition) -> MultiChoiceDialog", "Constructor. Use ShowModal method to show the dialog."); DocDeclAStr( void, SetSelections(const wxArrayInt& selections), "SetSelections(List selections)", - "Specify the items in the list that shoudl be selected, using a list of integers."); + "Specify the items in the list that should be selected, using a list of +integers."); DocAStr(GetSelections, "GetSelections() -> [selections]", @@ -362,9 +384,9 @@ public: %pythonAppend wxSingleChoiceDialog "self._setOORInfo(self)" DocAStr(wxSingleChoiceDialog, - "__init__(Window parent, String message, String caption,\n" - " List choices=[], long style=CHOICEDLG_STYLE,\n" - " Point pos=DefaultPosition) -> SingleChoiceDialog", + "__init__(Window parent, String message, String caption, + List choices=[], long style=CHOICEDLG_STYLE, + Point pos=DefaultPosition) -> SingleChoiceDialog", "Constructor. Use ShowModal method to show the dialog."); %extend { @@ -416,8 +438,8 @@ public: DocDeclStr( wxString , GetValue(), - "Returns the text that the user has entered if the user has pressed OK,\n" - "or the original value if the user has pressed Cancel."); + "Returns the text that the user has entered if the user has pressed OK, +or the original value if the user has pressed Cancel."); DocDeclStr( void , SetValue(const wxString& value), @@ -428,7 +450,8 @@ public: DocStr(wxFontData, - "This class holds a variety of information related to font dialogs."); + "This class holds a variety of information related to font dialogs and +is used to transfer settings to and results from a `wx.FontDialog`."); class wxFontData : public wxObject { @@ -438,18 +461,20 @@ public: DocDeclStr( void , EnableEffects(bool enable), - "Enables or disables 'effects' under MS Windows only. This refers\n" - "to the controls for manipulating colour, strikeout and underline\n" - "properties. The default value is true."); + "Enables or disables 'effects' under MS Windows only. This refers to +the controls for manipulating colour, strikeout and underline +properties. The default value is true."); DocDeclStr( bool , GetAllowSymbols(), - "Under MS Windows, returns a flag determining whether symbol fonts can be\n" - "selected. Has no effect on other platforms. The default value is true."); + "Under MS Windows, returns a flag determining whether symbol fonts can +be selected. Has no effect on other platforms. The default value is +true."); DocDeclStr( wxColour , GetColour(), - "Gets the colour associated with the font dialog. The default value is black."); + "Gets the colour associated with the font dialog. The default value is +black."); DocDeclStr( wxFont , GetChosenFont(), @@ -461,27 +486,28 @@ public: DocDeclStr( wxFont , GetInitialFont(), - "Gets the font that will be initially used by the font dialog. This should have\n" - "previously been set by the application."); + "Gets the font that will be initially used by the font dialog. This +should have previously been set by the application."); DocDeclStr( bool , GetShowHelp(), - "Returns true if the Help button will be shown (Windows only). The default\n" - "value is false."); + "Returns true if the Help button will be shown (Windows only). The +default value is false."); DocDeclStr( void , SetAllowSymbols(bool allowSymbols), - "Under MS Windows, determines whether symbol fonts can be selected. Has no\n" - "effect on other platforms. The default value is true."); + "Under MS Windows, determines whether symbol fonts can be selected. Has +no effect on other platforms. The default value is true."); DocDeclStr( void , SetChosenFont(const wxFont& font), - "Sets the font that will be returned to the user (for internal use only)."); + "Sets the font that will be returned to the user (normally for internal +use only)."); DocDeclStr( void , SetColour(const wxColour& colour), - "Sets the colour that will be used for the font foreground colour. The default\n" - "colour is black."); + "Sets the colour that will be used for the font foreground colour. The +default colour is black."); DocDeclStr( void , SetInitialFont(const wxFont& font), @@ -489,34 +515,40 @@ public: DocDeclStr( void , SetRange(int min, int max), - "Sets the valid range for the font point size (Windows only). The default is\n" - "0, 0 (unrestricted range)."); + "Sets the valid range for the font point size (Windows only). The +default is 0, 0 (unrestricted range)."); DocDeclStr( void , SetShowHelp(bool showHelp), - "Determines whether the Help button will be displayed in the font dialog\n" - "(Windows only). The default value is false."); + "Determines whether the Help button will be displayed in the font +dialog (Windows only). The default value is false."); }; DocStr(wxFontDialog, - "This class represents the font chooser dialog."); + "wx.FontDialog allows the user to select a system font and its attributes. + +:see: `wx.FontData` +"); class wxFontDialog : public wxDialog { public: %pythonAppend wxFontDialog "self._setOORInfo(self)" DocStr(wxFontDialog, - "Constructor. Pass a parent window and the FontData object to be\n" - "used to initialize the dialog controls."); + "Constructor. Pass a parent window and the `wx.FontData` object to be +used to initialize the dialog controls. Call `ShowModal` to display +the dialog. If ShowModal returns ``wx.ID_OK`` then you can fetch the +results with via the `wx.FontData` returned by `GetFontData`."); wxFontDialog(wxWindow* parent, const wxFontData& data); DocDeclStr( wxFontData& , GetFontData(), - "Returns a reference to the internal FontData used by the FontDialog."); + "Returns a reference to the internal `wx.FontData` used by the +wx.FontDialog."); }; @@ -524,32 +556,28 @@ public: DocStr(wxMessageDialog, - "This class provides a dialog that shows a single or multi-line message, with\n" - "a choice of OK, Yes, No and Cancel buttons."); - -RefDoc(wxMessageDialog, " - Styles - wx.OK: Show an OK button. - - wx.CANCEL: Show a Cancel button. - - wx.YES_NO: Show Yes and No buttons. - - wx.YES_DEFAULT: Used with wxYES_NO, makes Yes button the default - which is the default behaviour. - - wx.NO_DEFAULT: Used with wxYES_NO, makes No button the default. - - wx.ICON_EXCLAMATION: Shows an exclamation mark icon. - - wx.ICON_HAND: Shows an error icon. - - wx.ICON_ERROR: Shows an error icon - the same as wxICON_HAND. - - wx.ICON_QUESTION: Shows a question mark icon. - - wx.ICON_INFORMATION: Shows an information (i) icon. - - wx.STAY_ON_TOP: The message box stays on top of all other window, even those of the other applications (Windows only). +"This class provides a simple dialog that shows a single or multi-line +message, with a choice of OK, Yes, No and/or Cancel buttons. + + +Window Styles +-------------- + ================= ============================================= + wx.OK Show an OK button. + wx.CANCEL Show a Cancel button. + wx.YES_NO Show Yes and No buttons. + wx.YES_DEFAULT Used with wxYES_NO, makes Yes button the + default - which is the default behaviour. + wx.NO_DEFAULT Used with wxYES_NO, makes No button the default. + wx.ICON_EXCLAMATION Shows an exclamation mark icon. + wx.ICON_HAND Shows an error icon. + wx.ICON_ERROR Shows an error icon - the same as wxICON_HAND. + wx.ICON_QUESTION Shows a question mark icon. + wx.ICON_INFORMATION Shows an information (i) icon. + wx.STAY_ON_TOP The message box stays on top of all other + window, even those of the other applications + (Windows only). + ================= ============================================= "); @@ -558,12 +586,14 @@ public: %pythonAppend wxMessageDialog "self._setOORInfo(self)" RefDoc(wxMessageDialog, ""); // turn it off for the ctors - - wxMessageDialog(wxWindow* parent, - const wxString& message, - const wxString& caption = wxPyMessageBoxCaptionStr, - long style = wxOK | wxCANCEL | wxCENTRE, - const wxPoint& pos = wxDefaultPosition); + + DocCtorStr( + wxMessageDialog(wxWindow* parent, + const wxString& message, + const wxString& caption = wxPyMessageBoxCaptionStr, + long style = wxOK | wxCANCEL | wxCENTRE, + const wxPoint& pos = wxDefaultPosition), + "Constructor, use `ShowModal` to display the dialog."); }; @@ -571,34 +601,35 @@ public: DocStr(wxProgressDialog, - "A dialog that shows a short message and a progress bar. Optionally, it can\n" - "display an ABORT button."); - -RefDoc(wxProgressDialog, " - Styles - - wx.PD_APP_MODAL: Make the progress dialog modal. If this flag is - not given, it is only \"locally\" modal - that is - the input to the parent window is disabled, - but not to the other ones. - - wx.PD_AUTO_HIDE: Causes the progress dialog to disappear from screen - as soon as the maximum value of the progress - meter has been reached. - - wx.PD_CAN_ABORT: This flag tells the dialog that it should have - a \"Cancel\" button which the user may press. If - this happens, the next call to Update() will - return false. - - wx.PD_ELAPSED_TIME: This flag tells the dialog that it should show - elapsed time (since creating the dialog). - - wx.PD_ESTIMATED_TIME: This flag tells the dialog that it should show - estimated time. - - wx.PD_REMAINING_TIME: This flag tells the dialog that it should show - remaining time. +"A dialog that shows a short message and a progress bar. Optionally, it +can display an ABORT button. + +Window Styles +-------------- + ================= ============================================= + wx.PD_APP_MODAL Make the progress dialog modal. If this flag is + not given, it is only \"locally\" modal - + that is the input to the parent window is + disabled, but not to the other ones. + + wx.PD_AUTO_HIDE Causes the progress dialog to disappear from + screen as soon as the maximum value of the + progress meter has been reached. + + wx.PD_CAN_ABORT This flag tells the dialog that it should have + a \"Cancel\" button which the user may press. If + this happens, the next call to Update() will + return false. + + wx.PD_ELAPSED_TIME This flag tells the dialog that it should show + elapsed time (since creating the dialog). + + wx.PD_ESTIMATED_TIME This flag tells the dialog that it should show + estimated time. + + wx.PD_REMAINING_TIME This flag tells the dialog that it should show + remaining time. + ================= ============================================= "); @@ -614,21 +645,24 @@ public: int maximum = 100, wxWindow* parent = NULL, int style = wxPD_AUTO_HIDE | wxPD_APP_MODAL ), - "Constructor. Creates the dialog, displays it and disables user input for other\n" - "windows, or, if wxPD_APP_MODAL flag is not given, for its parent window only."); + "Constructor. Creates the dialog, displays it and disables user input +for other windows, or, if wx.PD_APP_MODAL flag is not given, for its +parent window only."); DocDeclStr( virtual bool , Update(int value, const wxString& newmsg = wxPyEmptyString), - "Updates the dialog, setting the progress bar to the new value and, if given\n" - "changes the message above it. Returns true unless the Cancel button has been\n" - "pressed.\n\n" - "If false is returned, the application can either immediately destroy the\n" - "dialog or ask the user for the confirmation and if the abort is not confirmed\n" - "the dialog may be resumed with Resume function."); + "Updates the dialog, setting the progress bar to the new value and, if +given changes the message above it. Returns true unless the Cancel +button has been pressed. + +If false is returned, the application can either immediately destroy +the dialog or ask the user for the confirmation and if the abort is +not confirmed the dialog may be resumed with Resume function."); DocDeclStr( void , Resume(), - "Can be used to continue with the dialog, after the user had chosen to abort."); + "Can be used to continue with the dialog, after the user had chosen to +abort."); }; @@ -697,8 +731,8 @@ public: DocDeclStr( int , GetFlags(), - "Get the currently selected flags: this is the combination of\n" - "wx.FR_DOWN, wx.FR_WHOLEWORD and wx.FR_MATCHCASE flags."); + "Get the currently selected flags: this is the combination of +wx.FR_DOWN, wx.FR_WHOLEWORD and wx.FR_MATCHCASE flags."); DocDeclStr( const wxString& , GetFindString(), @@ -706,8 +740,8 @@ public: DocDeclStr( const wxString& , GetReplaceString(), - "Return the string to replace the search string with (only\n" - "for replace and replace all events)."); + "Return the string to replace the search string with (only for replace +and replace all events)."); DocDeclStr( wxFindReplaceDialog *, GetDialog(), @@ -729,22 +763,26 @@ public: DocStr(wxFindReplaceData, -"FindReplaceData holds the data for FindReplaceDialog. It is used to initialize -the dialog with the default values and will keep the last values from the -dialog when it is closed. It is also updated each time a wxFindDialogEvent is -generated so instead of using the wxFindDialogEvent methods you can also -directly query this object. - -Note that all SetXXX() methods may only be called before showing the dialog -and calling them has no effect later. - - Flags - wxFR_DOWN: downward search/replace selected (otherwise, upwards) - - wxFR_WHOLEWORD: whole word search/replace selected - - wxFR_MATCHCASE: case sensitive search/replace selected (otherwise, - case insensitive) +"wx.FindReplaceData holds the data for wx.FindReplaceDialog. It is used +to initialize the dialog with the default values and will keep the +last values from the dialog when it is closed. It is also updated each +time a `wx.FindDialogEvent` is generated so instead of using the +`wx.FindDialogEvent` methods you can also directly query this object. + +Note that all SetXXX() methods may only be called before showing the +dialog and calling them has no effect later. + +Flags +----- + ================ =============================================== + wx.FR_DOWN Downward search/replace selected (otherwise, + upwards) + + wx.FR_WHOLEWORD Whole word search/replace selected + + wx.FR_MATCHCASE Case sensitive search/replace selected + (otherwise, case insensitive) + ================ =============================================== "); @@ -790,23 +828,27 @@ public: DocStr(wxFindReplaceDialog, -"FindReplaceDialog is a standard modeless dialog which is used to allow the -user to search for some text (and possibly replace it with something -else). The actual searching is supposed to be done in the owner window which -is the parent of this dialog. Note that it means that unlike for the other -standard dialogs this one must have a parent window. Also note that there is -no way to use this dialog in a modal way; it is always, by design and -implementation, modeless."); +"wx.FindReplaceDialog is a standard modeless dialog which is used to +allow the user to search for some text (and possibly replace it with +something else). The actual searching is supposed to be done in the +owner window which is the parent of this dialog. Note that it means +that unlike for the other standard dialogs this one must have a parent +window. Also note that there is no way to use this dialog in a modal +way; it is always, by design and implementation, modeless. + + +Window Styles +------------- -RefDoc(wxFindReplaceDialog, " - Styles - wx.FR_REPLACEDIALOG: replace dialog (otherwise find dialog) + ===================== ========================================= + wx.FR_REPLACEDIALOG replace dialog (otherwise find dialog) - wx.FR_NOUPDOWN: don't allow changing the search direction + wx.FR_NOUPDOWN don't allow changing the search direction - wx.FR_NOMATCHCASE: don't allow case sensitive searching + wx.FR_NOMATCHCASE don't allow case sensitive searching - wx.FR_NOWHOLEWORD: don't allow whole word searching + wx.FR_NOWHOLEWORD don't allow whole word searching + ===================== ========================================= "); class wxFindReplaceDialog : public wxDialog { @@ -821,8 +863,8 @@ public: wxFindReplaceData *data, const wxString &title, int style = 0), - "Create a FindReplaceDialog. The parent and data parameters must be\n" - "non-None. Use Show to display the dialog."); + "Create a FindReplaceDialog. The parent and data parameters must be +non-None. Use Show to display the dialog."); DocCtorStrName( wxFindReplaceDialog(), @@ -831,10 +873,8 @@ public: DocDeclStr( - bool , Create(wxWindow *parent, - wxFindReplaceData *data, - const wxString &title, - int style = 0), + bool , Create(wxWindow *parent, wxFindReplaceData *data, + const wxString &title, int style = 0), "Create the dialog, for 2-phase create."); diff --git a/wxPython/src/_config.i b/wxPython/src/_config.i index 7d15765a19..ec06be39c7 100644 --- a/wxPython/src/_config.i +++ b/wxPython/src/_config.i @@ -313,7 +313,7 @@ public: DocDeclStr( virtual bool , DeleteAll(), "Delete the whole underlying object (disk file, registry key, ...)\n" - "primarly intended for use by desinstallation routine."); + "primarly intended for use by deinstallation routine."); diff --git a/wxPython/src/_dc.i b/wxPython/src/_dc.i index 55e415d87c..d48f246665 100644 --- a/wxPython/src/_dc.i +++ b/wxPython/src/_dc.i @@ -56,6 +56,8 @@ public: #if defined(wxUSE_DC_OLD_METHODS) bool FloodFill(wxCoord x, wxCoord y, const wxColour& col, int style = wxFLOOD_SURFACE); + %name(FloodFillPoint) bool FloodFill(const wxPoint& pt, const wxColour& col, int style = wxFLOOD_SURFACE); + //bool GetPixel(wxCoord x, wxCoord y, wxColour *col) const; %extend { wxColour GetPixel(wxCoord x, wxCoord y) { @@ -63,26 +65,66 @@ public: self->GetPixel(x, y, &col); return col; } + wxColour GetPixelPoint(const wxPoint& pt) { + wxColour col; + self->GetPixel(pt, &col); + return col; + } } + void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2); + %name(DrawLinePoint) void DrawLine(const wxPoint& pt1, const wxPoint& pt2); + void CrossHair(wxCoord x, wxCoord y); + %name(CrossHairPoint) void CrossHair(const wxPoint& pt); + void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, wxCoord xc, wxCoord yc); + %name(DrawArcPoint) void DrawArc(const wxPoint& pt1, const wxPoint& pt2, const wxPoint& centre); + void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + %name(DrawCheckMarkRect) void DrawCheckMark(const wxRect& rect); + void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord w, wxCoord h, double sa, double ea); + %name(DrawEllipticArcPtSz) void DrawEllipticArc(const wxPoint& pt, const wxSize& sz, double sa, double ea); + void DrawPoint(wxCoord x, wxCoord y); + %name(DrawPointPoint) void DrawPoint(const wxPoint& pt); + void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height); %name(DrawRectangleRect)void DrawRectangle(const wxRect& rect); + %name(DrawRectanglePtSz) void DrawRectangle(const wxPoint& pt, const wxSize& sz); + void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height, double radius); + %name(DrawRoundedRectangleRect) void DrawRoundedRectangle(const wxRect& r, double radius); + %name(DrawRoundedRectanglePtSz) void DrawRoundedRectangle(const wxPoint& pt, const wxSize& sz, double radius); + void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); + %name(DrawCirclePoint) void DrawCircle(const wxPoint& pt, wxCoord radius); + void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + %name(DrawEllipseRect) void DrawEllipse(const wxRect& rect); + %name(DrawEllipsePtSz) void DrawEllipse(const wxPoint& pt, const wxSize& sz); + void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y); + %name(DrawIconPoint) void DrawIcon(const wxIcon& icon, const wxPoint& pt); + void DrawBitmap(const wxBitmap &bmp, wxCoord x, wxCoord y, bool useMask = False); + %name(DrawBitmapPoint) void DrawBitmap(const wxBitmap &bmp, const wxPoint& pt, bool useMask = False); + void DrawText(const wxString& text, wxCoord x, wxCoord y); + %name(DrawTextPoint) void DrawText(const wxString& text, const wxPoint& pt); + void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, double angle); + %name(DrawRotatedTextPoint) void DrawRotatedText(const wxString& text, const wxPoint& pt, double angle); + bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, wxCoord height, wxDC *source, wxCoord xsrc, wxCoord ysrc, int rop = wxCOPY, bool useMask = False, wxCoord xsrcMask = -1, wxCoord ysrcMask = -1); + %name(BlitPtSz) bool Blit(const wxPoint& destPt, const wxSize& sz, + wxDC *source, const wxPoint& srcPt, + int rop = wxCOPY, bool useMask = False, + const wxPoint& srcPtMask = wxDefaultPosition); @@ -105,6 +147,7 @@ public: return col; } } + %name(DrawLineXY) void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2); void DrawLine(const wxPoint& pt1, const wxPoint& pt2); diff --git a/wxPython/src/_event_ex.py b/wxPython/src/_event_ex.py index 03663716d2..622bed6de9 100644 --- a/wxPython/src/_event_ex.py +++ b/wxPython/src/_event_ex.py @@ -23,12 +23,14 @@ class PyEventBinder(object): for et in self.evtType: target.Connect(id1, id2, et, function) + def Unbind(self, target, id1, id2): """Remove an event binding.""" success = 0 for et in self.evtType: success += target.Disconnect(id1, id2, et) return success != 0 + def __call__(self, *args): """ diff --git a/wxPython/src/_evthandler.i b/wxPython/src/_evthandler.i index 5a12a452d8..2fed5cab97 100644 --- a/wxPython/src/_evthandler.i +++ b/wxPython/src/_evthandler.i @@ -113,7 +113,7 @@ public: """ if source is not None: id = source.GetId() - event.Unbind(self, id, id2) + return event.Unbind(self, id, id2) } diff --git a/wxPython/src/_gdicmn.i b/wxPython/src/_gdicmn.i index 96355a11ea..5b86c9a6e0 100644 --- a/wxPython/src/_gdicmn.i +++ b/wxPython/src/_gdicmn.i @@ -130,6 +130,7 @@ public: ~wxSize(); +// None/NULL is now handled properly by the typemap, so these are not needed. // %extend { // bool __eq__(const wxSize* other) { return other ? (*self == *other) : False; } // bool __ne__(const wxSize* other) { return other ? (*self != *other) : True; } diff --git a/wxPython/src/_image.i b/wxPython/src/_image.i index f5d4b36bd3..08d530f0eb 100644 --- a/wxPython/src/_image.i +++ b/wxPython/src/_image.i @@ -83,24 +83,14 @@ public: %name(ImageFromMime) wxImage(const wxString& name, const wxString& mimetype, int index = -1); %name(ImageFromStream) wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1); %name(ImageFromStreamMime) wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1 ); - - - %extend { - - %nokwargs wxImage(int width=0, int height=0, bool clear = True); - %nokwargs wxImage(const wxSize& size, bool clear = True); %name(EmptyImage) wxImage(int width=0, int height=0, bool clear = True) { if (width > 0 && height > 0) return new wxImage(width, height, clear); else return new wxImage; } - %name(EmptyImage) wxImage(const wxSize& size, bool clear = True) { - return new wxImage(size.x, size.y, clear); - } - - + %name(ImageFromBitmap) wxImage(const wxBitmap &bitmap) { return new wxImage(bitmap.ConvertToImage()); } diff --git a/wxPython/src/_sizers.i b/wxPython/src/_sizers.i index f6c73d0b76..bf9aeaeaeb 100644 --- a/wxPython/src/_sizers.i +++ b/wxPython/src/_sizers.i @@ -271,16 +271,30 @@ public: %pythoncode { def AddMany(self, widgets): + """ + AddMany is a convenience method for adding several items + to a sizer at one time. Simply pass it a list of tuples, + where each tuple consists of the parameters that you + would normally pass to the `Add` method. + """ for childinfo in widgets: if type(childinfo) != type(()) or (len(childinfo) == 2 and type(childinfo[0]) == type(1)): childinfo = (childinfo, ) self.Add(*childinfo) %# for backwards compatibility only, please do not use in new code - AddWindow = AddSizer = AddSpacer = Add - PrependWindow = PrependSizer = PrependSpacer = Prepend - InsertWindow = InsertSizer = InsertSpacer = Insert - RemoveWindow = RemoveSizer = RemovePos = Remove + AddWindow = wx._deprecated(Add, "AddWindow is deprecated, use `Add` instead.") + AddSizer = wx._deprecated(Add, "AddSizer is deprecated, use `Add` instead.") + AddSpacer = wx._deprecated(Add, "AddSpacer is deprecated, use `Add` instead.") + PrependWindow = wx._deprecated(Prepend, "PrependWindow is deprecated, use `Prepend` instead.") + PrependSizer = wx._deprecated(Prepend, "PrependSizer is deprecated, use `Prepend` instead.") + PrependSpacer = wx._deprecated(Prepend, "PrependSpacer is deprecated, use `Prepend` instead.") + InsertWindow = wx._deprecated(Insert, "InsertWindow is deprecated, use `Insert` instead.") + InsertSizer = wx._deprecated(Insert, "InsertSizer is deprecated, use `Insert` instead.") + InsertSpacer = wx._deprecated(Insert, "InsertSpacer is deprecated, use `Insert` instead.") + RemoveWindow = wx._deprecated(Remove, "RemoveWindow is deprecated, use `Remove` instead.") + RemoveSizer = wx._deprecated(Remove, "RemoveSizer is deprecated, use `Remove` instead.") + RemovePos = wx._deprecated(Remove, "RemovePos is deprecated, use `Remove` instead.") def SetItemMinSize(self, item, *args): diff --git a/wxPython/src/calendar.i b/wxPython/src/calendar.i index b0466c88e1..262170001e 100644 --- a/wxPython/src/calendar.i +++ b/wxPython/src/calendar.i @@ -62,8 +62,8 @@ enum wxCalendarDateBorder //--------------------------------------------------------------------------- DocStr(wxCalendarDateAttr, -"A set of customization attributes for a calendar date, which can be used to -control the look of the Calendar object."); +"A set of customization attributes for a calendar date, which can be +used to control the look of the Calendar object."); class wxCalendarDateAttr { @@ -142,54 +142,66 @@ MAKE_CONST_WXSTRING(CalendarNameStr); DocStr(wxCalendarCtrl, - "The calendar control allows the user to pick a date interactively."); - -RefDoc(wxCalendarCtrl, - -"The CalendarCtrl displays a window containing several parts: the control to -pick the month and the year at the top (either or both of them may be -disabled) and a month area below them which shows all the days in the -month. The user can move the current selection using the keyboard and select -the date (generating EVT_CALENDAR event) by pressing or double -clicking it. - -It has advanced possibilities for the customization of its display. All global -settings (such as colours and fonts used) can, of course, be changed. But -also, the display style for each day in the month can be set independently -using CalendarDateAttr class. - -An item without custom attributes is drawn with the default colours and font -and without border, but setting custom attributes with SetAttr allows to -modify its appearance. Just create a custom attribute object and set it for -the day you want to be displayed specially A day may be marked as being a -holiday, (even if it is not recognized as one by wx.DateTime) by using the -SetHoliday method. - -As the attributes are specified for each day, they may change when the month -is changed, so you will often want to update them in an EVT_CALENDAR_MONTH -event handler. - - Styles - CAL_SUNDAY_FIRST: Show Sunday as the first day in the week - CAL_MONDAY_FIRST: Show Monday as the first day in the week - CAL_SHOW_HOLIDAYS: Highlight holidays in the calendar - CAL_NO_YEAR_CHANGE: Disable the year changing - CAL_NO_MONTH_CHANGE: Disable the month (and, implicitly, the year) changing - CAL_SHOW_SURROUNDING_WEEKS: Show the neighbouring weeks in the previous and next months - CAL_SEQUENTIAL_MONTH_SELECTION: Use alternative, more compact, style for the month and year selection controls. - -The default calendar style is wxCAL_SHOW_HOLIDAYS. - - Events - EVT_CALENDAR: A day was double clicked in the calendar. - EVT_CALENDAR_SEL_CHANGED: The selected date changed. - EVT_CALENDAR_DAY: The selected day changed. - EVT_CALENDAR_MONTH: The selected month changed. - EVT_CALENDAR_YEAR: The selected year changed. - EVT_CALENDAR_WEEKDAY_CLICKED: User clicked on the week day header - -Note that changing the selected date will result in either of -EVT_CALENDAR_DAY, MONTH or YEAR events and an EVT_CALENDAR_SEL_CHANGED event. +"The calendar control allows the user to pick a date interactively. + +The CalendarCtrl displays a window containing several parts: the +control to pick the month and the year at the top (either or both of +them may be disabled) and a month area below them which shows all the +days in the month. The user can move the current selection using the +keyboard and select the date (generating EVT_CALENDAR event) by +pressing or double clicking it. + +It has advanced possibilities for the customization of its +display. All global settings (such as colours and fonts used) can, of +course, be changed. But also, the display style for each day in the +month can be set independently using CalendarDateAttr class. + +An item without custom attributes is drawn with the default colours +and font and without border, but setting custom attributes with +SetAttr allows to modify its appearance. Just create a custom +attribute object and set it for the day you want to be displayed +specially A day may be marked as being a holiday, (even if it is not +recognized as one by wx.DateTime) by using the SetHoliday method. + +As the attributes are specified for each day, they may change when the +month is changed, so you will often want to update them in an +EVT_CALENDAR_MONTH event handler. + +Window Styles +------------- + ============================== ============================ + CAL_SUNDAY_FIRST Show Sunday as the first day + in the week + CAL_MONDAY_FIRST Show Monday as the first day + in the week + CAL_SHOW_HOLIDAYS Highlight holidays in the + calendar + CAL_NO_YEAR_CHANGE Disable the year changing + CAL_NO_MONTH_CHANGE Disable the month (and, + implicitly, the year) changing + CAL_SHOW_SURROUNDING_WEEKS Show the neighbouring weeks in + the previous and next months + CAL_SEQUENTIAL_MONTH_SELECTION Use alternative, more compact, + style for the month and year + selection controls. + +The default calendar style is CAL_SHOW_HOLIDAYS. + +Events +------- + =========================== ============================== + EVT_CALENDAR A day was double clicked in the + calendar. + EVT_CALENDAR_SEL_CHANGED The selected date changed. + EVT_CALENDAR_DAY The selected day changed. + EVT_CALENDAR_MONTH The selected month changed. + EVT_CALENDAR_YEAR The selected year changed. + EVT_CALENDAR_WEEKDAY_CLICKED User clicked on the week day + header + +Note that changing the selected date will result in one of +EVT_CALENDAR_DAY, MONTH or YEAR events and an EVT_CALENDAR_SEL_CHANGED +event. "); @@ -200,29 +212,34 @@ public: %pythonAppend wxCalendarCtrl "self._setOORInfo(self)" %pythonAppend wxCalendarCtrl() "" - DocStr(wxCalendarCtrl, "Create and show a calendar control."); RefDoc(wxCalendarCtrl, ""); // turn it off for the ctors - - wxCalendarCtrl(wxWindow *parent, - wxWindowID id=-1, - const wxDateTime& date = wxDefaultDateTime, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCAL_SHOW_HOLIDAYS | wxWANTS_CHARS, - const wxString& name = wxPyCalendarNameStr); - - DocStr(wxCalendarCtrl(), "Precreate a CalendarCtrl for 2-phase creation."); - %name(PreCalendarCtrl)wxCalendarCtrl(); + DocCtorStr( + wxCalendarCtrl(wxWindow *parent, + wxWindowID id=-1, + const wxDateTime& date = wxDefaultDateTime, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCAL_SHOW_HOLIDAYS | wxWANTS_CHARS, + const wxString& name = wxPyCalendarNameStr), + "Create and show a calendar control."); + + DocCtorStrName( + wxCalendarCtrl(), + "Precreate a CalendarCtrl for 2-phase creation.", + PreCalendarCtrl); - DocStr(Create, "Acutally create the GUI portion of the CalendarCtrl for 2-phase creation."); - bool Create(wxWindow *parent, - wxWindowID id, - const wxDateTime& date = wxDefaultDateTime, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCAL_SHOW_HOLIDAYS | wxWANTS_CHARS, - const wxString& name = wxPyCalendarNameStr); + DocDeclStr( + bool , Create(wxWindow *parent, + wxWindowID id, + const wxDateTime& date = wxDefaultDateTime, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCAL_SHOW_HOLIDAYS | wxWANTS_CHARS, + const wxString& name = wxPyCalendarNameStr), + "Acutally create the GUI portion of the CalendarCtrl for 2-phase +creation."); + DocDeclStr( @@ -261,74 +278,80 @@ public: DocDeclStr( void, EnableYearChange(bool enable = True), - "This function should be used instead of changing CAL_NO_YEAR_CHANGE\n" - "style bit directly. It allows or disallows the user to change the year\n" - "interactively."); + "This function should be used instead of changing CAL_NO_YEAR_CHANGE +style bit directly. It allows or disallows the user to change the year +interactively."); DocDeclStr( void, EnableMonthChange(bool enable = True), - "This function should be used instead of changing CAL_NO_MONTH_CHANGE style\n" - "bit. It allows or disallows the user to change the month interactively. Note\n" - "that if the month can not be changed, the year can not be changed either."); + "This function should be used instead of changing CAL_NO_MONTH_CHANGE +style bit. It allows or disallows the user to change the month +interactively. Note that if the month can not be changed, the year can +not be changed either."); DocDeclStr( void, EnableHolidayDisplay(bool display = True), - "This function should be used instead of changing CAL_SHOW_HOLIDAYS style\n" - "bit directly. It enables or disables the special highlighting of the holidays."); + "This function should be used instead of changing CAL_SHOW_HOLIDAYS +style bit directly. It enables or disables the special highlighting of +the holidays."); DocDeclStr( void, SetHeaderColours(const wxColour& colFg, const wxColour& colBg), - "header colours are used for painting the weekdays at the top"); + "Header colours are used for painting the weekdays at the top."); DocDeclStr( wxColour, GetHeaderColourFg() const, - "header colours are used for painting the weekdays at the top"); + "Header colours are used for painting the weekdays at the top."); DocDeclStr( wxColour, GetHeaderColourBg() const, - "header colours are used for painting the weekdays at the top"); + "Header colours are used for painting the weekdays at the top."); DocDeclStr( void, SetHighlightColours(const wxColour& colFg, const wxColour& colBg), - "highlight colour is used for the currently selected date"); + "Highlight colour is used for the currently selected date."); DocDeclStr( wxColour, GetHighlightColourFg() const, - "highlight colour is used for the currently selected date"); + "Highlight colour is used for the currently selected date."); DocDeclStr( wxColour, GetHighlightColourBg() const, - "highlight colour is used for the currently selected date"); + "Highlight colour is used for the currently selected date."); DocDeclStr( void, SetHolidayColours(const wxColour& colFg, const wxColour& colBg), - "holiday colour is used for the holidays (if CAL_SHOW_HOLIDAYS style is used)"); + "Holiday colour is used for the holidays (if CAL_SHOW_HOLIDAYS style is +used)."); DocDeclStr( wxColour, GetHolidayColourFg() const, - "holiday colour is used for the holidays (if CAL_SHOW_HOLIDAYS style is used)"); + "Holiday colour is used for the holidays (if CAL_SHOW_HOLIDAYS style is +used)."); DocDeclStr( wxColour, GetHolidayColourBg() const, - "holiday colour is used for the holidays (if CAL_SHOW_HOLIDAYS style is used)"); + "Holiday colour is used for the holidays (if CAL_SHOW_HOLIDAYS style is +used)."); DocDeclStr( wxCalendarDateAttr*, GetAttr(size_t day) const, - "Returns the attribute for the given date (should be in the range 1...31).\n" - "The returned value may be None"); + "Returns the attribute for the given date (should be in the range +1...31). The returned value may be None"); DocDeclStr( void, SetAttr(size_t day, wxCalendarDateAttr *attr), - "Associates the attribute with the specified date (in the range 1...31).\n" - "If the attribute passed is None, the items attribute is cleared."); + "Associates the attribute with the specified date (in the range +1...31). If the attribute passed is None, the items attribute is +cleared."); DocDeclStr( void, SetHoliday(size_t day), @@ -336,19 +359,23 @@ public: DocDeclStr( void, ResetAttr(size_t day), - "Clears any attributes associated with the given day (in the range 1...31)."); + "Clears any attributes associated with the given day (in the range +1...31)."); DocAStr(HitTest, "HitTest(Point pos) -> (result, date, weekday)", -"Returns 3-tuple with information about the given position on the calendar -control. The first value of the tuple is a result code and determines the -validity of the remaining two values. The result codes are: - - CAL_HITTEST_NOWHERE: hit outside of anything - CAL_HITTEST_HEADER: hit on the header, weekday is valid - CAL_HITTEST_DAY: hit on a day in the calendar, date is set. +"Returns 3-tuple with information about the given position on the +calendar control. The first value of the tuple is a result code and +determines the validity of the remaining two values. The result codes +are: + + =================== ============================================ + CAL_HITTEST_NOWHERE hit outside of anything + CAL_HITTEST_HEADER hit on the header, weekday is valid + CAL_HITTEST_DAY hit on a day in the calendar, date is set. + =================== ============================================ "); %extend { PyObject* HitTest(const wxPoint& pos) { @@ -367,11 +394,11 @@ validity of the remaining two values. The result codes are: DocDeclStr( wxControl*, GetMonthControl() const, - "get the currently shown control for month"); + "Get the currently shown control for month."); DocDeclStr( wxControl*, GetYearControl() const, - "get the currently shown control for year"); + "Get the currently shown control for year."); }; diff --git a/wxPython/src/core.i b/wxPython/src/core.i index 5dd883fdc1..b10d9d60df 100644 --- a/wxPython/src/core.i +++ b/wxPython/src/core.i @@ -39,11 +39,32 @@ _core_._wxPySetDictionary(vars()) %#// be used here. import sys as _sys wx = _sys.modules[__name__] -} +} #endif +%pythoncode { +%#---------------------------------------------------------------------------- + +def _deprecated(callable, msg=None): + """ + Create a wrapper function that will raise a DeprecationWarning + before calling the callable. + """ + if msg is None: + msg = "%s is deprecated" % callable + def deprecatedWrapper(*args, **kwargs): + import warnings + warnings.warn(msg, DeprecationWarning, stacklevel=2) + return callable(*args, **kwargs) + deprecatedWrapper.__doc__ = msg + return deprecatedWrapper + + +%#---------------------------------------------------------------------------- +} + //--------------------------------------------------------------------------- // Include all the files that make up the core module diff --git a/wxPython/wx/lib/rightalign.py b/wxPython/wx/lib/rightalign.py index 69723c37a6..b0969b9a0e 100644 --- a/wxPython/wx/lib/rightalign.py +++ b/wxPython/wx/lib/rightalign.py @@ -37,7 +37,7 @@ left-aligned if it has focus. Hope this can help someone, as much as this list helps me. Josu Oyanguren -Ubera Servicios Informáticos. +Ubera Servicios Informaticos. P.S. This only works well on wxMSW.