From ce6878e638ddf4efc75cf89a11e3f2171627b6c7 Mon Sep 17 00:00:00 2001 From: Robin Dunn Date: Tue, 10 Aug 2004 22:48:14 +0000 Subject: [PATCH] regenerated git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@28757 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- wxPython/docs/BUILD.html | 34 +- wxPython/docs/CHANGES.html | 19 +- wxPython/docs/xml/wxPython-metadata.xml | 2448 +++++++++++++++++++++-- 3 files changed, 2353 insertions(+), 148 deletions(-) diff --git a/wxPython/docs/BUILD.html b/wxPython/docs/BUILD.html index 26f00f4817..6d659d8e12 100644 --- a/wxPython/docs/BUILD.html +++ b/wxPython/docs/BUILD.html @@ -74,16 +74,31 @@ cd bld ../configure --prefix=/opt/wx/2.5 \ --with-gtk \ --with-opengl \ - --disable-monolithic \ --enable-debug \ --enable-geometry \ --enable-sound --with-sdl \ --enable-display \

On OS X of course you'll want to use --with-mac instead of ---with-gtk. For GTK2 and unicode add:

+--with-gtk.

+

NOTE: Due to a recent change there is a dependency problem in the +multilib builds of wxWidgets on OSX, so I have switched to a +monolithic build on that platform. (IOW, all of the core code in +one shared library instead of several.) I would also expect other +unix builds to do just fine with a monolithic library, but I havn't +tested it in a while so your mileage may vary. Anyway, to switch +to the monolithic build of wxWidgets just add this configure flag:

+
+--enable-monolithic \
+
+

By default GTK2 will be selected if it is on your build system. To +force the use of GTK 1.2.x add this flag:

+
+--disable-gtk2 \
+
+

To make the wxWidgets build be Unicode enabled (strongly +recommended if you are building with GTK2) then add:

---enable-gtk2 \
 --enable-unicode \

Notice that I used a prefix of /opt/wx/2.5. You can use whatever @@ -159,10 +174,17 @@ command line to ensure your new one is used instead:

 WX_CONFIG=/opt/wx/2.5/bin/wx-config
-

If you are building with GTK2 then add the following flags to the -command line:

+

By default setup.py will assume that you built wxWidgets to use +GTK2. If you built wxWidgets to use GTK 1.2.x then you should add +this flag to the command-line:

-WXPORT=gtk2 UNICODE=1
+WXPORT=gtk2 
+
+

If you would like to do a Unicode enabled build (all strings sent +to or retruned from wx functions are Unicode objects) and your +wxWidgets was built with unicode enabled then add this flag:

+
+UNICODE=1

If you are wanting to have the source files regenerated with swig, then you need to turn on the USE_SWIG flag and optionally tell it diff --git a/wxPython/docs/CHANGES.html b/wxPython/docs/CHANGES.html index 05bfa72824..92f7ab7040 100644 --- a/wxPython/docs/CHANGES.html +++ b/wxPython/docs/CHANGES.html @@ -11,7 +11,7 @@

Recent Changes for wxPython

-

2.5.2.3

+

2.5.2.5

wx.ADJUST_MINSIZE is now the default behaviour for window items in sizers. This means that the item's GetMinSize and/or GetBestSize will be called when calculating layout and the return value from that will @@ -86,6 +86,23 @@ in a subpackage of wx.lib.

It is now possible to change the tab traversal order of controls on a panel or dialog. For details see the new MoveAfterInTabOrder and MoveBeforeInTabOrder methods of wx.Window.

+

Applied (and heavily modified) a patch from Eugene +<svip123@fastmail.fm> that allows the sample modules in the demo to be +edited and reloaded, all from within the demo. You can switch back +and forth between the default and your edited version, and any errors +ocurring upon the reload are reported on the Demo tab.

+

Added a menu item in the demo that will open a PyShell window that has +the app and demo frame preloaded in the namespace. This is another +good way to explore and play with the objects in the currently running +sample. For example, load the Button sample and then do the following +in the PyShell:

+
+>>> b = frame.demoPage.GetChildren()[0]
+>>> for x in range(0, 500, 10):
+...     b.Move((x, 50))
+...     app.Yield(True)
+...     wx.MilliSleep(10)
+

2.5.1.5

diff --git a/wxPython/docs/xml/wxPython-metadata.xml b/wxPython/docs/xml/wxPython-metadata.xml index d8b1da291e..854b9639fc 100644 --- a/wxPython/docs/xml/wxPython-metadata.xml +++ b/wxPython/docs/xml/wxPython-metadata.xml @@ -589,6 +589,7 @@ with floating point values. GetFloor() -> (x,y) + Convert to integer @@ -596,6 +597,7 @@ with floating point values. GetRounded() -> (x,y) + Convert to integer @@ -1123,6 +1125,9 @@ def MemoryFSHandler_AddFile(filename, a, b=''): FindFirstUnusedColour(int startR=1, int startG=0, int startB=0) -> (success, r, g, b) + Find first colour that is not used in the image and has higher RGB +values than startR, startG, startB. Returns a tuple consisting of a +success flag and rgb values. @@ -1275,6 +1280,9 @@ def MemoryFSHandler_AddFile(filename, a, b=''): FindFirstUnusedColour(int startR=1, int startG=0, int startB=0) -> (success, r, g, b) + Find first colour that is not used in the image and has higher RGB +values than startR, startG, startB. Returns a tuple consisting of a +success flag and rgb values. @@ -1642,6 +1650,22 @@ def MemoryFSHandler_AddFile(filename, a, b=''): __init__(self) -> TIFFHandler + + Performs quantization, or colour reduction, on a wxImage. + + Quantize(Image src, Image dest, int desiredNoColours=236, int flags=wxQUANTIZE_INCLUDE_WINDOWS_COLOURS|wxQUANTIZE_FILL_DESTINATION_IMAGE) -> bool + Reduce the colours in the source image and put the result into the +destination image, setting the palette in the destination if +needed. Both images may be the same, to overwrite the source image. +:todo: Create a version that returns the wx.Palette used. + + + + + + + + #--------------------------------------------------------------------------- @@ -2264,6 +2288,16 @@ EVT_CONTEXT_MENU = wx.PyEventBinder( wxEVT_CONTEXT_MENU ) ShiftDown(self) -> bool + + CmdDown(self) -> bool + "Cmd" is a pseudo key which is the same as Control for PC and Unix +platforms but the special "Apple" (a.k.a as "Command") key on +Macs: it makes often sense to use it instead of, say, `ControlDown` +because Cmd key is used for the same thing under Mac as Ctrl +elsewhere. The Ctrl still exists, it's just not used for this +purpose. So for non-Mac platforms this is the same as `ControlDown` +and Macs this is the same as `MetaDown`. + LeftDown(self) -> bool @@ -2417,14 +2451,24 @@ happened. ShiftDown(self) -> bool + + CmdDown(self) -> bool + "Cmd" is a pseudo key which is the same as Control for PC and Unix +platforms but the special "Apple" (a.k.a as "Command") key on +Macs: it makes often sense to use it instead of, say, `ControlDown` +because Cmd key is used for the same thing under Mac as Ctrl +elsewhere. The Ctrl still exists, it's just not used for this +purpose. So for non-Mac platforms this is the same as `ControlDown` +and Macs this is the same as `MetaDown`. + HasModifiers(self) -> bool GetKeyCode(self) -> int - - GetUniChar(self) -> int + + GetUnicodeKey(self) -> int GetRawKeyCode(self) -> unsigned int @@ -2921,18 +2965,24 @@ happened. GetDirection(self) -> bool - SetDirection(self, bool bForward) + SetDirection(self, bool forward) - + IsWindowChange(self) -> bool - SetWindowChange(self, bool bIs) + SetWindowChange(self, bool ischange) + + + + + + SetFlags(self, long flags) - + @@ -3265,7 +3315,17 @@ systems where more than one is available, (Sun, SGI, XFree86 4, etc.) SetAssertMode(self, int mode) - Set the OnAssert behaviour for debug and hybrid builds. + 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 + ========================= ======================================= + + @@ -3394,6 +3454,8 @@ class PyOnDemandOutputWindow: def __init__(self, title = "wxPython: stdout/stderr"): self.frame = None self.title = title + self.pos = wx.DefaultPosition + self.size = (450, 300) self.parent = None def SetParent(self, parent): @@ -3402,12 +3464,11 @@ class PyOnDemandOutputWindow: def CreateOutputWindow(self, st): - self.frame = wx.Frame(self.parent, -1, self.title, - style=wx.DEFAULT_FRAME_STYLE | wx.NO_FULL_REPAINT_ON_RESIZE) + self.frame = wx.Frame(self.parent, -1, self.title, self.pos, self.size, + style=wx.DEFAULT_FRAME_STYLE) self.text = wx.TextCtrl(self.frame, -1, "", - style = wx.TE_MULTILINE | wx.TE_READONLY) + style=wx.TE_MULTILINE|wx.TE_READONLY) self.text.AppendText(st) - self.frame.SetSize((450, 300)) self.frame.Show(True) EVT_CLOSE(self.frame, self.OnCloseWindow) @@ -3443,6 +3504,10 @@ class PyOnDemandOutputWindow: wx.CallAfter(self.frame.Close) + def flush(self): + pass + + #---------------------------------------------------------------------- @@ -3581,6 +3646,22 @@ your Mac.""" _sys.stdout, _sys.stderr = self.saveStdio + def SetOutputWindowAttributes(self, title=None, pos=None, size=None): + """ + Set the title, position and/or size of the output window if + the stdio has been redirected. This should be called before + any output would cause the output window to be created. + """ + if self.stdioWin: + if title is not None: + self.stdioWin.title = title + if pos is not None: + self.stdioWin.pos = pos + if size is not None: + self.stdioWin.size = size + + + # change from wx.PyApp_XX to wx.App_XX App_GetMacSupportPCMenuShortcuts = _core_.PyApp_GetMacSupportPCMenuShortcuts @@ -3671,7 +3752,14 @@ as well. See `__init__` for of the tuple values. :see: `wx.AcceleratorTable` __init__(self, int flags=0, int keyCode=0, int cmdID=0) -> AcceleratorEntry - Construct a wx.AcceleratorEntry. + 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. + @@ -3708,7 +3796,28 @@ as well. See `__init__` for of the tuple values. 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. +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` + __init__(entries) -> AcceleratorTable @@ -3755,6 +3864,126 @@ items or or of 3-tuples (flags, keyCode, cmdID) 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. + ============================= ===================================== + @@ -3792,7 +4021,25 @@ appear on screen themselves. 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. +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. @@ -3861,7 +4108,16 @@ constructor or via wx.Window.SetName. SetWindowVariant(self, int variant) Sets the variant of the window/font size to use for this window, if -the platform supports variants, for example, wxMac. +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) + ======================== ======================================= + @@ -3963,6 +4219,14 @@ default values. + + SetBestFittingSize(self, Size size=DefaultSize) + A 'Smart' SetSize that will fill in default size components with the +window's *best size* values. Also set's the minsize for use with sizers. + + + + Raise(self) Raises the window to the top of the window hierarchy if it is a @@ -4083,6 +4347,18 @@ after calling Fit. + + InvalidateBestSize(self) + Reset the cached best size value so it will be recalculated the next +time it is needed. + + + GetBestFittingSize(self) -> Size + This function will merge the window's best size into the window's +minimum size, giving priority to the min size components, and returns +the results. + + GetAdjustedBestSize(self) -> Size This method is similar to GetBestSize, except in one @@ -4136,12 +4412,20 @@ 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. - + + SetSizeHints(self, int minW, int minH, int maxW=-1, int maxH=-1, int incW=-1, + int incH=-1) 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. +will not be able to size the window outside the given bounds (if it is +a top-level window.) Sizers will also inspect the minimum window size +and will use that value if set when calculating layout. + +The resizing increments are only significant under Motif or Xt. + +:see: `GetMinSize`, `GetMaxSize`, `SetMinSize`, `SetMaxSize` + @@ -4151,22 +4435,27 @@ resizing increments are only significant under Motif or Xt. - - SetSizeHints(self, int minW, int minH, int maxW=-1, int maxH=-1, int incW=-1, - int incH=-1) -SetSizeHints(self, Size minSize, Size maxSize=DefaultSize, Size incSize=DefaultSize) + + SetSizeHintsSz(self, Size minSize, Size maxSize=DefaultSize, Size incSize=DefaultSize) 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. +will not be able to size the window outside the given bounds (if it is +a top-level window.) Sizers will also inspect the minimum window size +and will use that value if set when calculating layout. + +The resizing increments are only significant under Motif or Xt. + +:see: `GetMinSize`, `GetMaxSize`, `SetMinSize`, `SetMaxSize` + - + + SetVirtualSizeHints(self, int minW, int minH, int maxW=-1, int maxH=-1) 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 @@ -4178,9 +4467,8 @@ the virtual area of the window outside the given bounds. - - SetVirtualSizeHints(self, int minW, int minH, int maxW=-1, int maxH=-1) -SetVirtualSizeHints(self, Size minSize, Size maxSize=DefaultSize) + + SetVirtualSizeHintsSz(self, Size minSize, Size maxSize=DefaultSize) 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 @@ -4190,6 +4478,28 @@ the virtual area of the window outside the given bounds. + + GetMaxSize(self) -> Size + + + GetMinSize(self) -> Size + + + SetMinSize(self, Size minSize) + A more convenient method than `SetSizeHints` for setting just the +min size. + + + + + + SetMaxSize(self, Size maxSize) + A more convenient method than `SetSizeHints` for setting just the +max size. + + + + GetMinWidth(self) -> int @@ -4202,12 +4512,6 @@ the virtual area of the window outside the given bounds. GetMaxHeight(self) -> int - - GetMaxSize(self) -> Size - - - GetMinSize(self) -> Size - SetVirtualSize(self, Size size) Set the the virtual size of a window in pixels. For most windows this @@ -4397,6 +4701,51 @@ by pressing <Enter> such as the OK button on a wx.Dialog. + + Navigate(self, int flags=NavigationKeyEvent.IsForward) -> bool + Does keyboard navigation from this window to another, by sending a +`wx.NavigationKeyEvent`. + + :param flags: A combination of the ``IsForward`` or ``IsBackward`` + and the ``WinChange`` values in the `wx.NavigationKeyEvent` + class, which determine if the navigation should be in forward + or reverse order, and if it should be able to cross parent + window boundaries, such as between notebook pages or MDI child + frames. Typically the status of the Shift key (for forward or + backward) or the Control key (for WinChange) would be used to + determine how to set the flags. + +One situation in which you may wish to call this method is from a text +control custom keypress handler to do the default navigation behaviour +for the tab key, since the standard default behaviour for a multiline +text control with the wx.TE_PROCESS_TAB style is to insert a tab and +not navigate to the next control. + + + + + + MoveAfterInTabOrder(self, Window win) + Moves this window in the tab navigation order after the specified +sibling window. This means that when the user presses the TAB key on +that other window, the focus switches to this window. + +The default tab order is the same as creation order. This function +and `MoveBeforeInTabOrder` allow to change it after creating all the +windows. + + + + + + + MoveBeforeInTabOrder(self, Window win) + Same as `MoveAfterInTabOrder` except that it inserts this window just +before win instead of putting it right after it. + + + + GetChildren(self) -> PyObject Returns a list of the window's children. NOTE: Currently this is a @@ -4818,22 +5167,23 @@ this. 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. +automatically under GTK. Using `wx.NullColour` will reset the window +to the default background colour. Note that setting the background colour may not cause an immediate -refresh, so you may wish to call ClearBackground or Refresh after +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. +Using this function will disable attempts to use themes for this +window, if the system supports them. Use with care since usually the +themes represent the appearance chosen by the user to be used for all +applications on the system. - - SetOwnBackroundColour(self, Colour colour) + + SetOwnBackgroundColour(self, Colour colour) @@ -4917,6 +5267,7 @@ be reset back to default. GetTextExtent(String string) -> (width, height) + Get the width and height of the text using the current font. @@ -5008,32 +5359,53 @@ 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. +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); + - PopupMenuXY(self, Menu menu, int x, int y) -> bool - 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. + PopupMenuXY(self, Menu menu, int x=-1, int y=-1) -> bool + 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. If the default position is given then the current position of the +mouse cursor will be used. - - + + - PopupMenu(self, Menu menu, Point pos) -> bool - 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. + PopupMenu(self, Menu menu, Point pos=DefaultPosition) -> bool + 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. If the default position is given then the current position of the +mouse cursor will be used. - + @@ -5052,7 +5424,19 @@ toplevel parent of the window. SetScrollbar(self, int orientation, int position, int thumbSize, int range, bool refresh=True) - Sets the scrollbar properties of a built-in scrollbar. + 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. + @@ -5096,7 +5480,16 @@ toplevel parent of the window. 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. +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. @@ -6176,7 +6569,7 @@ has wx.LB_SORT or wx.CB_SORT style). - AppendItems(self, wxArrayString strings) + AppendItems(self, List strings) Apend several items at once to the control. Notice that calling this method may be much faster than appending the items one by one if you need to add a lot of items. @@ -6379,6 +6772,11 @@ account. GetMinSize(self) -> Size Get the minimum size needed for the item. + + GetMinSizeWithBorder(self) -> Size + Get the minimum size needed for the item with space for the borders +added, if needed. + SetInitSize(self, int x, int y) @@ -6540,7 +6938,17 @@ handle differences in font sizes or different window (dialog item) sizes on different platforms without problems. If for example the standard font as well as the overall design of Mac widgets requires more space than on Windows, then the initial size of a dialog using a -sizer will automatically be bigger on Mac than on Windows. +sizer will automatically be bigger on Mac than on Windows. + +:note: If you wish to create a custom sizer class in wxPython you + should derive the class from `wx.PySizer` in order to get + Python-aware capabilities for the various virtual methods. + +:see: `wx.SizerItem` + +:todo: More dscriptive text here along with some pictures... + + _setOORInfo(self, PyObject _self) @@ -6551,7 +6959,102 @@ sizer will automatically be bigger on Mac than on Windows. Add(self, item, int proportion=0, int flag=0, int border=0, PyObject userData=None) - Appends a child item to the sizer. + Appends a child item to the sizer. + + :param item: The item can be one of three kinds of objects: + + - **window**: A `wx.Window` to be managed by the sizer. Its + minimal size (either set explicitly by the user or + calculated internally when constructed with wx.DefaultSize) + is interpreted as the minimal size to use when laying out + item in the sizer. This is particularly useful in + connection with `wx.Window.SetSizeHints`. + + - **sizer**: The (child-)sizer to be added to the sizer. This + allows placing a child sizer in a sizer and thus to create + hierarchies of sizers (typically a vertical box as the top + sizer and several horizontal boxes on the level beneath). + + - **size**: A `wx.Size` or a 2-element sequence of integers + that represents the width and height of a spacer to be added + to the sizer. Adding spacers to sizers gives more + flexibility in the design of dialogs; imagine for example a + horizontal box with two buttons at the bottom of a dialog: + you might want to insert a space between the two buttons and + make that space stretchable using the *proportion* value and + the result will be that the left button will be aligned with + the left side of the dialog and the right button with the + right side - the space in between will shrink and grow with + the dialog. + + :param proportion: Although the meaning of this parameter is + undefined in wx.Sizer, it is used in `wx.BoxSizer` to indicate + if a child of a sizer can change its size in the main + orientation of the wx.BoxSizer - where 0 stands for not + changeable and a value of more than zero is interpreted + relative (a proportion of the total) to the value of other + children of the same wx.BoxSizer. For example, you might have + a horizontal wx.BoxSizer with three children, two of which are + supposed to change their size with the sizer. Then the two + stretchable windows should each be given *proportion* value of + 1 to make them grow and shrink equally with the sizer's + horizontal dimension. But if one of them had a *proportion* + value of 2 then it would get a double share of the space + available after the fixed size items are positioned. + + :param flag: This parameter can be used to set a number of flags + which can be combined using the binary OR operator ``|``. Two + main behaviours are defined using these flags. One is the + border around a window: the *border* parameter determines the + border width whereas the flags given here determine which + side(s) of the item that the border will be added. The other + flags determine how the sizer item behaves when the space + allotted to the sizer changes, and is somewhat dependent on + the specific kind of sizer used. + + +----------------------------+------------------------------------------+ + |- wx.TOP |These flags are used to specify | + |- wx.BOTTOM |which side(s) of the sizer item that | + |- wx.LEFT |the *border* width will apply to. | + |- wx.RIGHT | | + |- wx.ALL | | + | | | + +----------------------------+------------------------------------------+ + |- wx.EXAPAND |The item will be expanded to fill | + | |the space allotted to the item. | + +----------------------------+------------------------------------------+ + |- wx.SHAPED |The item will be expanded as much as | + | |possible while also maintaining its | + | |aspect ratio | + +----------------------------+------------------------------------------+ + |- wx.FIXED_MINSIZE |Normally wx.Sizers will use | + | |`wx.Window.GetMinSize` or | + | |`wx.Window.GetBestSize` to determine what | + | |the minimal size of window items should | + | |be, and will use that size to calculate | + | |the layout. This allows layouts to adjust | + | |when an item changes and it's best size | + | |becomes different. If you would rather | + | |have a window item stay the size it | + | |started with then use wx.FIXED_MINSIZE. | + +----------------------------+------------------------------------------+ + |- wx.ALIGN_CENTER |The wx.ALIGN flags allow you to specify | + |- wx.ALIGN_LEFT |the alignment of the item within the space| + |- wx.ALIGN_RIGHT |allotted to it by the sizer, ajusted for | + |- wx.ALIGN_TOP |the border if any. | + |- wx.ALIGN_BOTTOM | | + |- wx.ALIGN_CENTER_VERTICAL | | + |- wx.ALIGN_CENTER_HORIZONTAL| | + +----------------------------+------------------------------------------+ + + + :param border: Determines the border width, if the *flag* + parameter is set to include any border flag. + + :param userData: Allows an extra object to be attached to the + sizer item, for use in derived classes when sizing information + is more complex than the *proportion* and *flag* will allow for. + @@ -6594,7 +7097,13 @@ cause any layout or resizing to take place, call `Layout` to update the layout on screen after removing a child from the sizer. The *item* parameter can be either a window, a sizer, or the zero-based index of an item to remove. Returns True if the child item was found -and removed. +and removed. + +:note: For historical reasons calling this method with a `wx.Window` + parameter is depreacted, as it will not be able to destroy the + window since it is owned by its parent. You should use `Detach` + instead. + @@ -6854,7 +7363,24 @@ class. laid out in rather simple basic geometry, typically in a row or a column or nested hierarchies of either. A wx.BoxSizer will lay out its items in a simple row or column, depending on the orientation -parameter passed to the constructor. +parameter passed to the constructor. + +It is the unique feature of a box sizer, that it can grow in both +directions (height and width) but can distribute its growth in the +main direction (horizontal for a row) *unevenly* among its children. +This is determined by the proportion parameter give to items when they +are added to the sizer. It is interpreted as a weight factor, i.e. it +can be zero, indicating that the window may not be resized at all, or +above zero. If several windows have a value above zero, the value is +interpreted relative to the sum of all weight factors of the sizer, so +when adding two windows with a value of 1, they will both get resized +equally and each will receive half of the available space after the +fixed size items have been sized. If the items have unequal +proportion settings then they will receive a coresondingly unequal +allotment of the free space. + +:see: `wx.StaticBoxSizer` + __init__(self, int orient=HORIZONTAL) -> BoxSizer @@ -7111,9 +7637,13 @@ non-flexible direction if there is one. GetRowHeights(self) -> list + Returns a list of integers representing the heights of each of the +rows in the sizer. GetColWidths(self) -> list + Returns a list of integers representing the widths of each of the +columns in the sizer. @@ -7615,7 +8145,51 @@ one of eight possible constraints that a window can be involved in. You will never need to create an instance of wx.IndividualLayoutConstraint, rather you should create a `wx.LayoutConstraints` instance and use the individual contstraints -that it contains. +that it contains. + +Constraints are initially set to have the relationship +wx.Unconstrained, which means that their values should be calculated +by looking at known constraints. + +The Edge specifies the type of edge or dimension of a window. + +Edges +------ + ================== ============================================== + wx.Left The left edge. + wx.Top The top edge. + wx.Right The right edge. + wx.Bottom The bottom edge. + wx.CentreX The x-coordinate of the centre of the window. + wx.CentreY The y-coordinate of the centre of the window. + ================== ============================================== + + +The Relationship specifies the relationship that this edge or +dimension has with another specified edge or dimension. Normally, the +user doesn't use these directly because functions such as Below and +RightOf are a convenience for using the more general Set function. + +Relationships +------------- + ================== ============================================== + wx.Unconstrained The edge or dimension is unconstrained + (the default for edges.) + wx.AsIs The edge or dimension is to be taken from the current + window position or size (the default for dimensions.) + wx.Above The edge should be above another edge. + wx.Below The edge should be below another edge. + wx.LeftOf The edge should be to the left of another edge. + wx.RightOf The edge should be to the right of another edge. + wx.SameAs The edge or dimension should be the same as another edge + or dimension. + wx.PercentOf The edge or dimension should be a percentage of another + edge or dimension. + wx.Absolute The edge or dimension should be a given absolute value. + ================== ============================================== + +:see: `wx.LayoutConstraints`, `wx.Window.SetConstraints` + Set(self, int rel, Window otherW, int otherE, int val=0, int marg=wxLAYOUT_DEFAULT_MARGIN) @@ -7947,7 +8521,7 @@ def CallAfter(callable, *args, **kw): :see: `wx.FutureCall` """ app = wx.GetApp() - assert app, 'No wxApp created yet' + assert app is not None, 'No wx.App created yet' global _wxPyCallAfterId if _wxPyCallAfterId is None: @@ -8401,11 +8975,39 @@ is returned if the pixel is invalid (on X, unallocated). 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. +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` + __init__(self, Colour colour, int style=SOLID) -> Brush - Constructs a brush from a `wx.Colour` object and a style. + 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. + =================== ============================= + + @@ -8461,11 +9063,50 @@ 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. +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. + __init__(self, String name, int type=BITMAP_TYPE_ANY) -> Bitmap - 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` + @@ -8838,6 +9479,40 @@ 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. + + +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.) + ======================== ====================================== + @@ -8868,7 +9543,15 @@ cursors are available on all platforms. Constructs a cursor from a wxImage. The cursor is monochrome, colors with the RGB elements all greater than 127 will be foreground, colors less than this background. The mask (if any) will be used as -transparent. +transparent. +In MSW the foreground will be white and the background +black. The cursor is resized to 32x32. + +In GTK, the two most frequent colors will be used for foreground and +background. The cursor will be displayed at the size of the image. + +On MacOS the cursor is resized to 16x16 and currently only shown as +black/white (mask respected). @@ -8895,10 +9578,16 @@ transparent. - RegionFromBitmap(Bitmap bmp, Colour transColour=NullColour, int tolerance=0) -> Region + RegionFromBitmap(Bitmap bmp) -> Region + + + + + + RegionFromBitmapColour(Bitmap bmp, Colour transColour, int tolerance=0) -> Region - + @@ -9045,10 +9734,16 @@ transparent. ConvertToBitmap(self) -> Bitmap - UnionBitmap(self, Bitmap bmp, Colour transColour=NullColour, int tolerance=0) -> bool + UnionBitmap(self, Bitmap bmp) -> bool - + + + + UnionBitmapColour(self, Bitmap bmp, Colour transColour, int tolerance=0) -> bool + + + @@ -9744,18 +10439,53 @@ if wx.Platform == "__WXMSW__": #--------------------------------------------------------------------------- + A wx.DC is a device context onto which graphics and text can be +drawn. It is intended to represent a number of output devices in a +generic way, so a window can have a device context associated with it, +and a printer also has a device context. In this way, the same piece +of code may write to a number of different devices, if the device +context is used as a parameter. + +Derived types of wxDC have documentation for specific features only, +so refer to this section for most device context information. + +The wx.DC class is abstract and can not be instantiated, you must use +one of the derived classes instead. Which one will depend on the +situation in which it is used. __del__(self) BeginDrawing(self) + Allows for optimization of drawing code on platforms that need it. On +other platforms this is just an empty function and is harmless. To +take advantage of this postential optimization simply enclose each +group of calls to the drawing primitives within calls to +`BeginDrawing` and `EndDrawing`. EndDrawing(self) + Ends the group of drawing primitives started with `BeginDrawing`, and +invokes whatever optimization is available for this DC type on the +current platform. FloodFill(self, int x, int y, Colour col, int style=FLOOD_SURFACE) -> bool + Flood fills the device context starting from the given point, using +the current brush colour, and using a style: + + - **wxFLOOD_SURFACE**: the flooding occurs until a colour other than + the given colour is encountered. + + - **wxFLOOD_BORDER**: the area to be flooded is bounded by the given + colour. + +Returns False if the operation failed. + +Note: The present implementation for non-Windows platforms may fail to +find colour borders if the pixels do not match the colour +exactly. However the function will still return true. @@ -9765,6 +10495,20 @@ if wx.Platform == "__WXMSW__": FloodFillPoint(self, Point pt, Colour col, int style=FLOOD_SURFACE) -> bool + Flood fills the device context starting from the given point, using +the current brush colour, and using a style: + + - **wxFLOOD_SURFACE**: the flooding occurs until a colour other than + the given colour is encountered. + + - **wxFLOOD_BORDER**: the area to be flooded is bounded by the given + colour. + +Returns False if the operation failed. + +Note: The present implementation for non-Windows platforms may fail to +find colour borders if the pixels do not match the colour +exactly. However the function will still return true. @@ -9773,6 +10517,7 @@ if wx.Platform == "__WXMSW__": GetPixel(self, int x, int y) -> Colour + Gets the colour at the specified location on the DC. @@ -9786,6 +10531,10 @@ if wx.Platform == "__WXMSW__": DrawLine(self, int x1, int y1, int x2, int y2) + Draws a line from the first point to the second. The current pen is +used for drawing the line. Note that the second point is *not* part of +the line and is not drawn by this function (this is consistent with +the behaviour of many other toolkits). @@ -9795,6 +10544,10 @@ if wx.Platform == "__WXMSW__": DrawLinePoint(self, Point pt1, Point pt2) + Draws a line from the first point to the second. The current pen is +used for drawing the line. Note that the second point is *not* part of +the line and is not drawn by this function (this is consistent with +the behaviour of many other toolkits). @@ -9802,6 +10555,9 @@ if wx.Platform == "__WXMSW__": CrossHair(self, int x, int y) + Displays a cross hair using the current pen. This is a vertical and +horizontal line the height and width of the window, centred on the +given point. @@ -9809,12 +10565,21 @@ if wx.Platform == "__WXMSW__": CrossHairPoint(self, Point pt) + Displays a cross hair using the current pen. This is a vertical and +horizontal line the height and width of the window, centred on the +given point. DrawArc(self, int x1, int y1, int x2, int y2, int xc, int yc) + Draws an arc of a circle, centred on the *center* point (xc, yc), from +the first point to the second. The current pen is used for the outline +and the current brush for filling the shape. + +The arc is drawn in an anticlockwise direction from the start point to +the end point. @@ -9825,15 +10590,22 @@ if wx.Platform == "__WXMSW__": - DrawArcPoint(self, Point pt1, Point pt2, Point centre) + DrawArcPoint(self, Point pt1, Point pt2, Point center) + Draws an arc of a circle, centred on the *center* point (xc, yc), from +the first point to the second. The current pen is used for the outline +and the current brush for filling the shape. + +The arc is drawn in an anticlockwise direction from the start point to +the end point. - + DrawCheckMark(self, int x, int y, int width, int height) + Draws a check mark inside the given rectangle. @@ -9843,32 +10615,52 @@ if wx.Platform == "__WXMSW__": DrawCheckMarkRect(self, Rect rect) + Draws a check mark inside the given rectangle. - DrawEllipticArc(self, int x, int y, int w, int h, double sa, double ea) + DrawEllipticArc(self, int x, int y, int w, int h, double start, double end) + Draws an arc of an ellipse, with the given rectangle defining the +bounds of the ellipse. The current pen is used for drawing the arc and +the current brush is used for drawing the pie. + +The *start* and *end* parameters specify the start and end of the arc +relative to the three-o'clock position from the center of the +rectangle. Angles are specified in degrees (360 is a complete +circle). Positive values mean counter-clockwise motion. If start is +equal to end, a complete ellipse will be drawn. - - + + - DrawEllipticArcPointSize(self, Point pt, Size sz, double sa, double ea) + DrawEllipticArcPointSize(self, Point pt, Size sz, double start, double end) + Draws an arc of an ellipse, with the given rectangle defining the +bounds of the ellipse. The current pen is used for drawing the arc and +the current brush is used for drawing the pie. + +The *start* and *end* parameters specify the start and end of the arc +relative to the three-o'clock position from the center of the +rectangle. Angles are specified in degrees (360 is a complete +circle). Positive values mean counter-clockwise motion. If start is +equal to end, a complete ellipse will be drawn. - - + + DrawPoint(self, int x, int y) + Draws a point using the current pen. @@ -9876,12 +10668,16 @@ if wx.Platform == "__WXMSW__": DrawPointPoint(self, Point pt) + Draws a point using the current pen. DrawRectangle(self, int x, int y, int width, int height) + Draws a rectangle with the given top left corner, and with the given +size. The current pen is used for the outline and the current brush +for filling the shape. @@ -9891,12 +10687,18 @@ if wx.Platform == "__WXMSW__": DrawRectangleRect(self, Rect rect) + Draws a rectangle with the given top left corner, and with the given +size. The current pen is used for the outline and the current brush +for filling the shape. DrawRectanglePointSize(self, Point pt, Size sz) + Draws a rectangle with the given top left corner, and with the given +size. The current pen is used for the outline and the current brush +for filling the shape. @@ -9904,6 +10706,17 @@ if wx.Platform == "__WXMSW__": DrawRoundedRectangle(self, int x, int y, int width, int height, double radius) + Draws a rectangle with the given top left corner, and with the given +size. The corners are quarter-circles using the given radius. The +current pen is used for the outline and the current brush for filling +the shape. + +If radius is positive, the value is assumed to be the radius of the +rounded corner. If radius is negative, the absolute value is assumed +to be the proportion of the smallest dimension of the rectangle. This +means that the corner can be a sensible size relative to the size of +the rectangle, and also avoids the strange effects X produces when the +corners are too big for the rectangle. @@ -9914,6 +10727,17 @@ if wx.Platform == "__WXMSW__": DrawRoundedRectangleRect(self, Rect r, double radius) + Draws a rectangle with the given top left corner, and with the given +size. The corners are quarter-circles using the given radius. The +current pen is used for the outline and the current brush for filling +the shape. + +If radius is positive, the value is assumed to be the radius of the +rounded corner. If radius is negative, the absolute value is assumed +to be the proportion of the smallest dimension of the rectangle. This +means that the corner can be a sensible size relative to the size of +the rectangle, and also avoids the strange effects X produces when the +corners are too big for the rectangle. @@ -9921,6 +10745,17 @@ if wx.Platform == "__WXMSW__": DrawRoundedRectanglePointSize(self, Point pt, Size sz, double radius) + Draws a rectangle with the given top left corner, and with the given +size. The corners are quarter-circles using the given radius. The +current pen is used for the outline and the current brush for filling +the shape. + +If radius is positive, the value is assumed to be the radius of the +rounded corner. If radius is negative, the absolute value is assumed +to be the proportion of the smallest dimension of the rectangle. This +means that the corner can be a sensible size relative to the size of +the rectangle, and also avoids the strange effects X produces when the +corners are too big for the rectangle. @@ -9929,6 +10764,11 @@ if wx.Platform == "__WXMSW__": DrawCircle(self, int x, int y, int radius) + Draws a circle with the given center point and radius. The current +pen is used for the outline and the current brush for filling the +shape. + +:see: `DrawEllipse` @@ -9937,6 +10777,11 @@ if wx.Platform == "__WXMSW__": DrawCirclePoint(self, Point pt, int radius) + Draws a circle with the given center point and radius. The current +pen is used for the outline and the current brush for filling the +shape. + +:see: `DrawEllipse` @@ -9944,6 +10789,10 @@ if wx.Platform == "__WXMSW__": DrawEllipse(self, int x, int y, int width, int height) + Draws an ellipse contained in the specified rectangle. The current pen +is used for the outline and the current brush for filling the shape. + +:see: `DrawCircle` @@ -9953,12 +10802,20 @@ if wx.Platform == "__WXMSW__": DrawEllipseRect(self, Rect rect) + Draws an ellipse contained in the specified rectangle. The current pen +is used for the outline and the current brush for filling the shape. + +:see: `DrawCircle` DrawEllipsePointSize(self, Point pt, Size sz) + Draws an ellipse contained in the specified rectangle. The current pen +is used for the outline and the current brush for filling the shape. + +:see: `DrawCircle` @@ -9966,6 +10823,9 @@ if wx.Platform == "__WXMSW__": DrawIcon(self, Icon icon, int x, int y) + Draw an icon on the display (does nothing if the device context is +PostScript). This can be the simplest way of drawing bitmaps on a +window. @@ -9974,6 +10834,9 @@ if wx.Platform == "__WXMSW__": DrawIconPoint(self, Icon icon, Point pt) + Draw an icon on the display (does nothing if the device context is +PostScript). This can be the simplest way of drawing bitmaps on a +window. @@ -9981,6 +10844,17 @@ if wx.Platform == "__WXMSW__": DrawBitmap(self, Bitmap bmp, int x, int y, bool useMask=False) + Draw a bitmap on the device context at the specified point. If +*transparent* is true and the bitmap has a transparency mask, (or +alpha channel on the platforms that support it) then the bitmap will +be drawn transparently. + +When drawing a mono-bitmap, the current text foreground colour will be +used to draw the foreground of the bitmap (all bits set to 1), and the +current text background colour to draw the background (all bits set to +0). + +:see: `SetTextForeground`, `SetTextBackground` and `wx.MemoryDC` @@ -9990,6 +10864,17 @@ if wx.Platform == "__WXMSW__": DrawBitmapPoint(self, Bitmap bmp, Point pt, bool useMask=False) + Draw a bitmap on the device context at the specified point. If +*transparent* is true and the bitmap has a transparency mask, (or +alpha channel on the platforms that support it) then the bitmap will +be drawn transparently. + +When drawing a mono-bitmap, the current text foreground colour will be +used to draw the foreground of the bitmap (all bits set to 1), and the +current text background colour to draw the background (all bits set to +0). + +:see: `SetTextForeground`, `SetTextBackground` and `wx.MemoryDC` @@ -9998,6 +10883,18 @@ if wx.Platform == "__WXMSW__": DrawText(self, String text, int x, int y) + Draws a text string at the specified point, using the current text +font, and the current text foreground and background colours. + +The coordinates refer to the top-left corner of the rectangle bounding +the string. See `GetTextExtent` for how to get the dimensions of a +text string, which can be used to position the text more precisely. + +**NOTE**: under wxGTK the current logical function is used by this +function but it is ignored by wxMSW. Thus, you should avoid using +logical functions with this function in portable programs. + +:see: `DrawRotatedText` @@ -10006,6 +10903,18 @@ if wx.Platform == "__WXMSW__": DrawTextPoint(self, String text, Point pt) + Draws a text string at the specified point, using the current text +font, and the current text foreground and background colours. + +The coordinates refer to the top-left corner of the rectangle bounding +the string. See `GetTextExtent` for how to get the dimensions of a +text string, which can be used to position the text more precisely. + +**NOTE**: under wxGTK the current logical function is used by this +function but it is ignored by wxMSW. Thus, you should avoid using +logical functions with this function in portable programs. + +:see: `DrawRotatedText` @@ -10013,6 +10922,14 @@ if wx.Platform == "__WXMSW__": DrawRotatedText(self, String text, int x, int y, double angle) + Draws the text rotated by *angle* degrees, if supported by the platform. + +**NOTE**: Under Win9x only TrueType fonts can be drawn by this +function. In particular, a font different from ``wx.NORMAL_FONT`` +should be used as the it is not normally a TrueType +font. ``wx.SWISS_FONT`` is an example of a font which is. + +:see: `DrawText` @@ -10022,6 +10939,14 @@ if wx.Platform == "__WXMSW__": DrawRotatedTextPoint(self, String text, Point pt, double angle) + Draws the text rotated by *angle* degrees, if supported by the platform. + +**NOTE**: Under Win9x only TrueType fonts can be drawn by this +function. In particular, a font different from ``wx.NORMAL_FONT`` +should be used as the it is not normally a TrueType +font. ``wx.SWISS_FONT`` is an example of a font which is. + +:see: `DrawText` @@ -10032,6 +10957,27 @@ if wx.Platform == "__WXMSW__": Blit(self, int xdest, int ydest, int width, int height, DC source, int xsrc, int ysrc, int rop=COPY, bool useMask=False, int xsrcMask=-1, int ysrcMask=-1) -> bool + Copy from a source DC to this DC. Parameters specify the destination +coordinates, size of area to copy, source DC, source coordinates, +logical function, whether to use a bitmap mask, and mask source +position. + + :param xdest: Destination device context x position. + :param ydest: Destination device context y position. + :param width: Width of source area to be copied. + :param height: Height of source area to be copied. + :param source: Source device context. + :param xsrc: Source device context x position. + :param ysrc: Source device context y position. + :param rop: Logical function to use: see `SetLogicalFunction`. + :param useMask: If true, Blit does a transparent blit using the mask + that is associated with the bitmap selected into the + source device context. + :param xsrcMask: Source x position on the mask. If both xsrcMask and + ysrcMask are -1, xsrc and ysrc will be assumed for + the mask source position. + :param ysrcMask: Source y position on the mask. + @@ -10049,6 +10995,21 @@ if wx.Platform == "__WXMSW__": BlitPointSize(self, Point destPt, Size sz, DC source, Point srcPt, int rop=COPY, bool useMask=False, Point srcPtMask=DefaultPosition) -> bool + Copy from a source DC to this DC. Parameters specify the destination +coordinates, size of area to copy, source DC, source coordinates, +logical function, whether to use a bitmap mask, and mask source +position. + + :param destPt: Destination device context position. + :param sz: Size of source area to be copied. + :param source: Source device context. + :param srcPt: Source device context position. + :param rop: Logical function to use: see `SetLogicalFunction`. + :param useMask: If true, Blit does a transparent blit using the mask + that is associated with the bitmap selected into the + source device context. + :param srcPtMask: Source position on the mask. + @@ -10061,6 +11022,18 @@ if wx.Platform == "__WXMSW__": SetClippingRegion(self, int x, int y, int width, int height) + Sets the clipping region for this device context to the intersection +of the given region described by the parameters of this method and the +previously set clipping region. You should call `DestroyClippingRegion` +if you want to set the clipping region exactly to the region +specified. + +The clipping region is an area to which drawing is +restricted. Possible uses for the clipping region are for clipping +text or for speeding up window redraws when only a known area of the +screen is damaged. + +:see: `DestroyClippingRegion`, `wx.Region` @@ -10070,6 +11043,18 @@ if wx.Platform == "__WXMSW__": SetClippingRegionPointSize(self, Point pt, Size sz) + Sets the clipping region for this device context to the intersection +of the given region described by the parameters of this method and the +previously set clipping region. You should call `DestroyClippingRegion` +if you want to set the clipping region exactly to the region +specified. + +The clipping region is an area to which drawing is +restricted. Possible uses for the clipping region are for clipping +text or for speeding up window redraws when only a known area of the +screen is damaged. + +:see: `DestroyClippingRegion`, `wx.Region` @@ -10077,18 +11062,45 @@ if wx.Platform == "__WXMSW__": SetClippingRegionAsRegion(self, Region region) + Sets the clipping region for this device context to the intersection +of the given region described by the parameters of this method and the +previously set clipping region. You should call `DestroyClippingRegion` +if you want to set the clipping region exactly to the region +specified. + +The clipping region is an area to which drawing is +restricted. Possible uses for the clipping region are for clipping +text or for speeding up window redraws when only a known area of the +screen is damaged. + +:see: `DestroyClippingRegion`, `wx.Region` SetClippingRect(self, Rect rect) + Sets the clipping region for this device context to the intersection +of the given region described by the parameters of this method and the +previously set clipping region. You should call `DestroyClippingRegion` +if you want to set the clipping region exactly to the region +specified. + +The clipping region is an area to which drawing is +restricted. Possible uses for the clipping region are for clipping +text or for speeding up window redraws when only a known area of the +screen is damaged. + +:see: `DestroyClippingRegion`, `wx.Region` - DrawLines(self, int points, Point points_array, int xoffset=0, int yoffset=0) + DrawLines(self, List points, int xoffset=0, int yoffset=0) + Draws lines using a sequence of `wx.Point` objects, adding the +optional offset coordinate. The current pen is used for drawing the +lines. @@ -10097,8 +11109,16 @@ if wx.Platform == "__WXMSW__": - DrawPolygon(self, int points, Point points_array, int xoffset=0, int yoffset=0, + DrawPolygon(self, List points, int xoffset=0, int yoffset=0, int fillStyle=ODDEVEN_RULE) + Draws a filled polygon using a sequence of `wx.Point` objects, adding +the optional offset coordinate. The last argument specifies the fill +rule: ``wx.ODDEVEN_RULE`` (the default) or ``wx.WINDING_RULE``. + +The current pen is used for drawing the outline, and the current brush +for filling the shape. Using a transparent brush suppresses +filling. Note that wxWidgets automatically closes the first and last +points. @@ -10110,6 +11130,11 @@ if wx.Platform == "__WXMSW__": DrawLabel(self, String text, Rect rect, int alignment=wxALIGN_LEFT|wxALIGN_TOP, int indexAccel=-1) + Draw *text* within the specified rectangle, abiding by the alignment +flags. Will additionally emphasize the character at *indexAccel* if +it is not -1. + +:see: `DrawImageLabel` @@ -10120,6 +11145,10 @@ if wx.Platform == "__WXMSW__": DrawImageLabel(self, String text, Bitmap image, Rect rect, int alignment=wxALIGN_LEFT|wxALIGN_TOP, int indexAccel=-1) -> Rect + Draw *text* and an image (which may be ``wx.NullBitmap`` to skip +drawing it) within the specified rectangle, abiding by the alignment +flags. Will additionally emphasize the character at *indexAccel* if +it is not -1. Returns the bounding rectangle. @@ -10129,7 +11158,10 @@ if wx.Platform == "__WXMSW__": - DrawSpline(self, int points, Point points_array) + DrawSpline(self, List points) + Draws a spline between all given control points, (a list of `wx.Point` +objects) using the current pen. The spline is drawn using a series of +lines, using an algorithm taken from the X drawing program 'XFIG'. @@ -10137,63 +11169,101 @@ if wx.Platform == "__WXMSW__": Clear(self) + Clears the device context using the current background brush. StartDoc(self, String message) -> bool + Starts a document (only relevant when outputting to a +printer). *Message* is a message to show whilst printing. EndDoc(self) + Ends a document (only relevant when outputting to a printer). StartPage(self) + Starts a document page (only relevant when outputting to a printer). EndPage(self) + Ends a document page (only relevant when outputting to a printer). SetFont(self, Font font) + Sets the current font for the DC. It must be a valid font, in +particular you should not pass ``wx.NullFont`` to this method. + +:see: `wx.Font` SetPen(self, Pen pen) + Sets the current pen for the DC. + +If the argument is ``wx.NullPen``, the current pen is selected out of the +device context, and the original pen restored. + +:see: `wx.Pen` SetBrush(self, Brush brush) + Sets the current brush for the DC. + +If the argument is ``wx.NullBrush``, the current brush is selected out +of the device context, and the original brush restored, allowing the +current brush to be destroyed safely. + +:see: `wx.Brush` SetBackground(self, Brush brush) + Sets the current background brush for the DC. SetBackgroundMode(self, int mode) + *mode* may be one of ``wx.SOLID`` and ``wx.TRANSPARENT``. This setting +determines whether text will be drawn with a background colour or +not. SetPalette(self, Palette palette) + If this is a window DC or memory DC, assigns the given palette to the +window or bitmap associated with the DC. If the argument is +``wx.NullPalette``, the current palette is selected out of the device +context, and the original palette restored. + +:see: `wx.Palette` DestroyClippingRegion(self) + Destroys the current clipping region so that none of the DC is +clipped. + +:see: `SetClippingRegion` GetClippingBox() -> (x, y, width, height) + Gets the rectangle surrounding the current clipping region. @@ -10203,15 +11273,20 @@ if wx.Platform == "__WXMSW__": GetClippingRect(self) -> Rect + Gets the rectangle surrounding the current clipping region. GetCharHeight(self) -> int + Gets the character height of the currently set font. GetCharWidth(self) -> int + Gets the average character width of the currently set font. GetTextExtent(wxString string) -> (width, height) + Get the width and height of the text using the current font. Only +works for single line strings. @@ -10235,6 +11310,9 @@ current or specified font. Only works for single line strings. GetMultiLineTextExtent(wxString string, Font font=None) -> (width, height, descent, externalLeading) + Get the width, height, decent and leading of the text using the +current or specified font. Works for single as well as multi-line +strings. @@ -10244,18 +11322,44 @@ current or specified font. Only works for single line strings. - GetPartialTextExtents(self, String text) -> wxArrayInt + GetPartialTextExtents(self, text) -> [widths] + Returns a list of integers such that each value is the distance in +pixels from the begining of text to the coresponding character of +*text*. The generic version simply builds a running total of the widths +of each character using GetTextExtent, however if the various +platforms have a native API function that is faster or more accurate +than the generic implementaiton then it will be used instead. GetSize(self) -> Size - Get the DC size in device units. + This gets the horizontal and vertical resolution in device units. It +can be used to scale graphics to fit the page. For example, if *maxX* +and *maxY* represent the maximum horizontal and vertical 'pixel' values +used in your application, the following code will scale the graphic to +fit on the printer page:: + + w, h = dc.GetSize() + scaleX = maxX*1.0 / w + scaleY = maxY*1.0 / h + dc.SetUserScale(min(scaleX,scaleY),min(scaleX,scaleY)) + GetSizeTuple() -> (width, height) - Get the DC size in device units. + This gets the horizontal and vertical resolution in device units. It +can be used to scale graphics to fit the page. For example, if *maxX* +and *maxY* represent the maximum horizontal and vertical 'pixel' values +used in your application, the following code will scale the graphic to +fit on the printer page:: + + w, h = dc.GetSize() + scaleX = maxX*1.0 / w + scaleY = maxY*1.0 / h + dc.SetUserScale(min(scaleX,scaleY),min(scaleX,scaleY)) + @@ -10275,48 +11379,68 @@ current or specified font. Only works for single line strings. DeviceToLogicalX(self, int x) -> int + Convert device X coordinate to logical coordinate, using the current +mapping mode. DeviceToLogicalY(self, int y) -> int + Converts device Y coordinate to logical coordinate, using the current +mapping mode. DeviceToLogicalXRel(self, int x) -> int + Convert device X coordinate to relative logical coordinate, using the +current mapping mode but ignoring the x axis orientation. Use this +function for converting a width, for example. DeviceToLogicalYRel(self, int y) -> int + Convert device Y coordinate to relative logical coordinate, using the +current mapping mode but ignoring the y axis orientation. Use this +function for converting a height, for example. LogicalToDeviceX(self, int x) -> int + Converts logical X coordinate to device coordinate, using the current +mapping mode. LogicalToDeviceY(self, int y) -> int + Converts logical Y coordinate to device coordinate, using the current +mapping mode. LogicalToDeviceXRel(self, int x) -> int + Converts logical X coordinate to relative device coordinate, using the +current mapping mode but ignoring the x axis orientation. Use this for +converting a width, for example. LogicalToDeviceYRel(self, int y) -> int + Converts logical Y coordinate to relative device coordinate, using the +current mapping mode but ignoring the y axis orientation. Use this for +converting a height, for example. @@ -10329,57 +11453,101 @@ current or specified font. Only works for single line strings. GetDepth(self) -> int + Returns the colour depth of the DC. GetPPI(self) -> Size + Resolution in Pixels per inch Ok(self) -> bool + Returns true if the DC is ok to use. GetBackgroundMode(self) -> int + Returns the current background mode, either ``wx.SOLID`` or +``wx.TRANSPARENT``. + +:see: `SetBackgroundMode` GetBackground(self) -> Brush + Gets the brush used for painting the background. + +:see: `SetBackground` GetBrush(self) -> Brush + Gets the current brush GetFont(self) -> Font + Gets the current font GetPen(self) -> Pen + Gets the current pen GetTextBackground(self) -> Colour + Gets the current text background colour GetTextForeground(self) -> Colour + Gets the current text foreground colour SetTextForeground(self, Colour colour) + Sets the current text foreground colour for the DC. SetTextBackground(self, Colour colour) + Sets the current text background colour for the DC. GetMapMode(self) -> int + Gets the current *mapping mode* for the device context SetMapMode(self, int mode) + The *mapping mode* of the device context defines the unit of +measurement used to convert logical units to device units. The +mapping mode can be one of the following: + + ================ ============================================= + wx.MM_TWIPS Each logical unit is 1/20 of a point, or 1/1440 + of an inch. + wx.MM_POINTS Each logical unit is a point, or 1/72 of an inch. + wx.MM_METRIC Each logical unit is 1 mm. + wx.MM_LOMETRIC Each logical unit is 1/10 of a mm. + wx.MM_TEXT Each logical unit is 1 pixel. + ================ ============================================= + +Note that in X, text drawing isn't handled consistently with the +mapping mode; a font is always specified in point size. However, +setting the user scale (see `SetUserScale`) scales the text +appropriately. In Windows, scalable TrueType fonts are always used; in +X, results depend on availability of fonts, but usually a reasonable +match is found. + +The coordinate origin is always at the top left of the screen/printer. + +Drawing to a Windows printer device context uses the current mapping +mode, but mapping mode is currently ignored for PostScript output. + - GetUserScale() -> (xScale, yScale) + GetUserScale(self) -> (xScale, yScale) + Gets the current user scale factor (set by `SetUserScale`). @@ -10387,6 +11555,8 @@ current or specified font. Only works for single line strings. SetUserScale(self, double x, double y) + Sets the user scaling factor, useful for applications which require +'zooming'. @@ -10454,6 +11624,9 @@ current or specified font. Only works for single line strings. SetAxisOrientation(self, bool xLeftRight, bool yBottomUp) + Sets the x and y axis orientation (i.e., the direction from lowest to +highest values on the axis). The default orientation is the natural +orientation, e.g. x axis from left to right and y axis from bottom up. @@ -10461,24 +11634,72 @@ current or specified font. Only works for single line strings. GetLogicalFunction(self) -> int + Gets the current logical function (set by `SetLogicalFunction`). SetLogicalFunction(self, int function) + Sets the current logical function for the device context. This +determines how a source pixel (from a pen or brush colour, or source +device context if using `Blit`) combines with a destination pixel in +the current device context. + +The possible values and their meaning in terms of source and +destination pixel values are as follows: + + ================ ========================== + wx.AND src AND dst + wx.AND_INVERT (NOT src) AND dst + wx.AND_REVERSE src AND (NOT dst) + wx.CLEAR 0 + wx.COPY src + wx.EQUIV (NOT src) XOR dst + wx.INVERT NOT dst + wx.NAND (NOT src) OR (NOT dst) + wx.NOR (NOT src) AND (NOT dst) + wx.NO_OP dst + wx.OR src OR dst + wx.OR_INVERT (NOT src) OR dst + wx.OR_REVERSE src OR (NOT dst) + wx.SET 1 + wx.SRC_INVERT NOT src + wx.XOR src XOR dst + ================ ========================== + +The default is wx.COPY, which simply draws with the current +colour. The others combine the current colour and the background using +a logical operation. wx.INVERT is commonly used for drawing rubber +bands or moving outlines, since drawing twice reverts to the original +colour. + - SetOptimization(self, bool opt) + SetOptimization(self, bool optimize) + If *optimize* is true this function sets optimization mode on. This +currently means that under X, the device context will not try to set a +pen or brush property if it is known to be set already. This approach +can fall down if non-wxWidgets code is using the same device context +or window, for example when the window is a panel on which the +windowing system draws panel items. The wxWidgets device context +'memory' will now be out of step with reality. + +Setting optimization off, drawing, then setting it back on again, is a +trick that must occasionally be employed. - + GetOptimization(self) -> bool + Returns true if device context optimization is on. See +`SetOptimization` for . CalcBoundingBox(self, int x, int y) + Adds the specified point to the bounding box which can be retrieved +with `MinX`, `MaxX` and `MinY`, `MaxY` or `GetBoundingBox` functions. @@ -10486,27 +11707,36 @@ current or specified font. Only works for single line strings. CalcBoundingBoxPoint(self, Point point) + Adds the specified point to the bounding box which can be retrieved +with `MinX`, `MaxX` and `MinY`, `MaxY` or `GetBoundingBox` functions. ResetBoundingBox(self) + Resets the bounding box: after a call to this function, the bounding +box doesn't contain anything. MinX(self) -> int + Gets the minimum horizontal extent used in drawing commands so far. MaxX(self) -> int + Gets the maximum horizontal extent used in drawing commands so far. MinY(self) -> int + Gets the minimum vertical extent used in drawing commands so far. MaxY(self) -> int + Gets the maximum vertical extent used in drawing commands so far. GetBoundingBox() -> (x1,y1, x2,y2) + Returns the min and max points used in drawing commands so far. @@ -10569,18 +11799,48 @@ current or specified font. Only works for single line strings. #--------------------------------------------------------------------------- + A memory device context provides a means to draw graphics onto a +bitmap. A bitmap must be selected into the new memory DC before it may +be used for anything. Typical usage is as follows:: + + dc = wx.MemoryDC() + dc.SelectObject(bitmap) + # draw on the dc usign any of the Draw methods + dc.SelectObject(wx.NullBitmap) + # the bitmap now contains wahtever was drawn upon it + +Note that the memory DC *must* be deleted (or the bitmap selected out +of it) before a bitmap can be reselected into another memory DC. + __init__(self) -> MemoryDC + Constructs a new memory device context. + +Use the Ok member to test whether the constructor was successful in +creating a usable device context. Don't forget to select a bitmap into +the DC before drawing on it. + +:see: `MemoryDCFromDC` MemoryDCFromDC(DC oldDC) -> MemoryDC + Creates a DC that is compatible with the oldDC. SelectObject(self, Bitmap bitmap) + Selects the bitmap into the device context, to use as the memory +bitmap. Selecting the bitmap into a memory DC allows you to draw into +the DC, and therefore the bitmap, and also to use Blit to copy the +bitmap to a window. + +If the argument is wx.NullBitmap (or some other uninitialised +`wx.Bitmap`) the current bitmap is selected out of the device context, +and the original bitmap restored, allowing the current bitmap to be +destroyed safely. @@ -10590,8 +11850,35 @@ current or specified font. Only works for single line strings. #--------------------------------------------------------------------------- + This simple class provides a simple way to avoid flicker: when drawing +on it, everything is in fact first drawn on an in-memory buffer (a +`wx.Bitmap`) and then copied to the screen only once, when this object +is destroyed. + +It can be used in the same way as any other device +context. wx.BufferedDC itself typically replaces `wx.ClientDC`, if you +want to use it in your EVT_PAINT handler, you should look at +`wx.BufferedPaintDC`. + + Constructs a buffered DC. + + :param dc: The underlying DC: everything drawn to this object will + be flushed to this DC when this object is destroyed. You may + pass ``None`` in order to just initialize the buffer, and not + flush it. + + :param buffer: If a `wx.Size` object is passed as the 2nd arg then + it is the size of the bitmap that will be created internally + and used for an implicit buffer. If the 2nd arg is a + `wx.Bitmap` then it is the explicit buffer that will be + used. Using an explicit buffer is the most efficient solution + as the bitmap doesn't have to be recreated each time but it + also requires more memory as the bitmap is never freed. The + bitmap should have appropriate size, anything drawn outside of + its bounds is clipped. + @@ -10600,13 +11887,23 @@ current or specified font. Only works for single line strings. __init__(self, DC dc, Bitmap buffer) -> BufferedDC __init__(self, DC dc, Size area) -> BufferedDC - - - - - - - BufferedDCInternalBuffer(DC dc, Size area) -> BufferedDC + Constructs a buffered DC. + + :param dc: The underlying DC: everything drawn to this object will + be flushed to this DC when this object is destroyed. You may + pass ``None`` in order to just initialize the buffer, and not + flush it. + + :param buffer: If a `wx.Size` object is passed as the 2nd arg then + it is the size of the bitmap that will be created internally + and used for an implicit buffer. If the 2nd arg is a + `wx.Bitmap` then it is the explicit buffer that will be + used. Using an explicit buffer is the most efficient solution + as the bitmap doesn't have to be recreated each time but it + also requires more memory as the bitmap is never freed. The + bitmap should have appropriate size, anything drawn outside of + its bounds is clipped. + @@ -10614,15 +11911,44 @@ __init__(self, DC dc, Size area) -> BufferedDC __del__(self) + Copies everything drawn on the DC so far to the underlying DC +associated with this object, if any. UnMask(self) + Blits the buffer to the dc, and detaches the dc from the buffer (so it +can be effectively used once only). This is usually only called in +the destructor. + This is a subclass of `wx.BufferedDC` which can be used inside of an +EVT_PAINT event handler. Just create an object of this class instead +of `wx.PaintDC` and that's all you have to do to (mostly) avoid +flicker. The only thing to watch out for is that if you are using this +class together with `wx.ScrolledWindow`, you probably do **not** want +to call `wx.Window.PrepareDC` on it as it already does this internally +for the real underlying `wx.PaintDC`. + +If your window is already fully buffered in a `wx.Bitmap` then your +EVT_PAINT handler can be as simple as just creating a +``wx.BufferedPaintDC`` as it will `Blit` the buffer to the window +automatically when it is destroyed. For example:: + + def OnPaint(self, event): + dc = wx.BufferedPaintDC(self, self.buffer) + + + __init__(self, Window window, Bitmap buffer=NullBitmap) -> BufferedPaintDC + Create a buffered paint DC. As with `wx.BufferedDC`, you may either +provide the bitmap to be used for buffering or let this object create +one internally (in the latter case, the size of the client part of the +window is automatically used). + + @@ -10633,33 +11959,73 @@ __init__(self, DC dc, Size area) -> BufferedDC #--------------------------------------------------------------------------- + A wxScreenDC can be used to paint anywhere on the screen. This should +normally be constructed as a temporary stack object; don't store a +wxScreenDC object. + __init__(self) -> ScreenDC + A wxScreenDC can be used to paint anywhere on the screen. This should +normally be constructed as a temporary stack object; don't store a +wxScreenDC object. + StartDrawingOnTopWin(self, Window window) -> bool + Specify that the area of the screen to be drawn upon coincides with +the given window. + +:see: `EndDrawingOnTop` StartDrawingOnTop(self, Rect rect=None) -> bool + Specify that the area is the given rectangle, or the whole screen if +``None`` is passed. + +:see: `EndDrawingOnTop` EndDrawingOnTop(self) -> bool + Use this in conjunction with `StartDrawingOnTop` or +`StartDrawingOnTopWin` to ensure that drawing to the screen occurs on +top of existing windows. Without this, some window systems (such as X) +only allow drawing to take place underneath other windows. + +You might use this pair of functions when implementing a drag feature, +for example as in the `wx.SplitterWindow` implementation. + +These functions are probably obsolete since the X implementations +allow drawing directly on the screen now. However, the fact that this +function allows the screen to be refreshed afterwards may be useful +to some applications. #--------------------------------------------------------------------------- + A wx.ClientDC must be constructed if an application wishes to paint on +the client area of a window from outside an EVT_PAINT event. This should +normally be constructed as a temporary stack object; don't store a +wx.ClientDC object long term. + +To draw on a window from within an EVT_PAINT handler, construct a +`wx.PaintDC` object. + +To draw on the whole window including decorations, construct a +`wx.WindowDC` object (Windows only). + __init__(self, Window win) -> ClientDC + Constructor. Pass the window on which you wish to paint. @@ -10669,9 +12035,24 @@ __init__(self, DC dc, Size area) -> BufferedDC #--------------------------------------------------------------------------- + A wx.PaintDC must be constructed if an application wishes to paint on +the client area of a window from within an EVT_PAINT event +handler. This should normally be constructed as a temporary stack +object; don't store a wx.PaintDC object. If you have an EVT_PAINT +handler, you **must** create a wx.PaintDC object within it even if you +don't actually use it. + +Using wx.PaintDC within EVT_PAINT handlers is important because it +automatically sets the clipping area to the damaged area of the +window. Attempts to draw outside this area do not appear. + +To draw on a window from outside EVT_PAINT handlers, construct a +`wx.ClientDC` object. + __init__(self, Window win) -> PaintDC + Constructor. Pass the window on which you wish to paint. @@ -10681,9 +12062,14 @@ __init__(self, DC dc, Size area) -> BufferedDC #--------------------------------------------------------------------------- + A wx.WindowDC must be constructed if an application wishes to paint on +the whole area of a window (client and decorations). This should +normally be constructed as a temporary stack object; don't store a +wx.WindowDC object. __init__(self, Window win) -> WindowDC + Constructor. Pass the window on which you wish to paint. @@ -10693,9 +12079,18 @@ __init__(self, DC dc, Size area) -> BufferedDC #--------------------------------------------------------------------------- + wx.MirrorDC is a simple wrapper class which is always associated with a +real `wx.DC` object and either forwards all of its operations to it +without changes (no mirroring takes place) or exchanges x and y +coordinates which makes it possible to reuse the same code to draw a +figure and its mirror -- i.e. reflection related to the diagonal line +x == y. __init__(self, DC dc, bool mirror) -> MirrorDC + Creates a mirrored DC associated with the real *dc*. Everything drawn +on the wx.MirrorDC will appear on the *dc*, and will be mirrored if +*mirror* is True. @@ -10706,9 +12101,12 @@ __init__(self, DC dc, Size area) -> BufferedDC #--------------------------------------------------------------------------- + This is a `wx.DC` that can write to PostScript files on any platform. __init__(self, wxPrintData printData) -> PostScriptDC + Constructs a PostScript printer device context from a `wx.PrintData` +object. @@ -10724,12 +12122,15 @@ __init__(self, DC dc, Size area) -> BufferedDC SetResolution(int ppi) + Set resolution (in pixels per inch) that will be used in PostScript +output. Default is 720ppi. GetResolution() -> int + Return resolution used in PostScript output. @@ -11187,6 +12588,7 @@ this. GetScrollPixelsPerUnit() -> (xUnit, yUnit) + Get the size of one logical unit in physical units. @@ -11201,6 +12603,7 @@ this. GetViewStart() -> (x,y) + Get the view start @@ -11271,6 +12674,13 @@ CalcUnscrolledPosition(int x, int y) -> (ux, uy) GetTargetWindow(self) -> Window + + DoPrepareDC(self, DC dc) + Normally what is called by `PrepareDC`. + + + + GetClassDefaultAttributes(int variant=WINDOW_VARIANT_NORMAL) -> VisualAttributes Get the default attributes for this class. This is useful if you want @@ -11765,6 +13175,13 @@ this. + + SetStatusStyles(self, int styles, int styles_field) + + + + + GetFieldRect(self, int i) -> Rect @@ -11806,7 +13223,56 @@ this. wx.SplitterWindow manages up to two subwindows or panes, with an optional vertical or horizontal split which can be used with the mouse -or programmatically. +or programmatically. + +Styles +------- + ==================== ====================================== + wx.SP_3D Draws a 3D effect border and sash. + wx.SP_3DSASH Draws a 3D effect sash. + wx.SP_3DBORDER Synonym for wxSP_BORDER. + wx.SP_BORDER Draws a standard border. + wx.SP_NOBORDER No border (default). + wx.SP_NO_XP_THEME Under Windows XP, switches off the + attempt to draw the splitter + using Windows XP theming, so the + borders and sash will take on the + pre-XP look. + wx.SP_PERMIT_UNSPLIT Always allow to unsplit, even with + the minimum pane size other than zero. + wx.SP_LIVE_UPDATE Don't draw XOR line but resize the + child windows immediately. + ==================== ====================================== + +Events +------ + ============================== ======================================= + EVT_SPLITTER_SASH_POS_CHANGING The sash position is in the + process of being changed. May be + used to modify the position of + the tracking bar to properly + reflect the position that would + be set if the drag were to be + completed at this point. + + EVT_SPLITTER_SASH_POS_CHANGED + The sash position was + changed. May be used to modify + the sash position before it is + set, or to prevent the change + from taking place. + + EVT_SPLITTER_UNSPLIT The splitter has been just unsplit. + + EVT_SPLITTER_DCLICK The sash was double clicked. The + default behaviour is to unsplit + the window when this happens + (unless the minimum pane size has + been set to a value greater than + zero.) + ============================== ======================================= + + __init__(self, Window parent, int id=-1, Point pos=DefaultPosition, @@ -11870,7 +13336,24 @@ splitter window. SplitVertically(self, Window window1, Window window2, int sashPosition=0) -> bool - Initializes the left and right panes of the splitter window. + Initializes the left and right panes of the splitter window. + :param window1: The left pane. + :param window2: The right pane. + :param sashPosition: The initial position of the sash. If this + value is positive, it specifies the size of the left + pane. If it is negative, it is absolute value gives + the size of the right pane. Finally, specify 0 + (default) to choose the default position (half of + the total window width). + +Returns True if successful, False otherwise (the window was already +split). + +SplitVertically should be called if you wish to initially view two +panes. It can also be called at any subsequent time, but the +application should check that the window is not currently split using +IsSplit. + @@ -11879,7 +13362,24 @@ splitter window. SplitHorizontally(self, Window window1, Window window2, int sashPosition=0) -> bool - Initializes the top and bottom panes of the splitter window. + Initializes the top and bottom panes of the splitter window. + :param window1: The top pane. + :param window2: The bottom pane. + :param sashPosition: The initial position of the sash. If this + value is positive, it specifies the size of the + upper pane. If it is negative, it is absolute value + gives the size of the lower pane. Finally, specify 0 + (default) to choose the default position (half of + the total window height). + +Returns True if successful, False otherwise (the window was already +split). + +SplitHorizontally should be called if you wish to initially view two +panes. It can also be called at any subsequent time, but the +application should check that the window is not currently split using +IsSplit. + @@ -12563,10 +14063,6 @@ EVT_SPLITTER_DCLICK = EVT_SPLITTER_DOUBLECLICKED ScrollLines(self, int lines) -> bool - 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. @@ -12594,8 +14090,8 @@ already on top/bottom and nothing was done. - - HitTestXT(self, int x, int y) -> int + + HitTestXY(self, int x, int y) -> int Test where the given (in client coords) point lies @@ -12951,7 +14447,17 @@ instance. wx.DirDialog allows the user to select a directory by browising the -file system. +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. + ==================== ========================================== + __init__(self, Window parent, String message=DirSelectorPromptStr, @@ -12998,7 +14504,46 @@ file system. wx.FileDialog allows the user to select one or more files from the -filesystem. +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" + + +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.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.CHANGE_DIR Change the current working directory to the + directory where the file(s) chosen by the user + are. + =================== ========================================== + __init__(self, Window parent, String message=FileSelectorPromptStr, @@ -13134,6 +14679,8 @@ style, use GetPath for the others. SetSelections(List selections) + Specify the items in the list that should be selected, using a list of +integers. @@ -13331,7 +14878,27 @@ wx.FontDialog. 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. +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). + =================== ============================================= + __init__(self, Window parent, String message, String caption=MessageBoxCaptionStr, @@ -13349,7 +14916,35 @@ message, with a choice of OK, Yes, No and/or Cancel buttons. A dialog that shows a short message and a progress bar. Optionally, it -can display an ABORT button. +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. + ==================== ============================================= + __init__(self, String title, String message, int maximum=100, Window parent=None, @@ -13368,8 +14963,10 @@ parent window only. Update(self, int value, String newmsg=EmptyString) -> bool 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. +given changes the message above it. The value given should be less +than or equal to the maximum value given to the constructor and the +dialog is closed if it is equal to the maximum. 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 @@ -13455,7 +15052,20 @@ 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. +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) + ================ =============================================== + __init__(self, int flags=0) -> FindReplaceData @@ -13508,7 +15118,22 @@ 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. +way; it is always, by design and implementation, modeless. + + +Window Styles +------------- + + ===================== ========================================= + wx.FR_REPLACEDIALOG replace dialog (otherwise find dialog) + + wx.FR_NOUPDOWN don't allow changing the search direction + + wx.FR_NOMATCHCASE don't allow case sensitive searching + + wx.FR_NOWHOLEWORD don't allow whole word searching + ===================== ========================================= + __init__(self, Window parent, FindReplaceData data, String title, @@ -15188,7 +16813,30 @@ __init__(self, Printout printout, Printout printoutForPrinting, PrintData data) 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. +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` + __init__(self, Window parent, int id=-1, String label=EmptyString, @@ -15257,7 +16905,36 @@ this. A Button that contains a bitmap. A bitmap button can be supplied with a 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. +unpressed focused state, and greyed-out state may be supplied. + +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. + =========== ================================== + +:see: `wx.Button`, `wx.Bitmap` + __init__(self, Window parent, int id=-1, Bitmap bitmap=wxNullBitmap, @@ -15364,7 +17041,32 @@ unselected state, and for all other states if no other bitmaps are provided. +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. + =============================== =============================== + __init__(self, Window parent, int id=-1, String label=EmptyString, @@ -15472,7 +17174,14 @@ this. 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. +user pulls down the menu of choices. + +Events +------ + ================ ========================================== + EVT_CHOICE Sent when an item in the list is selected. + ================ ========================================== + __init__(Window parent, int id, Point pos=DefaultPosition, Size size=DefaultSize, @@ -15498,6 +17207,7 @@ user pulls down the menu of choices. 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 @@ -15557,7 +17267,32 @@ listbox. It can be displayed as static list with editable or read-only text field; or a drop-down list with text field. A combobox permits a single selection only. Combobox items are -numbered from zero. +numbered from zero. + +Styles +------ + ================ =============================================== + wx.CB_SIMPLE Creates a combobox with a permanently + displayed list. Windows only. + + wx.CB_DROPDOWN Creates a combobox with a drop-down list. + + wx.CB_READONLY Same as wxCB_DROPDOWN but only the strings + specified as the combobox choices can be + selected, it is impossible to select + (even from a program) a string which is + not in the choices list. + + wx.CB_SORT Sorts the entries in the list alphabetically. + ================ =============================================== + +Events +------- + ================ =============================================== + EVT_COMBOBOX Sent when an item on the list is selected. + EVT_TEXT Sent when the combobox text changes. + ================ =============================================== + @@ -15587,6 +17322,7 @@ numbered from zero. Point pos=DefaultPosition, Size size=DefaultSize, List choices=[], long style=0, Validator validator=DefaultValidator, String name=ChoiceNameStr) -> bool + Actually create the GUI wxComboBox control for 2-phase creation @@ -16284,13 +18020,11 @@ this. #--------------------------------------------------------------------------- - - - __init__(self) -> TextAttr -__init__(self, Colour colText, Colour colBack=wxNullColour, Font font=wxNullFont, - int alignment=TEXT_ALIGNMENT_DEFAULT) -> TextAttr + + __init__(self, Colour colText=wxNullColour, Colour colBack=wxNullColour, + Font font=wxNullFont, int alignment=TEXT_ALIGNMENT_DEFAULT) -> TextAttr - + @@ -16500,6 +18234,7 @@ __init__(self, Colour colText, Colour colBack=wxNullColour, Font font=wxNullFont GetSelection() -> (from, to) + If the return values from and to are the same, there is no selection. @@ -16615,12 +18350,25 @@ __init__(self, Colour colText, Colour colBack=wxNullColour, Font font=wxNullFont HitTest(Point pt) -> (result, row, col) + Find the row, col coresponding to the character at the point given in +pixels. NB: pt is in device coords but is not adjusted for the client +area origin nor scrolling. + + HitTestPos(Point pt) -> (result, position) + Find the character position in the text coresponding to the point +given in pixels. NB: pt is in device coords but is not adjusted for +the client area origin nor scrolling. + + + + + Copy(self) @@ -16800,7 +18548,19 @@ EVT_TEXT_MAXLEN = wx.PyEventBinder( wxEVT_COMMAND_TEXT_MAXLEN, 1) SetScrollbar(self, int position, int thumbSize, int range, int pageSize, bool refresh=True) - Sets the scrollbar properties of a built-in scrollbar. + 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. + @@ -17680,6 +19440,8 @@ this. HitTest(Point pt) -> (tab, where) + Returns the tab which is hit, and flags indicating where using +wx.NB_HITTEST flags. @@ -18930,6 +20692,8 @@ immediately. HitTest(Point point) -> (item, where) + Determines which item (if any) is at the specified point, giving + in the second return value (see wxLIST_HITTEST_... flags.) @@ -19735,6 +21499,10 @@ EVT_TREE_ITEM_GETTOOLTIP = wx.PyEventBinder(wxEVT_COMMAND_TREE_ITEM_GETTOOLTIP HitTest(Point point) -> (item, where) + Determine which item (if any) belongs the given point. The coordinates +specified are relative to the client area of tree ctrl and the where return +value is set to a bitmask of wxTREE_HITTEST_xxx constants. + @@ -19873,6 +21641,11 @@ this. FindChild(wxTreeItemId parentId, wxString path) -> (item, done) + Find the child that matches the first part of 'path'. E.g. if a child +path is "/usr" and 'path' is "/usr/include" then the child for +/usr is returned. If the path string has been used (we're at the +leaf), done is set to True. + @@ -20086,7 +21859,18 @@ 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. +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 + ============== ========================================= + +:see: `wx.ContextHelp`, `wx.ContextHelpButton` + __init__(self, wxEventType type=wxEVT_NULL, int winid=0, Point pt=DefaultPosition) -> HelpEvent @@ -20565,12 +22349,19 @@ with the control (if any) in a tooltip. - - Usleep(unsigned long milliseconds) + + MilliSleep(unsigned long milliseconds) + + MicroSleep(unsigned long microseconds) + + + + + Usleep = MilliSleep EnableTopLevelWindows(bool enable) @@ -22248,6 +24039,68 @@ method and register the provider with wx.ArtProvider.PushProvider:: 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) __init__(self) -> ArtProvider @@ -22267,6 +24120,68 @@ method and register the provider with wx.ArtProvider.PushProvider:: 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) @@ -22820,6 +24735,7 @@ taken literally. GetAmPmStrings() -> (am, pm) + Get the AM and PM strings in the current locale (may be empty) @@ -23795,7 +25711,30 @@ handle which is used by the system for the clipboard and drag and drop operations. The applications are usually only interested in, for example, pasting data from the clipboard only if the data is in a format the program understands. A data format is is used to uniquely -identify this format. +identify this format. +On the system level, a data format is usually just a number, (which +may be the CLIPFORMAT under Windows or Atom under X11, for example.) + +The standard format IDs are: + + ================ ===================================== + wx.DF_INVALID An invalid format + wx.DF_TEXT Text format + wx.DF_BITMAP A bitmap (wx.Bitmap) + wx.DF_METAFILE A metafile (wx.Metafile, Windows only) + wx.DF_FILENAME A list of filenames + wx.DF_HTML An HTML string. This is only valid on + Windows and non-unicode builds + ================ ===================================== + +Aside the standard formats, the application may also use custom +formats which are identified by their names (strings) and not numeric +identifiers. Although internally custom format must be created (or +registered) first, you shouldn't care about it because it is done +automatically the first time the wxDataFormat object corresponding to +a given format name is created. + + __init__(self, int type) -> DataFormat Constructs a data format object for one of the standard data formats @@ -23876,6 +25815,39 @@ it supports and how to render itself in each of supported formats. directly from Python. If you need a custom type of data object then you should instead derive from `wx.PyDataObjectSimple` or use `wx.CustomDataObject`. + +Not surprisingly, being 'smart' comes at a price of added +complexity. This is reasonable for the situations when you really need +to support multiple formats, but may be annoying if you only want to +do something simple like cut and paste text. + +To provide a solution for both cases, wxWidgets has two predefined +classes which derive from wx.DataObject: `wx.DataObjectSimple` and +`wx.DataObjectComposite`. `wx.DataObjectSimple` is the simplest +wx.DataObject possible and only holds data in a single format (such as +text or bitmap) and `wx.DataObjectComposite` is the simplest way to +implement a wx.DataObject which supports multiple simultaneous formats +because it achievs this by simply holding several +`wx.DataObjectSimple` objects. + +Please note that the easiest way to use drag and drop and the +clipboard with multiple formats is by using `wx.DataObjectComposite`, +but it is not the most efficient one as each `wx.DataObjectSimple` +would contain the whole data in its respective formats. Now imagine +that you want to paste 200 pages of text in your proprietary format, +as well as Word, RTF, HTML, Unicode and plain text to the clipboard +and even today's computers are in trouble. For this case, you will +have to derive from wx.DataObject directly and make it enumerate its +formats and provide the data in the requested format on +demand. (**TODO**: This is currently not possible from Python. Make +it so.) + +Note that the platform transfer mechanisms for the clipboard and drag +and drop, do not copy any data out of the source application until +another application actually requests the data. This is in contrast to +the 'feel' offered to the user of a program who would normally think +that the data resides in the clipboard after having pressed 'Copy' - +in reality it is only declared to be available. __del__(self) @@ -23923,7 +25895,8 @@ in the given direction. GetDataHere(self, DataFormat format) -> String Get the data bytes in the specified format, returns None on failure. - + +:todo: This should use the python buffer interface isntead... @@ -23931,7 +25904,8 @@ in the given direction. SetData(self, DataFormat format, String data) -> bool Set the data in the specified format from the bytes in the the data string. - + +:todo: This should use the python buffer interface isntead... @@ -23993,6 +25967,29 @@ Python-aware and knows how to reflect calls to its C++ virtual methods to methods in the Python derived class. You should derive from this class and overload `GetDataSize`, `GetDataHere` and `SetData` when you need to create your own simple single-format type of `wx.DataObject`. + +Here is a simple example:: + + class MyDataObject(wx.PyDataObjectSimple): + def __init__(self): + wx.PyDataObjectSimple.__init__( + self, wx.CustomDataFormat('MyDOFormat')) + self.data = '' + + def GetDataSize(self): + return len(self.data) + def GetDataHere(self): + return self.data # returns a string + def SetData(self, data): + self.data = data + return True + +Note that there is already a `wx.CustomDataObject` class that behaves +very similarly to this example. The value of creating your own +derived class like this is to be able to do additional things when the +data is requested or given via the clipboard or drag and drop +operation, such as generate the data value or decode it into needed +data structures. @@ -24002,6 +25999,29 @@ Python-aware and knows how to reflect calls to its C++ virtual methods to methods in the Python derived class. You should derive from this class and overload `GetDataSize`, `GetDataHere` and `SetData` when you need to create your own simple single-format type of `wx.DataObject`. + +Here is a simple example:: + + class MyDataObject(wx.PyDataObjectSimple): + def __init__(self): + wx.PyDataObjectSimple.__init__( + self, wx.CustomDataFormat('MyDOFormat')) + self.data = '' + + def GetDataSize(self): + return len(self.data) + def GetDataHere(self): + return self.data # returns a string + def SetData(self, data): + self.data = data + return True + +Note that there is already a `wx.CustomDataObject` class that behaves +very similarly to this example. The value of creating your own +derived class like this is to be able to do additional things when the +data is requested or given via the clipboard or drag and drop +operation, such as generate the data value or decode it into needed +data structures. @@ -24131,7 +26151,8 @@ into the data object. wx.BitmapDataObject is a specialization of wxDataObject for bitmap data. It can be used without change to paste data into the `wx.Clipboard` or a `wx.DropSource`. - + +:see: `wx.PyBitmapDataObject` if you wish to override `GetBitmap` to increase efficiency. __init__(self, Bitmap bitmap=wxNullBitmap) -> BitmapDataObject @@ -24202,6 +26223,7 @@ them using this class. GetFilenames(self) -> [names] + Returns a list of file names. AddFile(self, String filename) @@ -24582,7 +26604,29 @@ normal clipboard, if primary is True. + + Get() -> Clipboard + Returns global instance (wxTheClipboard) of the object. + + + class _wxPyDelayedInitWrapper(object): + def __init__(self, initfunc, *args, **kwargs): + self._initfunc = initfunc + self._args = args + self._kwargs = kwargs + self._instance = None + def _checkInstance(self): + if self._instance is None: + self._instance = self._initfunc(*self._args, **self._kwargs) + def __getattr__(self, name): + self._checkInstance() + return getattr(self._instance, name) + def __repr__(self): + self._checkInstance() + return repr(self._instance) + TheClipboard = _wxPyDelayedInitWrapper(Clipboard.Get) + A helpful class for opening the clipboard and automatically closing it when the locker is destroyed. @@ -24736,7 +26780,22 @@ function is not supported at all on this platform. ChangeMode(self, VideoMode mode=DefaultVideoMode) -> bool - Change current mode, return true if succeeded, false otherwise + Changes the video mode of this display to the mode specified in the +mode parameter. + +If wx.DefaultVideoMode is passed in as the mode parameter, the defined +behaviour is that wx.Display will reset the video mode to the default +mode used by the display. On Windows, the behavior is normal. +However, there are differences on other platforms. On Unix variations +using X11 extensions it should behave as defined, but some +irregularities may occur. + +On wxMac passing in wx.DefaultVideoMode as the mode parameter does +nothing. This happens because Carbon no longer has access to +DMUseScreenPrefs, an undocumented function that changed the video mode +to the system default by using the system's 'scrn' resource. + +Returns True if succeeded, False otherwise @@ -24897,7 +26956,47 @@ 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. +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. + + __init__(self, Window parent, int id=-1, DateTime date=DefaultDateTime, @@ -25093,7 +27192,15 @@ cleared. 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. +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. + =================== ============================================ + @@ -25680,6 +27787,9 @@ this. IsReadOnly(self) -> bool + + GetKind(self) -> int + SetDefAttr(self, GridCellAttr defAttr) @@ -27538,6 +29648,25 @@ EVT_GRID_SELECT_CELL = wx.PyEventBinder( wxEVT_GRID_SELECT_CELL ) EVT_GRID_EDITOR_SHOWN = wx.PyEventBinder( wxEVT_GRID_EDITOR_SHOWN ) EVT_GRID_EDITOR_HIDDEN = wx.PyEventBinder( wxEVT_GRID_EDITOR_HIDDEN ) EVT_GRID_EDITOR_CREATED = wx.PyEventBinder( wxEVT_GRID_EDITOR_CREATED ) + + +# The same as above but with the ability to specify an identifier +EVT_GRID_CMD_CELL_LEFT_CLICK = wx.PyEventBinder( wxEVT_GRID_CELL_LEFT_CLICK, 1 ) +EVT_GRID_CMD_CELL_RIGHT_CLICK = wx.PyEventBinder( wxEVT_GRID_CELL_RIGHT_CLICK, 1 ) +EVT_GRID_CMD_CELL_LEFT_DCLICK = wx.PyEventBinder( wxEVT_GRID_CELL_LEFT_DCLICK, 1 ) +EVT_GRID_CMD_CELL_RIGHT_DCLICK = wx.PyEventBinder( wxEVT_GRID_CELL_RIGHT_DCLICK, 1 ) +EVT_GRID_CMD_LABEL_LEFT_CLICK = wx.PyEventBinder( wxEVT_GRID_LABEL_LEFT_CLICK, 1 ) +EVT_GRID_CMD_LABEL_RIGHT_CLICK = wx.PyEventBinder( wxEVT_GRID_LABEL_RIGHT_CLICK, 1 ) +EVT_GRID_CMD_LABEL_LEFT_DCLICK = wx.PyEventBinder( wxEVT_GRID_LABEL_LEFT_DCLICK, 1 ) +EVT_GRID_CMD_LABEL_RIGHT_DCLICK = wx.PyEventBinder( wxEVT_GRID_LABEL_RIGHT_DCLICK, 1 ) +EVT_GRID_CMD_ROW_SIZE = wx.PyEventBinder( wxEVT_GRID_ROW_SIZE, 1 ) +EVT_GRID_CMD_COL_SIZE = wx.PyEventBinder( wxEVT_GRID_COL_SIZE, 1 ) +EVT_GRID_CMD_RANGE_SELECT = wx.PyEventBinder( wxEVT_GRID_RANGE_SELECT, 1 ) +EVT_GRID_CMD_CELL_CHANGE = wx.PyEventBinder( wxEVT_GRID_CELL_CHANGE, 1 ) +EVT_GRID_CMD_SELECT_CELL = wx.PyEventBinder( wxEVT_GRID_SELECT_CELL, 1 ) +EVT_GRID_CMD_EDITOR_SHOWN = wx.PyEventBinder( wxEVT_GRID_EDITOR_SHOWN, 1 ) +EVT_GRID_CMD_EDITOR_HIDDEN = wx.PyEventBinder( wxEVT_GRID_EDITOR_HIDDEN, 1 ) +EVT_GRID_CMD_EDITOR_CREATED = wx.PyEventBinder( wxEVT_GRID_EDITOR_CREATED, 1 ) @@ -27705,6 +29834,12 @@ EVT_GRID_EDITOR_CREATED = wx.PyEventBinder( wxEVT_GRID_EDITOR_CREATED ) + + NormalizeFontSizes(self, int size=-1) + + + + GetContainer(self) -> HtmlContainerCell @@ -28440,6 +30575,12 @@ EVT_GRID_EDITOR_CREATED = wx.PyEventBinder( wxEVT_GRID_EDITOR_CREATED ) + + NormalizeFontSizes(self, int size=-1) + + + + SetTitle(self, String title) @@ -28520,6 +30661,12 @@ EVT_GRID_EDITOR_CREATED = wx.PyEventBinder( wxEVT_GRID_EDITOR_CREATED ) SelectAll(self) + + SelectionToText(self) -> String + + + ToText(self) -> String + base_OnLinkClicked(self, HtmlLinkInfo link) @@ -28607,6 +30754,12 @@ this. + + NormalizeFontSizes(self, int size=-1) + + + + Render(self, int x, int y, int from=0, int dont_render=False, int to=INT_MAX, int choices=None, int LCOUNT=0) -> int @@ -28668,6 +30821,12 @@ this. + + NormalizeFontSizes(self, int size=-1) + + + + SetMargins(self, float top=25.2, float bottom=25.2, float left=25.2, float right=25.2, float spaces=5) @@ -28755,6 +30914,12 @@ this. + + NormalizeFontSizes(self, int size=-1) + + + + GetPrintData(self) -> PrintData @@ -38366,8 +40531,8 @@ XmlResource_AddSubclassFactory(XmlSubclassFactory_Python()) - wx = _core - __docfilter__ = wx.__DocFilter(globals()) + import wx + __docfilter__ = wx._core.__DocFilter(globals()) @@ -38634,6 +40799,7 @@ EVT_DYNAMIC_SASH_UNIFY = wx.PyEventBinder( wxEVT_DYNAMIC_SASH_UNIFY, 1 ) + wx.TR_DONT_ADJUST_MAC = TR_DONT_ADJUST_MAC @@ -39330,8 +41496,8 @@ EVT_DYNAMIC_SASH_UNIFY = wx.PyEventBinder( wxEVT_DYNAMIC_SASH_UNIFY, 1 ) GetHeaderWindow(self) -> Window - - GetMainWindow(self) -> Window + + GetMainWindow(self) -> ScrolledWindow -- 2.45.2