X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8668c242808de89b9a8debf2b5a8e62d46e10972..a1ae1090eebbc49d8495c3d3464457277af846db:/wxPython/src/_window.i diff --git a/wxPython/src/_window.i b/wxPython/src/_window.i index 3ffc44537d..68fb3083be 100644 --- a/wxPython/src/_window.i +++ b/wxPython/src/_window.i @@ -23,114 +23,422 @@ MAKE_CONST_WXSTRING(PanelNameStr); //--------------------------------------------------------------------------- %newgroup + +DocStr(wxVisualAttributes, + "struct containing all the visual attributes of a control", ""); + +struct wxVisualAttributes +{ + %extend { + wxVisualAttributes() { return new wxVisualAttributes; } + ~wxVisualAttributes() { delete self; } + } + + // the font used for control label/text inside it + wxFont font; + + // the foreground colour + wxColour colFg; + + // the background colour, may be wxNullColour if the controls background + // colour is not solid + wxColour colBg; +}; + + + + +enum wxWindowVariant +{ + wxWINDOW_VARIANT_NORMAL, // Normal size + wxWINDOW_VARIANT_SMALL, // Smaller size (about 25 % smaller than normal ) + wxWINDOW_VARIANT_MINI, // Mini size (about 33 % smaller than normal ) + wxWINDOW_VARIANT_LARGE, // Large size (about 25 % larger than normal ) + wxWINDOW_VARIANT_MAX +}; + + +DocStr(wxWindow, +"wx.Window is the base class for all windows and represents any visible +object on the screen. All controls, top level windows and so on are +wx.Windows. Sizers and device contexts are not however, as they don't +appear on screen themselves. +", +" +Styles +------- + ============================= ===================================== + wx.SIMPLE_BORDER Displays a thin border around the window. + + wx.DOUBLE_BORDER Displays a double border. Windows and Mac only. + + wx.SUNKEN_BORDER Displays a sunken border. + + wx.RAISED_BORDER Displays a raised border. + + wx.STATIC_BORDER Displays a border suitable for a static + control. Windows only. + + wx.NO_BORDER Displays no border, overriding the default + border style for the window. + + wx.TRANSPARENT_WINDOW The window is transparent, that is, it + will not receive paint events. Windows only. + + wx.TAB_TRAVERSAL Use this to enable tab traversal for + non-dialog windows. + + wx.WANTS_CHARS Use this to indicate that the window + wants to get all char/key events for + all keys - even for keys like TAB or + ENTER which are usually used for + dialog navigation and which wouldn't + be generated without this style. If + you need to use this style in order to + get the arrows or etc., but would + still like to have normal keyboard + navigation take place, you should + create and send a wxNavigationKeyEvent + in response to the key events for Tab + and Shift-Tab. + + wx.NO_FULL_REPAINT_ON_RESIZE Disables repainting the window + completely when its size is changed. + You will have to repaint the new + window area manually if you use this + style. As of version 2.5.1 this + style is on by default. Use + wx.FULL_REPAINT_ON_RESIZE to + deactivate it. + + wx.VSCROLL Use this style to enable a vertical scrollbar. + + wx.HSCROLL Use this style to enable a horizontal scrollbar. + + wx.ALWAYS_SHOW_SB If a window has scrollbars, disable them + instead of hiding them when they are + not needed (i.e. when the size of the + window is big enough to not require + the scrollbars to navigate it). This + style is currently only implemented + for wxMSW and wxUniversal and does + nothing on the other platforms. + + wx.CLIP_CHILDREN Use this style to eliminate flicker caused by + the background being repainted, then + children being painted over + them. Windows only. + + wx.FULL_REPAINT_ON_RESIZE Use this style to force a complete + redraw of the window whenever it is + resized instead of redrawing just the + part of the window affected by + resizing. Note that this was the + behaviour by default before 2.5.1 + release and that if you experience + redraw problems with the code which + previously used to work you may want + to try this. + ============================= ===================================== + + +Extra Styles +------------ + ============================= ===================================== + wx.WS_EX_VALIDATE_RECURSIVELY By default, + Validate/TransferDataTo/FromWindow() + only work on direct children of + the window (compatible + behaviour). Set this flag to make + them recursively descend into all + subwindows. + + wx.WS_EX_BLOCK_EVENTS wx.CommandEvents and the objects of the + derived classes are forwarded to + the parent window and so on + recursively by default. Using this + flag for the given window allows + to block this propagation at this + window, i.e. prevent the events + from being propagated further + upwards. Dialogs have this flag on + by default. + + wx.WS_EX_TRANSIENT Don't use this window as an implicit parent for + the other windows: this must be + used with transient windows as + otherwise there is the risk of + creating a dialog/frame with this + window as a parent which would + lead to a crash if the parent is + destroyed before the child. + + wx.WS_EX_PROCESS_IDLE This window should always process idle + events, even if the mode set by + wx.IdleEvent.SetMode is + wx.IDLE_PROCESS_SPECIFIED. + + wx.WS_EX_PROCESS_UI_UPDATES This window should always process UI + update events, even if the mode + set by wxUpdateUIEvent::SetMode is + wxUPDATE_UI_PROCESS_SPECIFIED. + ============================= ===================================== + +"); + + + class wxWindow : public wxEvtHandler { public: - %addtofunc wxWindow "self._setOORInfo(self)" - %addtofunc wxWindow() "" - - wxWindow(wxWindow* parent, const wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = wxPyPanelNameStr); - %name(PreWindow)wxWindow(); + %pythonAppend wxWindow "self._setOORInfo(self)" + %pythonAppend wxWindow() "" + + DocCtorStr( + wxWindow(wxWindow* parent, const wxWindowID id=-1, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxPyPanelNameStr), + "Construct and show a generic Window.", ""); + + DocCtorStrName( + wxWindow(), + "Precreate a Window for 2-phase creation.", "", + PreWindow); + - bool Create(wxWindow* parent, const wxWindowID id, + DocDeclStr( + bool , Create(wxWindow* parent, const wxWindowID id=-1, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = 0, - const wxString& name = wxPyPanelNameStr); - - + const wxString& name = wxPyPanelNameStr), + "Create the GUI part of the Window for 2-phase creation mode.", ""); + // deleting the window // ------------------- - // ask the window to close itself, return True if the event handler - // honoured our request - bool Close( bool force = False ); - // delete window unconditionally (dangerous!), returns True if ok - virtual bool Destroy(); + DocDeclStr( + bool , Close( bool force = False ), + "This function simply generates a EVT_CLOSE event whose handler usually +tries to close the window. It doesn't close the window itself, +however. If force is False (the default) then the window's close +handler will be allowed to veto the destruction of the window.", +" +Usually Close is only used with the top level windows (wx.Frame and +wx.Dialog classes) as the others are not supposed to have any special +EVT_CLOSE logic. + +The close handler should check whether the window is being deleted +forcibly, using wx.CloseEvent.GetForce, in which case it should +destroy the window using wx.Window.Destroy. + +Note that calling Close does not guarantee that the window will be +destroyed; but it provides a way to simulate a manual close of a +window, which may or may not be implemented by destroying the +window. The default EVT_CLOSE handler for wx.Dialog does not +necessarily delete the dialog, since it will simply simulate an +wxID_CANCEL event which is handled by the appropriate button event +handler and may do anything at all. + +To guarantee that the window will be destroyed, call wx.Window.Destroy +instead."); + - // delete all children of this window, returns True if ok - bool DestroyChildren(); - // is the window being deleted? - bool IsBeingDeleted() const; + DocDeclStr( + virtual bool , Destroy(), + "Destroys the window safely. Frames and dialogs are not destroyed +immediately when this function is called -- they are added to a list +of windows to be deleted on idle time, when all the window's events +have been processed. This prevents problems with events being sent to +non-existent windows. +Returns True if the window has either been successfully deleted, or it +has been added to the list of windows pending real deletion.", ""); + + DocDeclStr( + bool , DestroyChildren(), + "Destroys all children of a window. Called automatically by the +destructor.", ""); + + + DocDeclStr( + bool , IsBeingDeleted() const, + "Is the window in the process of being deleted?", ""); + + + // window attributes // ----------------- - // the text which the window shows in the title if applicable - virtual void SetTitle( const wxString& WXUNUSED(title) ); - virtual wxString GetTitle() const; + DocDeclStr( + virtual void , SetTitle( const wxString& title), + "Sets the window's title. Applicable only to frames and dialogs.", ""); + + DocDeclStr( + virtual wxString , GetTitle() const, + "Gets the window's title. Applicable only to frames and dialogs.", ""); + - // the text which the window shows in its label if applicable - virtual void SetLabel(const wxString& label); - virtual wxString GetLabel() const; + DocDeclStr( + virtual void , SetLabel(const wxString& label), + "Set the text which the window shows in its label if applicable.", ""); + + DocDeclStr( + virtual wxString , GetLabel() const, + "Generic way of getting a label from any window, for identification +purposes. The interpretation of this function differs from class to +class. For frames and dialogs, the value returned is the title. For +buttons or static text controls, it is the button text. This function +can be useful for meta-programs such as testing tools or special-needs +access programs)which need to identify windows by name.", ""); + - // the window name is used for ressource setting in X, it is not the - // same as the window title/label - virtual void SetName( const wxString &name ); - virtual wxString GetName() const; + DocDeclStr( + virtual void , SetName( const wxString &name ), + "Sets the window's name. The window name is used for ressource setting +in X, it is not the same as the window title/label", ""); + + DocDeclStr( + virtual wxString , GetName() const, + "Returns the windows name. This name is not guaranteed to be unique; +it is up to the programmer to supply an appropriate name in the window +constructor or via wx.Window.SetName.", ""); + + + DocDeclStr( + void , SetWindowVariant( wxWindowVariant variant ), + "Sets the variant of the window/font size to use for this window, if +the platform supports variants, for example, wxMac.", + " +Variant values are: + + ======================== ======================================= + wx.WINDOW_VARIANT_NORMAL Normal size + wx.WINDOW_VARIANT_SMALL Smaller size (about 25 % smaller than normal) + wx.WINDOW_VARIANT_MINI Mini size (about 33 % smaller than normal) + wx.WINDOW_VARIANT_LARGE Large size (about 25 % larger than normal) + ======================== ======================================= +"); + + DocDeclStr( + wxWindowVariant , GetWindowVariant() const, + "", ""); + - // window id uniquely identifies the window among its siblings unless - // it is -1 which means "don't care" - void SetId( wxWindowID winid ); - wxWindowID GetId() const; + DocDeclStr( + void , SetId( wxWindowID winid ), + "Sets the identifier of the window. Each window has an integer +identifier. If the application has not provided one, an identifier +will be generated. Normally, the identifier should be provided on +creation and should not be modified subsequently.", ""); + + DocDeclStr( + wxWindowID , GetId() const, + "Returns the identifier of the window. Each window has an integer +identifier. If the application has not provided one (or the default Id +-1 is used) then an unique identifier with a negative value will be +generated.", ""); + - // generate a control id for the controls which were not given one by - // user - static int NewControlId(); + DocDeclStr( + static int , NewControlId(), + "Generate a control id for the controls which were not given one.", ""); + - // get the id of the control following the one with the given - // (autogenerated) id - static int NextControlId(int winid); + DocDeclStr( + static int , NextControlId(int winid), + "Get the id of the control following the one with the given +autogenerated) id", ""); + - // get the id of the control preceding the one with the given - // (autogenerated) id - static int PrevControlId(int winid); + DocDeclStr( + static int , PrevControlId(int winid), + "Get the id of the control preceding the one with the given +autogenerated) id", ""); + // moving/resizing // --------------- - // set the window size - void SetSize( const wxSize& size ); - // set the window size and position - %name(SetDimensions) void SetSize( int x, int y, int width, int height, - int sizeFlags = wxSIZE_AUTO ); + DocDeclStr( + void , SetSize( const wxSize& size ), + "Sets the size of the window in pixels.", ""); + + + DocDeclStrName( + void , SetSize( int x, int y, int width, int height, + int sizeFlags = wxSIZE_AUTO ), + "Sets the position and size of the window in pixels. The sizeFlags +parameter indicates the interpretation of the other params if they are +-1. wx.SIZE_AUTO*: a -1 indicates that a class-specific default +shoudl be used. wx.SIZE_USE_EXISTING: existing dimensions should be +used if -1 values are supplied. wxSIZE_ALLOW_MINUS_ONE: allow +dimensions of -1 and less to be interpreted as real dimensions, not +default values.", "", + SetDimensions); + - // set the window size and position with a wxRect - %name(SetRect) void SetSize(const wxRect& rect, int sizeFlags = wxSIZE_AUTO); + DocDeclStrName( + void , SetSize(const wxRect& rect, int sizeFlags = wxSIZE_AUTO), + "Sets the position and size of the window in pixels using a wx.Rect.", "", + SetRect); + - // set window size - %name(SetSizeWH)void SetSize( int width, int height ); + DocDeclStrName( + void , SetSize( int width, int height ), + "Sets the size of the window in pixels.", "", + SetSizeWH); + - // set window position - void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING); + DocDeclStr( + void , Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING), + "Moves the window to the given position.", ""); + %pythoncode { SetPosition = Move } - // set window position - %name(MoveXY) void Move(int x, int y, int flags = wxSIZE_USE_EXISTING); - // Z-order - virtual void Raise(); - virtual void Lower(); + DocDeclStrName( + void , Move(int x, int y, int flags = wxSIZE_USE_EXISTING), + "Moves the window to the given position.", "", + MoveXY); + + + + DocDeclStr( + virtual void , Raise(), + "Raises the window to the top of the window hierarchy if it is a +managed window (dialog or frame).", ""); + + DocDeclStr( + virtual void , Lower(), + "Lowers the window to the bottom of the window hierarchy if it is a +managed window (dialog or frame).", ""); + + // client size is the size of the area available for subwindows + DocStr(SetClientSize, + "This sets the size of the window client area in pixels. Using this +function to size a window tends to be more device-independent than +wx.Window.SetSize, since the application need not worry about what +dimensions the border or title bar have when trying to fit the window +around panel items, for example.", ""); void SetClientSize( const wxSize& size ); %name(SetClientSizeWH) void SetClientSize( int width, int height ); %name(SetClientRect) void SetClientSize(const wxRect& rect); DocStr(GetPosition, // sets the docstring for both - "Get the window's position."); + "Get the window's position.", ""); wxPoint GetPosition(); DocDeclAName( @@ -139,7 +447,7 @@ public: GetPositionTuple); - DocStr(GetSize, "Get the window size."); + DocStr(GetSize, "Get the window size.", ""); wxSize GetSize() const; DocDeclAName( void, GetSize( int *OUTPUT, int *OUTPUT ) const, @@ -147,28 +455,44 @@ public: GetSizeTuple); - // get the window position and size - wxRect GetRect() const; - DocStr(GetClientSize, "Get the window's client size."); + DocDeclStr( + wxRect , GetRect() const, + "Returns the size and position of the window as a wx.Rect object.", ""); + + + DocStr(GetClientSize, + "This gets the size of the window's 'client area' in pixels. The client +area is the area which may be drawn on by the programmer, excluding +title bar, border, scrollbars, etc.", ""); wxSize GetClientSize() const; DocDeclAName( void, GetClientSize( int *OUTPUT, int *OUTPUT ) const, "GetClientSizeTuple() -> (width, height)", GetClientSizeTuple); + - // get the origin of the client area of the window relative to the - // window top left corner (the client area may be shifted because of - // the borders, scrollbars, other decorations...) - virtual wxPoint GetClientAreaOrigin() const; + DocDeclStr( + virtual wxPoint , GetClientAreaOrigin() const, + "Get the origin of the client area of the window relative to the +window's top left corner (the client area may be shifted because of +the borders, scrollbars, other decorations...)", ""); + - // get the client rectangle in window (i.e. client) coordinates - wxRect GetClientRect() const; + DocDeclStr( + wxRect , GetClientRect() const, + "Get the client area position and size as a wx.Rect object.", ""); + + DocStr(GetBestSize, - "Get the size best suited for the window (in fact, minimal acceptable size\n" - "using which it will still look \"nice\")"); + "This functions returns the best acceptable minimal size for the +window, if applicable. For example, for a static text control, it will +be the minimal size such that the control label is not truncated. For +windows containing subwindows (suzh aswx.Panel), the size returned by +this function will be the same as the size the window would have had +after calling Fit.", ""); wxSize GetBestSize() const; DocDeclAName( void, GetBestSize(int *OUTPUT, int *OUTPUT) const, @@ -176,65 +500,129 @@ public: GetBestSizeTuple); - // There are times (and windows) where 'Best' size and 'Min' size - // are vastly out of sync. This should be remedied somehow, but in - // the meantime, this method will return the larger of BestSize - // (the window's smallest legible size), and any user specified - // MinSize hint. - wxSize GetAdjustedBestSize() const; + DocDeclStr( + wxSize , GetAdjustedBestSize() const, + "This method is similar to GetBestSize, except in one +thing. GetBestSize should return the minimum untruncated size of the +window, while this method will return the largest of BestSize and any +user specified minimum size. ie. it is the minimum size the window +should currently be drawn at, not the minimal size it can possibly +tolerate.", ""); + + - // the generic center function - centers the window on parent by - // default or on screen if it doesn't have parent or - // wxCENTER_ON_SCREEN flag is given - void Center( int direction = wxBOTH ); + DocDeclStr( + void , Center( int direction = wxBOTH ), + "Centers the window. The parameter specifies the direction for +cetering, and may be wx.HORIZONTAL, wx.VERTICAL or wx.BOTH. It may +also include wx.CENTER_ON_SCREEN flag if you want to center the window +on the entire screen and not on its parent window. If it is a +top-level window and has no parent then it will always be centered +relative to the screen.", ""); + %pythoncode { Centre = Center } - // center on screen (only works for top level windows) - void CenterOnScreen(int dir = wxBOTH); + + DocDeclStr( + void , CenterOnScreen(int dir = wxBOTH), + "Center on screen (only works for top level windows)", ""); %pythoncode { CentreOnScreen = CenterOnScreen } - // center with respect to the the parent window - void CenterOnParent(int dir = wxBOTH); + + DocDeclStr( + void , CenterOnParent(int dir = wxBOTH), + "Center with respect to the the parent window", ""); %pythoncode { CentreOnParent = CenterOnParent } + - // set window size to wrap around its children - virtual void Fit(); + DocDeclStr( + virtual void , Fit(), + "Sizes the window so that it fits around its subwindows. This function +won't do anything if there are no subwindows and will only really work +correctly if sizers are used for the subwindows layout. Also, if the +window has exactly one subwindow it is better (faster and the result +is more precise as Fit adds some margin to account for fuzziness of +its calculations) to call window.SetClientSize(child.GetSize()) +instead of calling Fit.", ""); + - // set virtual size to satisfy children - virtual void FitInside(); + DocDeclStr( + virtual void , FitInside(), + "Similar to Fit, but sizes the interior (virtual) size of a +window. Mainly useful with scrolled windows to reset scrollbars after +sizing changes that do not trigger a size event, and/or scrolled +windows without an interior sizer. This function similarly won't do +anything if there are no subwindows.", ""); + - // set min/max size of the window + + %nokwargs SetSizeHints; + DocStr(SetSizeHints, + "Allows specification of minimum and maximum window sizes, and window +size increments. If a pair of values is not set (or set to -1), the +default values will be used. If this function is called, the user +will not be able to size the window outside the given bounds. The +resizing increments are only significant under Motif or Xt.", ""); virtual void SetSizeHints( int minW, int minH, int maxW = -1, int maxH = -1, int incW = -1, int incH = -1 ); + void SetSizeHints( const wxSize& minSize, + const wxSize& maxSize=wxDefaultSize, + const wxSize& incSize=wxDefaultSize); + + %nokwargs SetVirtualSizeHints; + DocStr(SetVirtualSizeHints, + "Allows specification of minimum and maximum virtual window sizes. If a +pair of values is not set (or set to -1), the default values will be +used. If this function is called, the user will not be able to size +the virtual area of the window outside the given bounds.", ""); virtual void SetVirtualSizeHints( int minW, int minH, int maxW = -1, int maxH = -1 ); + void SetVirtualSizeHints( const wxSize& minSize, + const wxSize& maxSize=wxDefaultSize); + + DocDeclStr( + virtual int , GetMinWidth() const, + "", ""); + + DocDeclStr( + virtual int , GetMinHeight() const, + "", ""); + + DocDeclStr( + int , GetMaxWidth() const, + "", ""); + + DocDeclStr( + int , GetMaxHeight() const, + "", ""); + - virtual int GetMinWidth() const; - virtual int GetMinHeight() const; - int GetMaxWidth() const; - int GetMaxHeight() const; - - - // Override this method to control the values given to Sizers etc. - virtual wxSize GetMaxSize() const; + DocDeclStr( + virtual wxSize , GetMaxSize() const, + "", ""); + + DocDeclStr( + virtual wxSize , GetMinSize() const, + "", ""); + DocStr(SetVirtualSize, - "Set the the virtual size of a window. For most windows this is just the\n" - "client area of the window, but for some like scrolled windows it is more or\n" - "less independent of the screen window size."); + "Set the the virtual size of a window in pixels. For most windows this +is just the client area of the window, but for some like scrolled +windows it is more or less independent of the screen window size.", ""); void SetVirtualSize(const wxSize& size ); %name(SetVirtualSizeWH) void SetVirtualSize( int w, int h ); DocStr(GetVirtualSize, - "Get the the virtual size of the window. For most windows this is just\n" - "the client area of the window, but for some like scrolled windows it is\n" - "more or less independent of the screen window size."); + "Get the the virtual size of the window in pixels. For most windows +this is just the client area of the window, but for some like scrolled +windows it is more or less independent of the screen window size.", ""); wxSize GetVirtualSize() const; DocDeclAName( void, GetVirtualSize( int *OUTPUT, int *OUTPUT ) const, @@ -250,148 +638,306 @@ public: // virtual wxSize DoGetVirtualSize() const; // { return m_virtualSize; } - // Return the largest of ClientSize and BestSize (as determined - // by a sizer, interior children, or other means) - virtual wxSize GetBestVirtualSize() const; - + DocDeclStr( + virtual wxSize , GetBestVirtualSize() const, + "Return the largest of ClientSize and BestSize (as determined by a +sizer, interior children, or other means)", ""); + // window state // ------------ - // returns True if window was shown/hidden, False if the nothing was - // done (window was already shown/hidden) - virtual bool Show( bool show = True ); - bool Hide(); + DocDeclStr( + virtual bool , Show( bool show = True ), + "Shows or hides the window. You may need to call Raise for a top level +window if you want to bring it to top, although this is not needed if +Show is called immediately after the frame creation. Returns True if +the window has been shown or hidden or False if nothing was done +because it already was in the requested state.", ""); + + DocDeclStr( + bool , Hide(), + "Equivalent to calling Show(False).", ""); + - // returns True if window was enabled/disabled, False if nothing done - virtual bool Enable( bool enable = True ); - bool Disable(); + DocDeclStr( + virtual bool , Enable( bool enable = True ), + "Enable or disable the window for user input. Note that when a parent +window is disabled, all of its children are disabled as well and they +are reenabled again when the parent is. Returns true if the window +has been enabled or disabled, false if nothing was done, i.e. if the +window had already been in the specified state.", ""); + + DocDeclStr( + bool , Disable(), + "Disables the window, same as Enable(false).", ""); + - bool IsShown() const; - bool IsEnabled() const; + DocDeclStr( + bool , IsShown() const, + "Returns true if the window is shown, false if it has been hidden.", ""); + + DocDeclStr( + bool , IsEnabled() const, + "Returns true if the window is enabled for input, false otherwise.", ""); - // get/set window style (setting style won't update the window and so - // is only useful for internal usage) - virtual void SetWindowStyleFlag( long style ); - virtual long GetWindowStyleFlag() const; + - // get/set window style (setting style won't update the window and so - // is only useful for internal usage) - void SetWindowStyle( long style ); - long GetWindowStyle() const; - bool HasFlag(int flag) const; - virtual bool IsRetained() const; + DocDeclStr( + virtual void , SetWindowStyleFlag( long style ), + "Sets the style of the window. Please note that some styles cannot be +changed after the window creation and that Refresh() might need to be +called after changing the others for the change to take place +immediately.", ""); + + DocDeclStr( + virtual long , GetWindowStyleFlag() const, + "Gets the window style that was passed to the constructor or Create +method.", ""); - // extra style: the less often used style bits which can't be set with - // SetWindowStyleFlag() - virtual void SetExtraStyle(long exStyle); - long GetExtraStyle() const; + %pythoncode { SetWindowStyle = SetWindowStyleFlag; GetWindowStyle = GetWindowStyleFlag } + + + DocDeclStr( + bool , HasFlag(int flag) const, + "Test if the given style is set for this window.", ""); + - // make the window modal (all other windows unresponsive) - virtual void MakeModal(bool modal = True); + DocDeclStr( + virtual bool , IsRetained() const, + "Returns true if the window is retained, false otherwise. Retained +windows are only available on X platforms.", ""); + - virtual void SetThemeEnabled(bool enableTheme); - virtual bool GetThemeEnabled() const; - // controls by default inherit the colours of their parents, if a - // particular control class doesn't want to do it, it can override - // ShouldInheritColours() to return False - virtual bool ShouldInheritColours() const; + DocDeclStr( + virtual void , SetExtraStyle(long exStyle), + "Sets the extra style bits for the window. Extra styles are the less +often used style bits which can't be set with the constructor or with +SetWindowStyleFlag()", ""); + + DocDeclStr( + long , GetExtraStyle() const, + "Returns the extra style bits for the window.", ""); + + + DocDeclStr( + virtual void , MakeModal(bool modal = True), + "Disables all other windows in the application so that the user can +only interact with this window. Passing False will reverse this +effect.", ""); + - // focus and keyboard handling - // --------------------------- + + DocDeclStr( + virtual void , SetThemeEnabled(bool enableTheme), + "This function tells a window if it should use the system's \"theme\" + code to draw the windows' background instead if its own background + drawing code. This will only have an effect on platforms that support + the notion of themes in user defined windows. One such platform is + GTK+ where windows can have (very colourful) backgrounds defined by a + user's selected theme. + +Dialogs, notebook pages and the status bar have this flag set to true +by default so that the default look and feel is simulated best.", ""); + + DocDeclStr( + virtual bool , GetThemeEnabled() const, + "Return the themeEnabled flag.", ""); + - // set focus to this window - virtual void SetFocus(); +// TODO with directors +// // controls by default inherit the colours of their parents, if a +// // particular control class doesn't want to do it, it can override +// // ShouldInheritColours() to return False +// virtual bool ShouldInheritColours() const; - // set focus to this window as the result of a keyboard action - virtual void SetFocusFromKbd(); - // return the window which currently has the focus or NULL - static wxWindow *FindFocus(); - // can this window have focus? - virtual bool AcceptsFocus() const; + - // can this window be given focus by keyboard navigation? if not, the - // only way to give it focus (provided it accepts it at all) is to - // click it - virtual bool AcceptsFocusFromKeyboard() const; + // focus and keyboard handling + // --------------------------- - // get the default child of this parent, i.e. the one which is - // activated by pressing - virtual wxWindow *GetDefaultItem() const; + + DocDeclStr( + virtual void , SetFocus(), + "Set's the focus to this window, allowing it to receive keyboard input.", ""); + + DocDeclStr( + virtual void , SetFocusFromKbd(), + "Set focus to this window as the result of a keyboard action. Normally +only called internally.", ""); + - // set this child as default, return the old default - virtual wxWindow *SetDefaultItem(wxWindow * WXUNUSED(child)); + + DocDeclStr( + static wxWindow *, FindFocus(), + "Returns the window or control that currently has the keyboard focus, +or None.", ""); + - // set this child as temporary default - virtual void SetTmpDefaultItem(wxWindow * WXUNUSED(win)); + DocDeclStr( + virtual bool , AcceptsFocus() const, + "Can this window have focus?", ""); + + + DocDeclStr( + virtual bool , AcceptsFocusFromKeyboard() const, + "Can this window be given focus by keyboard navigation? if not, the +only way to give it focus (provided it accepts it at all) is to click +it.", ""); + + + + + DocDeclStr( + virtual wxWindow *, GetDefaultItem() const, + "Get the default child of this parent, i.e. the one which is activated +by pressing such as the OK button on a wx.Dialog.", ""); + + DocDeclStr( + virtual wxWindow *, SetDefaultItem(wxWindow * child), + "Set this child as default, return the old default.", ""); + + DocDeclStr( + virtual void , SetTmpDefaultItem(wxWindow * win), + "Set this child as temporary default", ""); + + // parent/children relations // ------------------------- - // get the list of children + //wxWindowList& GetChildren(); // TODO: Do a typemap or a wrapper for wxWindowList %extend { + DocStr(GetChildren, + "Returns a list of the window's children. NOTE: Currently this is a +copy of the child window list maintained by the window, so the return +value of this function is only valid as long as the window's children +do not change.", ""); PyObject* GetChildren() { wxWindowList& list = self->GetChildren(); return wxPy_ConvertList(&list); } } - // get the parent or the parent of the parent - wxWindow *GetParent() const; - wxWindow *GetGrandParent() const; + DocDeclStr( + wxWindow *, GetParent() const, + "Returns the parent window of this window, or None if there isn't one.", ""); + + DocDeclStr( + wxWindow *, GetGrandParent() const, + "Returns the parent of the parent of this window, or None if there +isn't one.", ""); + - // is this window a top level one? - virtual bool IsTopLevel() const; + + DocDeclStr( + virtual bool , IsTopLevel() const, + "Returns true if the given window is a top-level one. Currently all +frames and dialogs are always considered to be top-level windows (even +if they have a parent window).", ""); + // change the real parent of this window, return True if the parent // was changed, False otherwise (error or newParent == oldParent) - virtual bool Reparent( wxWindow *newParent ); + DocDeclStr( + virtual bool , Reparent( wxWindow *newParent ), + "Reparents the window, i.e the window will be removed from its current +parent window (e.g. a non-standard toolbar in a wxFrame) and then +re-inserted into another. Available on Windows and GTK. Returns True +if the parent was changed, False otherwise (error or newParent == +oldParent)", ""); + - // implementation mostly - virtual void AddChild( wxWindow *child ); - virtual void RemoveChild( wxWindow *child ); + DocDeclStr( + virtual void , AddChild( wxWindow *child ), + "Adds a child window. This is called automatically by window creation +functions so should not be required by the application programmer.", ""); + + DocDeclStr( + virtual void , RemoveChild( wxWindow *child ), + "Removes a child window. This is called automatically by window +deletion functions so should not be required by the application +programmer.", ""); + // looking for windows // ------------------- - // find window among the descendants of this one either by id or by - // name (return NULL if not found) - %name(FindWindowById) wxWindow *FindWindow( long winid ); - %name(FindWindowByName) wxWindow *FindWindow( const wxString& name ); + DocDeclStrName( + wxWindow *, FindWindow( long winid ), + "Find a chld of this window by window ID", "", + FindWindowById); + + DocDeclStrName( + wxWindow *, FindWindow( const wxString& name ), + "Find a child of this window by name", "", + FindWindowByName); + // event handler stuff // ------------------- - // get the current event handler - wxEvtHandler *GetEventHandler() const; + DocDeclStr( + wxEvtHandler *, GetEventHandler() const, + "Returns the event handler for this window. By default, the window is +its own event handler.", ""); + + + DocDeclStr( + void , SetEventHandler( wxEvtHandler *handler ), + "Sets the event handler for this window. An event handler is an object +that is capable of processing the events sent to a window. By default, +the window is its own event handler, but an application may wish to +substitute another, for example to allow central implementation of +event-handling for a variety of different window classes. + +It is usually better to use `wx.Window.PushEventHandler` since this sets +up a chain of event handlers, where an event not handled by one event +handler is handed to the next one in the chain.", ""); + - // replace the event handler (allows to completely subclass the - // window) - void SetEventHandler( wxEvtHandler *handler ); + DocDeclStr( + void , PushEventHandler( wxEvtHandler *handler ), + "Pushes this event handler onto the event handler stack for the window. +An event handler is an object that is capable of processing the events +sent to a window. By default, the window is its own event handler, but +an application may wish to substitute another, for example to allow +central implementation of event-handling for a variety of different +window classes. - // push/pop event handler: allows to chain a custom event handler to - // alreasy existing ones - void PushEventHandler( wxEvtHandler *handler ); - wxEvtHandler *PopEventHandler( bool deleteHandler = False ); +wx.Window.PushEventHandler allows an application to set up a chain of +event handlers, where an event not handled by one event handler is +handed to the next one in the chain. Use `wx.Window.PopEventHandler` to +remove the event handler.", ""); - // find the given handler in the event handler chain and remove (but - // not delete) it from the event handler chain, return True if it was - // found and False otherwise (this also results in an assert failure so - // this function should only be called when the handler is supposed to - // be there) - bool RemoveEventHandler(wxEvtHandler *handler); + + DocDeclStr( + wxEvtHandler *, PopEventHandler( bool deleteHandler = False ), + "Removes and returns the top-most event handler on the event handler +stack. If deleteHandler is True then the wx.EvtHandler object will be +destroyed after it is popped.", ""); + + + DocDeclStr( + bool , RemoveEventHandler(wxEvtHandler *handler), + "Find the given handler in the event handler chain and remove (but not +delete) it from the event handler chain, return True if it was found +and False otherwise (this also results in an assert failure so this +function should only be called when the handler is supposed to be +there.)", ""); + @@ -400,15 +946,60 @@ public: // a window may have an associated validator which is used to control // user input - virtual void SetValidator( const wxValidator &validator ); - virtual wxValidator *GetValidator(); + DocDeclStr( + virtual void , SetValidator( const wxValidator &validator ), + "Deletes the current validator (if any) and sets the window validator, +having called wx.Validator.Clone to create a new validator of this +type.", ""); + + DocDeclStr( + virtual wxValidator *, GetValidator(), + "Returns a pointer to the current validator for the window, or None if +there is none.", ""); + + + DocDeclStr( + virtual bool , Validate(), + "Validates the current values of the child controls using their +validators. If the window has wx.WS_EX_VALIDATE_RECURSIVELY extra +style flag set, the method will also call Validate() of all child +windows. Returns false if any of the validations failed.", ""); + + + DocDeclStr( + virtual bool , TransferDataToWindow(), + "Transfers values to child controls from data areas specified by their +validators. If the window has wx.WS_EX_VALIDATE_RECURSIVELY extra +style flag set, the method will also call TransferDataToWindow() of +all child windows.", ""); + + DocDeclStr( + virtual bool , TransferDataFromWindow(), + "Transfers values from child controls to data areas specified by their +validators. Returns false if a transfer failed. If the window has +wx.WS_EX_VALIDATE_RECURSIVELY extra style flag set, the method will +also call TransferDataFromWindow() of all child windows.", ""); + + + DocDeclStr( + virtual void , InitDialog(), + "Sends an EVT_INIT_DIALOG event, whose handler usually transfers data +to the dialog via validators.", ""); + + // accelerators // ------------ - virtual void SetAcceleratorTable( const wxAcceleratorTable& accel ); - wxAcceleratorTable *GetAcceleratorTable(); + DocDeclStr( + virtual void , SetAcceleratorTable( const wxAcceleratorTable& accel ), + "Sets the accelerator table for this window.", ""); + + DocDeclStr( + wxAcceleratorTable *, GetAcceleratorTable(), + "Gets the accelerator table for this window.", ""); + @@ -416,15 +1007,25 @@ public: // hot keys (system wide accelerators) // ----------------------------------- %extend { - // hot keys (system wide accelerators) + DocStr(RegisterHotKey, + "Registers a system wide hotkey. Every time the user presses the hotkey +registered here, this window will receive a hotkey event. It will +receive the event even if the application is in the background and +does not have the input focus because the user is working with some +other application. To bind an event handler function to this hotkey +use EVT_HOTKEY with an id equal to hotkeyId. Returns True if the +hotkey was registered successfully.", ""); bool RegisterHotKey(int hotkeyId, int modifiers, int keycode) { - #if wxUSE_HOTKEY + %#if wxUSE_HOTKEY return self->RegisterHotKey(hotkeyId, modifiers, keycode); - #else + %#else return False; - #endif + %#endif } + + DocStr(UnregisterHotKey, + "Unregisters a system wide hotkey.", ""); bool UnregisterHotKey(int hotkeyId) { #if wxUSE_HOTKEY return self->UnregisterHotKey(hotkeyId); @@ -439,12 +1040,26 @@ public: // "dialog units" translations // --------------------------- + DocStr(ConvertDialogToPixels, + "Converts a point or size from dialog units to pixels. Dialog units +are used for maintaining a dialog's proportions even if the font +changes. For the x dimension, the dialog units are multiplied by the +average character width and then divided by 4. For the y dimension, +the dialog units are multiplied by the average character height and +then divided by 8.", ""); %name(ConvertDialogPointToPixels) wxPoint ConvertDialogToPixels(const wxPoint& pt); %name(ConvertDialogSizeToPixels) wxSize ConvertDialogToPixels(const wxSize& sz); - %name(DLG_PNT) wxPoint ConvertDialogToPixels(const wxPoint& pt); %name(DLG_SZE) wxSize ConvertDialogToPixels(const wxSize& sz); + + DocStr(ConvertPixelPointToDialog, + "Converts a point or size from pixels to dialog units. Dialog units +are used for maintaining a dialog's proportions even if the font +changes. For the x dimension, the dialog units are multiplied by the +average character width and then divided by 4. For the y dimension, +the dialog units are multiplied by the average character height and +then divided by 8.", ""); %name(ConvertPixelPointToDialog) wxPoint ConvertPixelsToDialog(const wxPoint& pt); %name(ConvertPixelSizeToDialog) wxSize ConvertPixelsToDialog(const wxSize& sz); @@ -453,107 +1068,266 @@ public: // mouse functions // --------------- - // move the mouse to the specified position - virtual void WarpPointer(int x, int y); + DocDeclStr( + virtual void , WarpPointer(int x, int y), + "Moves the pointer to the given position on the window. - // start or end mouse capture, these functions maintain the stack of - // windows having captured the mouse and after calling ReleaseMouse() - // the mouse is not released but returns to the window which had had - // captured it previously (if any) - void CaptureMouse(); - void ReleaseMouse(); +NOTE: This function is not supported under Mac because Apple Human +Interface Guidelines forbid moving the mouse cursor programmatically.", ""); + - // get the window which currently captures the mouse or NULL - static wxWindow *GetCapture(); + DocDeclStr( + void , CaptureMouse(), + "Directs all mouse input to this window. Call wx.Window.ReleaseMouse to +release the capture. - // does this window have the capture? - virtual bool HasCapture() const; +Note that wxWindows maintains the stack of windows having captured the +mouse and when the mouse is released the capture returns to the window +which had had captured it previously and it is only really released if +there were no previous window. In particular, this means that you must +release the mouse as many times as you capture it.", ""); + + DocDeclStr( + void , ReleaseMouse(), + "Releases mouse input captured with wx.Window.CaptureMouse.", ""); + + DocDeclStr( + static wxWindow *, GetCapture(), + "Returns the window which currently captures the mouse or None", ""); + + DocDeclStr( + virtual bool , HasCapture() const, + "Returns true if this window has the current mouse capture.", ""); + + + + // painting the window // ------------------- - // mark the specified rectangle (or the whole window) as "dirty" so it - // will be repainted - virtual void Refresh( bool eraseBackground = True, - const wxRect *rect = NULL ); + DocDeclStr( + virtual void , Refresh( bool eraseBackground = True, + const wxRect *rect = NULL ), + "Mark the specified rectangle (or the whole window) as \"dirty\" so it +will be repainted. Causes an EVT_PAINT event to be generated and sent +to the window.", ""); + - // a less awkward wrapper for Refresh - void RefreshRect(const wxRect& rect); + DocDeclStr( + void , RefreshRect(const wxRect& rect), + "Redraws the contents of the given rectangle: the area inside it will +be repainted. This is the same as Refresh but has a nicer syntax.", ""); + - // repaint all invalid areas of the window immediately - virtual void Update(); + DocDeclStr( + virtual void , Update(), + "Calling this method immediately repaints the invalidated area of the +window instead of waiting for the EVT_PAINT event to happen, (normally +this would usually only happen when the flow of control returns to the +event loop.) Notice that this function doesn't refresh the window and +does nothing if the window has been already repainted. Use Refresh +first if you want to immediately redraw the window (or some portion of +it) unconditionally.", ""); + + + DocDeclStr( + virtual void , ClearBackground(), + "Clears the window by filling it with the current background +colour. Does not cause an erase background event to be generated.", ""); + - // clear the window background - virtual void ClearBackground(); - // freeze the window: don't redraw it until it is thawed - virtual void Freeze(); + DocDeclStr( + virtual void , Freeze(), + "Freezes the window or, in other words, prevents any updates from +taking place on screen, the window is not redrawn at all. Thaw must be +called to reenable window redrawing. Calls to Freeze/Thaw may be +nested, with the actual Thaw being delayed until all the nesting has +been undone. + +This method is useful for visual appearance optimization (for example, +it is a good idea to use it before inserting large amount of text into +a wxTextCtrl under wxGTK) but is not implemented on all platforms nor +for all controls so it is mostly just a hint to wxWindows and not a +mandatory directive.", ""); + - // thaw the window: redraw it after it had been frozen - virtual void Thaw(); + DocDeclStr( + virtual void , Thaw(), + "Reenables window updating after a previous call to Freeze. Calls to +Freeze/Thaw may be nested, so Thaw must be called the same number of +times that Freeze was before the window will be updated.", ""); + - // adjust DC for drawing on this window - virtual void PrepareDC( wxDC & WXUNUSED(dc) ); + DocDeclStr( + virtual void , PrepareDC( wxDC & dc ), + "Call this function to prepare the device context for drawing a +scrolled image. It sets the device origin according to the current +scroll position.", ""); + - // the update region of the window contains the areas which must be - // repainted by the program - wxRegion& GetUpdateRegion(); + DocDeclStr( + wxRegion& , GetUpdateRegion(), + "Returns the region specifying which parts of the window have been +damaged. Should only be called within an EVT_PAINT handler.", ""); + - // get the update rectangle region bounding box in client coords - wxRect GetUpdateClientRect() const; + DocDeclStr( + wxRect , GetUpdateClientRect() const, + "Get the update rectangle region bounding box in client coords.", ""); + - // these functions verify whether the given point/rectangle belongs to - // (or at least intersects with) the update region + DocStr(IsExposed, + "Returns true if the given point or rectangle area has been exposed +since the last repaint. Call this in an paint event handler to +optimize redrawing by only redrawing those areas, which have been +exposed.", ""); bool IsExposed( int x, int y, int w=1, int h=1 ) const; %name(IsExposedPoint) bool IsExposed( const wxPoint& pt ) const; - %name(isExposedRect) bool IsExposed( const wxRect& rect ) const; + %name(IsExposedRect) bool IsExposed( const wxRect& rect ) const; // colours, fonts and cursors // -------------------------- - // set/retrieve the window colours (system defaults are used by - // default): Set functions return True if colour was changed - virtual bool SetBackgroundColour( const wxColour &colour ); - virtual bool SetForegroundColour( const wxColour &colour ); - wxColour GetBackgroundColour() const; - wxColour GetForegroundColour() const; + DocDeclStr( + virtual wxVisualAttributes , GetDefaultAttributes() const, + "Get the default attributes for an instance of this class. This is +useful if you want to use the same font or colour in your own control +as in a standard control -- which is a much better idea than hard +coding specific colours or fonts which might look completely out of +place on the user's system, especially if it uses themes.", ""); + + + DocDeclStr( + static wxVisualAttributes , + GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL), + "Get the default attributes for this class. This is useful if you want +to use the same font or colour in your own control as in a standard +control -- which is a much better idea than hard coding specific +colours or fonts which might look completely out of place on the +user's system, especially if it uses themes. + +The variant parameter is only relevant under Mac currently and is +ignore under other platforms. Under Mac, it will change the size of +the returned font. See `wx.Window.SetWindowVariant` for more about +this.", ""); + + + DocDeclStr( + virtual bool , SetBackgroundColour( const wxColour &colour ), + "Sets the background colour of the window. Returns True if the colour +was changed. The background colour is usually painted by the default +EVT_ERASE_BACKGROUND event handler function under Windows and +automatically under GTK. + +Note that setting the background colour may not cause an immediate +refresh, so you may wish to call ClearBackground or Refresh after +calling this function. + +Use this function with care under GTK+ as the new appearance of the +window might not look equally well when used with themes, i.e GTK+'s +ability to change its look as the user wishes with run-time loadable +modules.", ""); + + DocDeclStr( + void , SetDefaultBackgroundColour(const wxColour& colour), + "", ""); + + + + DocDeclStr( + virtual bool , SetForegroundColour( const wxColour &colour ), + "Sets the foreground colour of the window. Returns True is the colour +was changed. The interpretation of foreground colour is dependent on +the window class; it may be the text colour or other colour, or it may +not be used at all.", ""); + + DocDeclStr( + void , SetDefaultForegroundColour(const wxColour& colour), + "", ""); + + + + DocDeclStr( + wxColour , GetBackgroundColour() const, + "Returns the background colour of the window.", ""); + + DocDeclStr( + wxColour , GetForegroundColour() const, + "Returns the foreground colour of the window. The interpretation of +foreground colour is dependent on the window class; it may be the text +colour or other colour, or it may not be used at all.", ""); + + + + + DocDeclStr( + virtual bool , SetCursor( const wxCursor &cursor ), + "Sets the window's cursor. Notice that the window cursor also sets it +for the children of the window implicitly. + +The cursor may be wx.NullCursor in which case the window cursor will +be reset back to default.", ""); + + DocDeclStr( + wxCursor& , GetCursor(), + "Return the cursor associated with this window.", ""); + - // set/retrieve the cursor for this window (SetCursor() returns True - // if the cursor was really changed) - virtual bool SetCursor( const wxCursor &cursor ); - wxCursor& GetCursor(); - // set/retrieve the font for the window (SetFont() returns True if the - // font really changed) - virtual bool SetFont( const wxFont &font ); - wxFont& GetFont(); + DocDeclStr( + virtual bool , SetFont( const wxFont &font ), + "Sets the font for this window.", ""); + + DocDeclStr( + void , SetDefaultFont(const wxFont& font), + "", ""); + - // associate a caret with the window - void SetCaret(wxCaret *caret); + + DocDeclStr( + wxFont& , GetFont(), + "Returns the default font used for this window.", ""); - // get the current caret (may be NULL) - wxCaret *GetCaret() const; + - // get the (average) character size for the current font - virtual int GetCharHeight() const; - virtual int GetCharWidth() const; + DocDeclStr( + void , SetCaret(wxCaret *caret), + "Sets the caret associated with the window.", ""); + + DocDeclStr( + wxCaret *, GetCaret() const, + "Returns the caret associated with the window.", ""); + + + + DocDeclStr( + virtual int , GetCharHeight() const, + "Get the (average) character size for the current font.", ""); + + DocDeclStr( + virtual int , GetCharWidth() const, + "Get the (average) character size for the current font.", ""); + DocDeclAStr( void, GetTextExtent(const wxString& string, int *OUTPUT, int *OUTPUT), "GetTextExtent(String string) -> (width, height)", - "Get the width and height of the text using the current font."); + "Get the width and height of the text using the current font.", ""); DocDeclAStrName( void, GetTextExtent(const wxString& string, int *OUTPUT, int *OUTPUT, int *OUTPUT, int* OUTPUT, const wxFont* font = NULL), "GetFullTextExtent(String string, Font font=None) ->\n (width, height, descent, externalLeading)", - "Get the width, height, decent and leading of the text using the current or specified font.", + "Get the width, height, decent and leading of the text using the +current or specified font.", "", GetFullTextExtent); @@ -564,46 +1338,122 @@ public: %apply int * INOUT { int* x, int* y }; // translate to/from screen/client coordinates - %name(ClientToScreenXY) void ClientToScreen( int *x, int *y ) const; - %name(ScreenToClientXY) void ScreenToClient( int *x, int *y ) const; + DocDeclAStrName( + void , ClientToScreen( int *x, int *y ) const, + "ClientToScreenXY(int x, int y) -> (x,y)", + "Converts to screen coordinates from coordinates relative to this window.", "", + ClientToScreenXY); + + DocDeclAStrName( + void , ScreenToClient( int *x, int *y ) const, + "ScreenToClientXY(int x, int y) -> (x,y)", + "Converts from screen to client window coordinates.", "", + ScreenToClientXY); + - wxPoint ClientToScreen(const wxPoint& pt) const; - wxPoint ScreenToClient(const wxPoint& pt) const; + DocDeclStr( + wxPoint , ClientToScreen(const wxPoint& pt) const, + "Converts to screen coordinates from coordinates relative to this window.", ""); + + DocDeclStr( + wxPoint , ScreenToClient(const wxPoint& pt) const, + "Converts from screen to client window coordinates.", ""); + - // test where the given (in client coords) point lies - %name(HitTestXY) wxHitTest HitTest(wxCoord x, wxCoord y) const; - wxHitTest HitTest(const wxPoint& pt) const; + + DocDeclStrName( + wxHitTest , HitTest(wxCoord x, wxCoord y) const, + "Test where the given (in client coords) point lies", "", + HitTestXY); + + DocDeclStr( + wxHitTest , HitTest(const wxPoint& pt) const, + "Test where the given (in client coords) point lies", ""); + // misc // ---- - // get the window border style from the given flags: this is different from - // simply doing flags & wxBORDER_MASK because it uses GetDefaultBorder() to - // translate wxBORDER_DEFAULT to something reasonable - %name(GetBorderFlags) wxBorder GetBorder(long flags) const; + %nokwargs GetBorder; + DocDeclStr( + wxBorder , GetBorder(long flags) const, + "Get the window border style from the given flags: this is different +from simply doing flags & wxBORDER_MASK because it uses +GetDefaultBorder() to translate wxBORDER_DEFAULT to something +reasonable. +", ""); + + DocDeclStr( + wxBorder , GetBorder() const, + "Get border for the flags of this window", ""); + - // get border for the flags of this window - wxBorder GetBorder() const { return GetBorder(GetWindowStyleFlag()); } + - // send wxUpdateUIEvents to this window, and children if recurse is True - virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE); + DocDeclStr( + virtual void , UpdateWindowUI(long flags = wxUPDATE_UI_NONE), + "This function sends EVT_UPDATE_UI events to the window. The particular +implementation depends on the window; for example a wx.ToolBar will +send an update UI event for each toolbar button, and a wx.Frame will +send an update UI event for each menubar menu item. You can call this +function from your application to ensure that your UI is up-to-date at +a particular point in time (as far as your EVT_UPDATE_UI handlers are +concerned). This may be necessary if you have called +wx.UpdateUIEvent.SetMode or wx.UpdateUIEvent.SetUpdateInterval to +limit the overhead that wxWindows incurs by sending update UI events +in idle time.", +" +The flags should be a bitlist of one or more of the following values: + + ===================== ============================== + wx.UPDATE_UI_NONE No particular value + wx.UPDATE_UI_RECURSE Call the function for descendants + wx.UPDATE_UI_FROMIDLE Invoked from OnIdle + ===================== ============================== + +If you are calling this function from an OnIdle function, make sure +you pass the wx.UPDATE_UI_FROMIDLE flag, since this tells the window +to only update the UI elements that need to be updated in idle +time. Some windows update their elements only when necessary, for +example when a menu is about to be shown. The following is an example +of how to call UpdateWindowUI from an idle function:: + + def OnIdle(self, evt): + if wx.UpdateUIEvent.CanUpdate(self): + self.UpdateWindowUI(wx.UPDATE_UI_FROMIDLE); +"); + // TODO: using directors? // // do the window-specific processing after processing the update event // virtual void DoUpdateWindowUI(wxUpdateUIEvent& event) ; + + DocStr(PopupMenu, + "Pops up the given menu at the specified coordinates, relative to this +window, and returns control when the user has dismissed the menu. If a +menu item is selected, the corresponding menu event is generated and +will be processed as usual.", ""); %name(PopupMenuXY) bool PopupMenu(wxMenu *menu, int x, int y); bool PopupMenu(wxMenu *menu, const wxPoint& pos); + + + %extend { + DocStr(GetHandle, + "Returns the platform-specific handle (as a long integer) of the +physical window. Currently on wxMac it returns the handle of the +toplevel parent of the window.", ""); long GetHandle() { return wxPyGetWinHandle(self); } } + #ifdef __WXMSW__ // A way to do the native draw first... Too bad it isn't in wxGTK too. void OnPaint(wxPaintEvent& event); @@ -614,64 +1464,143 @@ public: // scrollbars // ---------- - // does the window have the scrollbar for this orientation? - bool HasScrollbar(int orient) const; + + DocDeclStr( + bool , HasScrollbar(int orient) const, + "Does the window have the scrollbar for this orientation?", ""); + // configure the window scrollbars - virtual void SetScrollbar( int orient, - int pos, - int thumbvisible, - int range, - bool refresh = True ); - virtual void SetScrollPos( int orient, int pos, bool refresh = True ); - virtual int GetScrollPos( int orient ) const; - virtual int GetScrollThumb( int orient ) const; - virtual int GetScrollRange( int orient ) const; - - // scroll window to the specified position - virtual void ScrollWindow( int dx, int dy, - const wxRect* rect = NULL ); - - // scrolls window by line/page: note that not all controls support this - // - // return True if the position changed, False otherwise - virtual bool ScrollLines(int WXUNUSED(lines)); - virtual bool ScrollPages(int WXUNUSED(pages)); - - // convenient wrappers for ScrollLines/Pages - bool LineUp(); - bool LineDown(); - bool PageUp(); - bool PageDown(); + DocDeclStr( + virtual void , SetScrollbar( int orientation, + int position, + int thumbSize, + int range, + bool refresh = True ), + "Sets the scrollbar properties of a built-in scrollbar.", + " + :param orientation: Determines the scrollbar whose page size is to + be set. May be wx.HORIZONTAL or wx.VERTICAL. + + :param position: The position of the scrollbar in scroll units. + + :param thumbSize: The size of the thumb, or visible portion of the + scrollbar, in scroll units. + + :param range: The maximum position of the scrollbar. + + :param refresh: True to redraw the scrollbar, false otherwise. +"); + + DocDeclStr( + virtual void , SetScrollPos( int orientation, int pos, bool refresh = True ), + "Sets the position of one of the built-in scrollbars.", ""); + + DocDeclStr( + virtual int , GetScrollPos( int orientation ) const, + "Returns the built-in scrollbar position.", ""); + + DocDeclStr( + virtual int , GetScrollThumb( int orientation ) const, + "Returns the built-in scrollbar thumb size.", ""); + + DocDeclStr( + virtual int , GetScrollRange( int orientation ) const, + "Returns the built-in scrollbar range.", ""); + + + + + DocDeclStr( + virtual void , ScrollWindow( int dx, int dy, + const wxRect* rect = NULL ), + "Physically scrolls the pixels in the window and move child windows +accordingly. Use this function to optimise your scrolling +implementations, to minimise the area that must be redrawn. Note that +it is rarely required to call this function from a user program.", +" + :param dx: Amount to scroll horizontally. + + :param dy: Amount to scroll vertically. + + :param rect: Rectangle to invalidate. If this is None, the whole + window is invalidated. If you pass a rectangle corresponding + to the area of the window exposed by the scroll, your + painting handler can optimize painting by checking for the + invalidated region."); + + + DocDeclStr( + virtual bool , ScrollLines(int lines), + "If the platform and window class supports it, scrolls the window by +the given number of lines down, if lines is positive, or up if lines +is negative. Returns True if the window was scrolled, False if it was +already on top/bottom and nothing was done.", ""); + + DocDeclStr( + virtual bool , ScrollPages(int pages), + "If the platform and window class supports it, scrolls the window by +the given number of pages down, if pages is positive, or up if pages +is negative. Returns True if the window was scrolled, False if it was +already on top/bottom and nothing was done.", ""); + + + DocDeclStr( + bool , LineUp(), + "This is just a wrapper for ScrollLines(-1).", ""); + + DocDeclStr( + bool , LineDown(), + "This is just a wrapper for ScrollLines(1).", ""); + + DocDeclStr( + bool , PageUp(), + "This is just a wrapper for ScrollPages(-1).", ""); + + DocDeclStr( + bool , PageDown(), + "This is just a wrapper for ScrollPages(1).", ""); + // context-sensitive help // ---------------------- - // associate this help text with this window - void SetHelpText(const wxString& text); + DocDeclStr( + void , SetHelpText(const wxString& text), + "Sets the help text to be used as context-sensitive help for this +window. Note that the text is actually stored by the current +wxHelpProvider implementation, and not in the window object itself.", ""); + - // associate this help text with all windows with the same id as this - // one - void SetHelpTextForId(const wxString& text); + DocDeclStr( + void , SetHelpTextForId(const wxString& text), + "Associate this help text with all windows with the same id as this +one.", ""); + - // get the help string associated with this window (may be empty) - wxString GetHelpText() const; + DocDeclStr( + wxString , GetHelpText() const, + "Gets the help text to be used as context-sensitive help for this +window. Note that the text is actually stored by the current +wxHelpProvider implementation, and not in the window object itself.", ""); + #ifndef __WXX11__ // tooltips // -------- - // the easiest way to set a tooltip for a window is to use this method + DocStr(SetToolTip, + "Attach a tooltip to the window.", ""); %name(SetToolTipString) void SetToolTip( const wxString &tip ); - - // attach a tooltip to the window void SetToolTip( wxToolTip *tip ); - // get the associated tooltip or NULL if none - wxToolTip* GetToolTip() const; + DocDeclStr( + wxToolTip* , GetToolTip() const, + "get the associated tooltip or None if none", ""); + // LINK ERROR --> wxString GetToolTipText() const; #endif @@ -684,13 +1613,25 @@ public: // set/retrieve the drop target associated with this window (may be // NULL; it's owned by the window and will be deleted by it) %apply SWIGTYPE *DISOWN { wxPyDropTarget *dropTarget }; - virtual void SetDropTarget( wxPyDropTarget *dropTarget ); + + DocDeclStr( + virtual void , SetDropTarget( wxPyDropTarget *dropTarget ), + "Associates a drop target with this window. If the window already has +a drop target, it is deleted.", ""); + %clear wxPyDropTarget *dropTarget; + + + DocDeclStr( + virtual wxPyDropTarget *, GetDropTarget() const, + "Returns the associated drop target, which may be None.", ""); - virtual wxPyDropTarget *GetDropTarget() const; #ifdef __WXMSW__ // TODO: should I drop-kick this? - void DragAcceptFiles(bool accept); + DocDeclStr( + void , DragAcceptFiles(bool accept), + "Enables or disables eligibility for drop file events, EVT_DROP_FILES. +Only available on Windows.", ""); #endif #endif @@ -699,27 +1640,77 @@ public: // ---------------------- // set the constraints for this window or retrieve them (may be NULL) - void SetConstraints( wxLayoutConstraints *constraints ); - wxLayoutConstraints *GetConstraints() const; + DocDeclStr( + void , SetConstraints( wxLayoutConstraints *constraints ), + "Sets the window to have the given layout constraints. If an existing +layout constraints object is already owned by the window, it will be +deleted. Pass None to disassociate and delete the window's current +constraints. + +You must call SetAutoLayout to tell a window to use the constraints +automatically in its default EVT_SIZE handler; otherwise, you must +handle EVT_SIZE yourself and call Layout() explicitly. When setting +both a wx.LayoutConstraints and a wx.Sizer, only the sizer will have +effect.", ""); + + DocDeclStr( + wxLayoutConstraints *, GetConstraints() const, + "Returns a pointer to the window's layout constraints, or None if there +are none.", ""); + - // when using constraints or sizers, it makes sense to update - // children positions automatically whenever the window is resized - // - this is done if autoLayout is on - void SetAutoLayout( bool autoLayout ); - bool GetAutoLayout() const; + DocDeclStr( + void , SetAutoLayout( bool autoLayout ), + "Determines whether the Layout function will be called automatically +when the window is resized. It is called implicitly by SetSizer but +if you use SetConstraints you should call it manually or otherwise the +window layout won't be correctly updated when its size changes.", ""); + + DocDeclStr( + bool , GetAutoLayout() const, + "Returns the current autoLayout setting", ""); + - // lay out the window and its children - virtual bool Layout(); + DocDeclStr( + virtual bool , Layout(), + "Invokes the constraint-based layout algorithm or the sizer-based +algorithm for this window. See SetAutoLayout: when auto layout is on, +this function gets called automatically by the default EVT_SIZE +handler when the window is resized.", ""); + - // sizers - void SetSizer(wxSizer *sizer, bool deleteOld = True ); - void SetSizerAndFit( wxSizer *sizer, bool deleteOld = True ); + DocDeclStr( + void , SetSizer(wxSizer *sizer, bool deleteOld = True ), + "Sets the window to have the given layout sizer. The window will then +own the object, and will take care of its deletion. If an existing +layout sizer object is already owned by the window, it will be deleted +if the deleteOld parameter is true. Note that this function will also +call SetAutoLayout implicitly with a True parameter if the sizer is +non-NoneL and False otherwise.", ""); + + DocDeclStr( + void , SetSizerAndFit( wxSizer *sizer, bool deleteOld = True ), + "The same as SetSizer, except it also sets the size hints for the +window based on the sizer's minimum size.", ""); + - wxSizer *GetSizer() const; + DocDeclStr( + wxSizer *, GetSizer() const, + "Return the sizer associated with the window by a previous call to +SetSizer or None if there isn't one.", ""); + // Track if this window is a member of a sizer - void SetContainingSizer(wxSizer* sizer); - wxSizer *GetContainingSizer() const; + DocDeclStr( + void , SetContainingSizer(wxSizer* sizer), + "This normally does not need to be called by application code. It is +called internally when a window is added to a sizer, and is used so +the window can remove itself from the sizer when it is destroyed.", ""); + + DocDeclStr( + wxSizer *, GetContainingSizer() const, + "Return the sizer that this window is a member of, if any, otherwise None.", ""); + @@ -741,10 +1732,53 @@ public: + + DocDeclStr( + virtual void , InheritAttributes(), + "This function is (or should be, in case of custom controls) called +during window creation to intelligently set up the window visual +attributes, that is the font and the foreground and background +colours. + +By 'intelligently' the following is meant: by default, all windows use +their own default attributes. However if some of the parent's +attributes are explicitly changed (that is, using SetFont and not +SetDefaultFont) and if the corresponding attribute hadn't been +explicitly set for this window itself, then this window takes the same +value as used by the parent. In addition, if the window overrides +ShouldInheritColours to return false, the colours will not be changed +no matter what and only the font might. + +This rather complicated logic is necessary in order to accomodate the +different usage scenarius. The most common one is when all default +attributes are used and in this case, nothing should be inherited as +in modern GUIs different controls use different fonts (and colours) +than their siblings so they can't inherit the same value from the +parent. However it was also deemed desirable to allow to simply change +the attributes of all children at once by just changing the font or +colour of their common parent, hence in this case we do inherit the +parents attributes. +", ""); + + +// TODO: Virtualize this with directors + DocDeclStr( + virtual bool , ShouldInheritColours() const, + "Return true from here to allow the colours of this window to be +changed by InheritAttributes, returning false forbids inheriting them +from the parent window. + +The base class version returns false, but this method is overridden in +wxControl where it returns true.", ""); + + + %pythoncode { def PostCreate(self, pre): - """Phase 3 of the 2-phase create - Call this method after precreating the window with the 2-phase create method.""" + """ + Phase 3 of the 2-phase create + Call this method after precreating the window with the 2-phase create method. + """ self.this = pre.this self.thisown = pre.thisown pre.thisown = 0 @@ -764,12 +1798,20 @@ public: %pythoncode { def DLG_PNT(win, point_or_x, y=None): + """ + Convenience function for converting a Point or (x,y) in + dialog units to pixel units. + """ if y is None: return win.ConvertDialogPointToPixels(point_or_x) else: return win.ConvertDialogPointToPixels(wx.Point(point_or_x, y)) def DLG_SZE(win, size_width, height=None): + """ + Convenience function for converting a Size or (w,h) in + dialog units to pixel units. + """ if height is None: return win.ConvertDialogSizeToPixels(size_width) else: @@ -785,7 +1827,29 @@ def DLG_SZE(win, size_width, height=None): // standalone functions for them. -// Find a window among any window in the application (all return NULL if not found) +DocStr(wxFindWindowById, +"Find the first window in the application with the given id. If parent +is None, the search will start from all top-level frames and dialog +boxes; if non-None, the search will be limited to the given window +hierarchy. The search is recursive in both cases.", ""); + +DocStr(wxFindWindowByName, +"Find a window by its name (as given in a window constructor or Create +function call). If parent is None, the search will start from all +top-level frames and dialog boxes; if non-None, the search will be +limited to the given window hierarchy. The search is recursive in both +cases. + +If no window with such name is found, wx.FindWindowByLabel is called.", ""); + +DocStr(wxFindWindowByLabel, +"Find a window by its label. Depending on the type of window, the label +may be a window title or panel item label. If parent is None, the +search will start from all top-level frames and dialog boxes; if +non-None, the search will be limited to the given window +hierarchy. The search is recursive in both cases.", ""); + + %inline %{ wxWindow* wxFindWindowById( long id, const wxWindow *parent = NULL ) { return wxWindow::FindWindowById(id, parent); @@ -804,12 +1868,25 @@ wxWindow* wxFindWindowByLabel( const wxString& label, +%{ +#ifdef __WXMSW__ +#include // to get wxGetWindowId +#endif +%} + %inline %{ - wxWindow* wxWindow_FromHWND(unsigned long hWnd) { + wxWindow* wxWindow_FromHWND(wxWindow* parent, unsigned long _hWnd) { #ifdef __WXMSW__ + WXHWND hWnd = (WXHWND)_hWnd; + long id = wxGetWindowId(hWnd); wxWindow* win = new wxWindow; + parent->AddChild(win); + win->SetEventHandler(win); win->SetHWND(hWnd); + win->SetId(id); win->SubclassWin(hWnd); + win->AdoptAttributesFromHWND(); + win->SetupColours(); return win; #else wxPyRaiseNotImplemented();