From: Robin Dunn Date: Wed, 25 Feb 2004 00:42:30 +0000 (+0000) Subject: Added docstrings X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/4c42683a5c011a664405b63abf8a3d76bd257aa2 Added docstrings git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@25939 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/wxPython/src/_cshelp.i b/wxPython/src/_cshelp.i index 21fbcbfda9..445db16569 100644 --- a/wxPython/src/_cshelp.i +++ b/wxPython/src/_cshelp.i @@ -37,74 +37,223 @@ EVT_DETAILED_HELP_RANGE = wx.PyEventBinder( wxEVT_DETAILED_HELP, 2) //---------------------------------------------------------------------- -// A help event is sent when the user clicks on a window in context-help mode. +DocStr(wxHelpEvent, +"A help event is sent when the user has requested +context-sensitive help. This can either be caused by the +application requesting context-sensitive help mode via +wx.ContextHelp, or (on MS Windows) by the system generating a +WM_HELP message when the user pressed F1 or clicked on the query +button in a dialog caption. + +A help event is sent to the window that the user clicked on, and +is propagated up the window hierarchy until the event is +processed or there are no more event handlers. The application +should call event.GetId to check the identity of the clicked-on +window, and then either show some suitable help or call +event.Skip if the identifier is unrecognised. Calling Skip is +important because it allows wxWindows to generate further events +for ancestors of the clicked-on window. Otherwise it would be +impossible to show help for container windows, since processing +would stop after the first window found. + + Events + EVT_HELP Sent when the user has requested context- + sensitive help. + EVT_HELP_RANGE Allows to catch EVT_HELP for a range of IDs +"); + class wxHelpEvent : public wxCommandEvent { public: - wxHelpEvent(wxEventType type = wxEVT_NULL, - wxWindowID winid = 0, - const wxPoint& pt = wxDefaultPosition); + DocCtorStr( + wxHelpEvent(wxEventType type = wxEVT_NULL, + wxWindowID winid = 0, + const wxPoint& pt = wxDefaultPosition), + ""); + + + DocDeclStr( + const wxPoint , GetPosition() const, + "Returns the left-click position of the mouse, in screen\n" + "coordinates. This allows the application to position the help\n" + "appropriately."); + + DocDeclStr( + void , SetPosition(const wxPoint& pos), + "Sets the left-click position of the mouse, in screen coordinates."); + + + DocDeclStr( + const wxString& , GetLink() const, + "Get an optional link to further help"); + + DocDeclStr( + void , SetLink(const wxString& link), + "Set an optional link to further help"); + + + DocDeclStr( + const wxString& , GetTarget() const, + "Get an optional target to display help in. E.g. a window specification"); + + DocDeclStr( + void , SetTarget(const wxString& target), + "Set an optional target to display help in. E.g. a window specification"); + +}; - // Position of event (in screen coordinates) - const wxPoint& GetPosition() const; - void SetPosition(const wxPoint& pos); +//--------------------------------------------------------------------------- - // Optional link to further help - const wxString& GetLink() const; - void SetLink(const wxString& link); - // Optional target to display help in. E.g. a window specification - const wxString& GetTarget() const; - void SetTarget(const wxString& target); -}; +DocStr(wxContextHelp, +"This class changes the cursor to a query and puts the application +into a 'context-sensitive help mode'. When the user left-clicks +on a window within the specified window, a EVT_HELP event is sent +to that control, and the application may respond to it by popping +up some help. -//--------------------------------------------------------------------------- +There are a couple of ways to invoke this behaviour implicitly: + + * Use the wx.DIALOG_EX_CONTEXTHELP extended style for a + dialog (Windows only). This will put a question mark in the + titlebar, and Windows will put the application into + context-sensitive help mode automatically, with further + programming. + + * Create a wx.ContextHelpButton, whose predefined behaviour + is to create a context help object. Normally you will write + your application so that this button is only added to a + dialog for non-Windows platforms (use + wx.DIALOG_EX_CONTEXTHELP on Windows). +"); class wxContextHelp : public wxObject { public: - wxContextHelp(wxWindow* window = NULL, bool doNow = True); + DocCtorStr( + wxContextHelp(wxWindow* window = NULL, bool doNow = True), + "Constructs a context help object, calling BeginContextHelp if\n" + "doNow is true (the default).\n" + "\n" + "If window is None, the top window is used."); + ~wxContextHelp(); - bool BeginContextHelp(wxWindow* window = NULL); - bool EndContextHelp(); + DocDeclStr( + bool , BeginContextHelp(wxWindow* window = NULL), + "Puts the application into context-sensitive help mode. window is\n" + "the window which will be used to catch events; if NULL, the top\n" + "window will be used.\n" + "\n" + "Returns true if the application was successfully put into\n" + "context-sensitive help mode. This function only returns when the\n" + "event loop has finished."); + + DocDeclStr( + bool , EndContextHelp(), + "Ends context-sensitive help mode. Not normally called by the\n" + "application."); + }; //---------------------------------------------------------------------- +DocStr(wxContextHelpButton, +"Instances of this class may be used to add a question mark button +that when pressed, puts the application into context-help +mode. It does this by creating a wx.ContextHelp object which +itself generates a EVT_HELP event when the user clicks on a +window. + +On Windows, you may add a question-mark icon to a dialog by use +of the wx.DIALOG_EX_CONTEXTHELP extra style, but on other +platforms you will have to add a button explicitly, usually next +to OK, Cancel or similar buttons. +"); + class wxContextHelpButton : public wxBitmapButton { public: %pythonAppend wxContextHelpButton "self._setOORInfo(self)" - wxContextHelpButton(wxWindow* parent, wxWindowID id = wxID_CONTEXT_HELP, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxBU_AUTODRAW); + DocCtorStr( + wxContextHelpButton(wxWindow* parent, wxWindowID id = wxID_CONTEXT_HELP, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBU_AUTODRAW), + "Constructor, creating and showing a context help button."); }; //---------------------------------------------------------------------- +DocStr(wxHelpProvider, +"wx.HelpProvider is an abstract class used by a program +implementing context-sensitive help to show the help text for the +given window. + +The current help provider must be explicitly set by the +application using wx.HelpProvider.Set()."); + class wxHelpProvider { public: - static wxHelpProvider *Set(wxHelpProvider *helpProvider); - static wxHelpProvider *Get(); - - // Virtuals... - wxString GetHelp(const wxWindow *window); - bool ShowHelp(wxWindow *window); - void AddHelp(wxWindow *window, const wxString& text); - %name(AddHelpById)void AddHelp(wxWindowID id, const wxString& text); - + DocDeclStr( + static wxHelpProvider *, Set(wxHelpProvider *helpProvider), + "Sset the current, application-wide help provider. Returns the\n" + "previous one. Unlike some other classes, the help provider is\n" + "not created on demand. This must be explicitly done by the\n" + "application."); + + DocDeclStr( + static wxHelpProvider *, Get(), + "Return the current application-wide help provider."); + + + DocDeclStr( + wxString , GetHelp(const wxWindow *window), + "Gets the help string for this window. Its interpretation is\n" + "dependent on the help provider except that empty string always\n" + "means that no help is associated with the window."); + + DocDeclStr( + bool , ShowHelp(wxWindow *window), + "Shows help for the given window. Uses GetHelp internally if\n" + "applicable.\n" + "\n" + "Returns true if it was done, or false if no help was available\n" + "for this window."); + + DocDeclStr( + void , AddHelp(wxWindow *window, const wxString& text), + "Associates the text with the given window."); + + DocDeclStrName( + void , AddHelp(wxWindowID id, const wxString& text), + "This version associates the given text with all windows with this\n" + "id. May be used to set the same help string for all Cancel\n" + "buttons in the application, for example.", + AddHelpById); + + DocDeclStr( + void , RemoveHelp(wxWindow* window), + "Removes the association between the window pointer and the help\n" + "text. This is called by the wx.Window destructor. Without this,\n" + "the table of help strings will fill up and when window pointers\n" + "are reused, the wrong help string will be found."); + + %extend { void Destroy() { delete self; } } - }; //---------------------------------------------------------------------- +DocStr(wxSimpleHelpProvider, +"wx.SimpleHelpProvider is an implementation of wx.HelpProvider +which supports only plain text help strings, and shows the string +associated with the control (if any) in a tooltip."); + class wxSimpleHelpProvider : public wxHelpProvider { public: diff --git a/wxPython/src/_cursor.i b/wxPython/src/_cursor.i index dac7260966..e401bb2e54 100644 --- a/wxPython/src/_cursor.i +++ b/wxPython/src/_cursor.i @@ -15,58 +15,167 @@ //--------------------------------------------------------------------------- + +DocStr(wxCursor, +"A cursor is a small bitmap usually used for denoting where the +mouse pointer is, with a picture that might indicate the +interpretation of a mouse click. + +A single cursor object may be used in many windows (any subwindow +type). The wxWindows convention is to set the cursor for a +window, as in X, rather than to set it globally as in MS Windows, +although a global wx.SetCursor function is also available for use +on MS Windows."); + + +RefDoc(wxCursor::wxCursor(int id), +" + Stock Cursor IDs + + wx.CURSOR_ARROW A standard arrow cursor. + wx.CURSOR_RIGHT_ARROW A standard arrow cursor pointing to the right. + wx.CURSOR_BLANK Transparent cursor. + wx.CURSOR_BULLSEYE Bullseye cursor. + wx.CURSOR_CHAR Rectangular character cursor. + wx.CURSOR_CROSS A cross cursor. + wx.CURSOR_HAND A hand cursor. + wx.CURSOR_IBEAM An I-beam cursor (vertical line). + wx.CURSOR_LEFT_BUTTON Represents a mouse with the left button depressed. + wx.CURSOR_MAGNIFIER A magnifier icon. + wx.CURSOR_MIDDLE_BUTTON Represents a mouse with the middle button depressed. + wx.CURSOR_NO_ENTRY A no-entry sign cursor. + wx.CURSOR_PAINT_BRUSH A paintbrush cursor. + wx.CURSOR_PENCIL A pencil cursor. + wx.CURSOR_POINT_LEFT A cursor that points left. + wx.CURSOR_POINT_RIGHT A cursor that points right. + wx.CURSOR_QUESTION_ARROW An arrow and question mark. + wx.CURSOR_RIGHT_BUTTON Represents a mouse with the right button depressed. + wx.CURSOR_SIZENESW A sizing cursor pointing NE-SW. + wx.CURSOR_SIZENS A sizing cursor pointing N-S. + wx.CURSOR_SIZENWSE A sizing cursor pointing NW-SE. + wx.CURSOR_SIZEWE A sizing cursor pointing W-E. + wx.CURSOR_SIZING A general sizing cursor. + wx.CURSOR_SPRAYCAN A spraycan cursor. + wx.CURSOR_WAIT A wait cursor. + wx.CURSOR_WATCH A watch cursor. + wx.CURSOR_ARROWWAIT A cursor with both an arrow and an hourglass, (windows.) + +"); + class wxCursor : public wxGDIObject { public: + %extend { - wxCursor(const wxString* cursorName, long flags, int hotSpotX=0, int hotSpotY=0) { -#ifdef __WXGTK__ + DocStr(wxCursor, + "Construct a Cursor from a file. Specify the type of file using\n" + "wx.BITAMP_TYPE* constants, and specify the hotspot if not using a\n" + ".cur file.\n" + "\n" + "This cursor is not available on wxGTK, use wx.StockCursor,\n" + "wx.CursorFromImage, or wx.CursorFromBits instead."); + wxCursor(const wxString* cursorName, long type, int hotSpotX=0, int hotSpotY=0) { +%#ifdef __WXGTK__ wxCHECK_MSG(False, NULL, - wxT("wxCursor constructor not implemented for wxGTK, use wxStockCursor, wxCursorFromImage, or wxCursorFromBits instead.")); -#else + wxT("wx.Cursor constructor not implemented for wxGTK, use wx.StockCursor, wx.CursorFromImage, or wx.CursorFromBits instead.")); +%#else return new wxCursor(*cursorName, flags, hotSpotX, hotSpotY); -#endif +%#endif } } ~wxCursor(); - // alternate constructors - %name(StockCursor) wxCursor(int id); - %name(CursorFromImage) wxCursor(const wxImage& image); - %extend { - %name(CursorFromBits) wxCursor(PyObject* bits, int width, int height, - int hotSpotX=-1, int hotSpotY=-1, - PyObject* maskBits=0) { - char* bitsbuf; - char* maskbuf = NULL; - int length; - PyString_AsStringAndSize(bits, &bitsbuf, &length); - if (maskBits) - PyString_AsStringAndSize(maskBits, &maskbuf, &length); - return new wxCursor(bitsbuf, width, height, hotSpotX, hotSpotY, maskbuf); - } - } + DocCtorStrName( + wxCursor(int id), + "Create a cursor using one of the stock cursors. Note that not\n" + "all cursors are available on all platforms.", + StockCursor); + + + DocCtorStrName( + wxCursor(const wxImage& image), + "Constructs a cursor from a wxImage. The cursor is monochrome,\n" + "colors with the RGB elements all greater than 127 will be\n" + "foreground, colors less than this background. The mask (if any)\n" + "will be used as transparent.\n" + "\n" + "In MSW the foreground will be white and the background black. The\n" + "cursor is resized to 32x32 In GTK, the two most frequent colors\n" + "will be used for foreground and background. The cursor will be\n" + "displayed at the size of the image. On MacOS the cursor is\n" + "resized to 16x16 and currently only shown as black/white (mask\n" + "respected).", + CursorFromImage); + + +// %extend { +// DocStr(wxCursor, +// ""); +// %name(CursorFromBits) wxCursor(PyObject* bits, int width, int height, +// int hotSpotX=-1, int hotSpotY=-1, +// PyObject* maskBits=NULL) { +// char* bitsbuf; +// char* maskbuf = NULL; +// int length; +// PyString_AsStringAndSize(bits, &bitsbuf, &length); +// if (maskBits) +// PyString_AsStringAndSize(maskBits, &maskbuf, &length); +// return new wxCursor(bitsbuf, width, height, hotSpotX, hotSpotY, maskbuf); +// } +// } + + - // wxGDIImage methods #ifdef __WXMSW__ - long GetHandle(); - void SetHandle(long handle); + DocDeclStr( + long , GetHandle(), + "Get the MS Windows handle for the cursor"); + + DocDeclStr( + void , SetHandle(long handle), + "Set the MS WIndows handle for the cursor"); + #endif - bool Ok(); + DocDeclStr( + bool , Ok(), + ""); + + %pythoncode { def __nonzero__(self): return self.Ok() } + #ifdef __WXMSW__ - int GetWidth(); - int GetHeight(); - int GetDepth(); - void SetWidth(int w); - void SetHeight(int h); - void SetDepth(int d); - void SetSize(const wxSize& size); + DocDeclStr( + int , GetWidth(), + ""); + + DocDeclStr( + int , GetHeight(), + ""); + + DocDeclStr( + int , GetDepth(), + ""); + + DocDeclStr( + void , SetWidth(int w), + ""); + + DocDeclStr( + void , SetHeight(int h), + ""); + + DocDeclStr( + void , SetDepth(int d), + ""); + + DocDeclStr( + void , SetSize(const wxSize& size), + ""); + #endif - %pythoncode { def __nonzero__(self): return self.Ok() } };