diff options
Diffstat (limited to 'source/blender/python/api2_2x/doc/Window.py')
| -rw-r--r-- | source/blender/python/api2_2x/doc/Window.py | 538 |
1 files changed, 0 insertions, 538 deletions
diff --git a/source/blender/python/api2_2x/doc/Window.py b/source/blender/python/api2_2x/doc/Window.py deleted file mode 100644 index 7fceeb757de..00000000000 --- a/source/blender/python/api2_2x/doc/Window.py +++ /dev/null @@ -1,538 +0,0 @@ -# Blender.Window module and the Window PyType object - -""" -The Blender.Window submodule. - -B{New}: renamed ViewLayer to L{ViewLayers} (actually added an alias, so both -forms will work). - -Window -====== - -This module provides access to B{Window} functions in Blender. - -Example: --------- - -FileSelector:: - - import Blender - from Blender import Window - # - def my_callback(filename): # callback for the FileSelector - print "You chose the file:", filename # do something with the chosen file - # - Window.FileSelector (my_callback, "Choose one!") - -Example: --------- - -DrawProgressBar:: - - import Blender - from Blender.Window import DrawProgressBar - # - # substitute the bogus_*() function calls for your own, of course. - # - DrawProgressBar (0.0, "Importing data ...") - bogus_importData() - DrawProgressBar (0.3, "Building something") - bogus_build() - DrawProgressBar (0.8, "Updating Blender") - bogus_update() - DrawProgressBar (1.0, "Finished") - # - # another example: - # - number = 1 - while number < 20: - file = filename + "00%d" % number - DrawProgressBar (number / 20.0, "Loading texture: %s" % file) - Blender.Image.Load(file) - number += 1 - - DrawProgressBar (1.0, "Finished loading") - - -@type Types: readonly dictionary -@var Types: The available Window Types. - - ACTION - - BUTS - - FILE - - IMAGE - - IMASEL - - INFO - - IPO - - NLA - - OOPS - - SCRIPT - - SEQ - - SOUND - - TEXT - - VIEW3D - -@type Qual: readonly dictionary -@var Qual: Qualifier keys (shift, control, alt) bitmasks. - - LALT: left ALT key - - RALT: right ALT key - - ALT: any ALT key, ... - - LCTRL - - RCTRL - - CTRL - - LSHIFT - - RSHIFT - - SHIFT - -@type MButs: readonly dictionary -@var MButs: Mouse buttons. - - L: left mouse button - - M: middle mouse button - - R: right mouse button - -@warn: The event system in Blender needs a rewrite, though we don't know when that will happen. Until then, event related functions here (L{QAdd}, L{QRead}, -L{QHandle}, etc.) can be used, but they are actually experimental and can be -substituted for a better method when the rewrite happens. In other words, use -them at your own risk, because though they should work well and allow many -interesting and powerful possibilities, they can be deprecated in some future -version of Blender / Blender Python. -""" - -def Redraw (spacetype = '<Types.VIEW3D>'): - """ - Force a redraw of a specific space type. - @type spacetype: int - @param spacetype: the space type, see L{Types}. By default the 3d Views are - redrawn. If spacetype < 0, all currently visible spaces are redrawn. - """ - -def RedrawAll (): - """ - Redraw all windows. - """ - -def QRedrawAll (): - """ - Redraw all windows by queue event. - """ - -def FileSelector (callback, title = 'SELECT FILE', filename = '<default>'): - """ - Open the file selector window in Blender. After the user selects a filename, - it is passed as parameter to the function callback given to FileSelector(). - Example:: - import Blender - # - def my_function(filename): - print 'The selected file was:', filename - # - Blender.Window.FileSelector (my_function, 'SAVE FILE') - @type callback: function that accepts a string: f(str) - @param callback: The function that must be provided to FileSelector() and - will receive the selected filename as parameter. - @type title: string - @param title: The string that appears in the button to confirm the selection - and return from the file selection window. - @type filename: string - @param filename: A filename. This defaults to Blender.Get('filename'). - @warn: script links are not allowed to call the File / Image Selectors. This - is because script links global dictionaries are removed when they finish - execution and the File Selector needs the passed callback to stay around. - An alternative is calling the File Selector from another script (see - L{Blender.Run}). - """ - -def ImageSelector (callback, title = 'SELECT IMAGE', filename = '<default>'): - """ - Open the image selector window in Blender. After the user selects a filename, - it is passed as parameter to the function callback given to ImageSelector(). - Example:: - import Blender - # - def my_function(imagename): - print 'The selected image was:', imagename - # - Blender.Window.ImageSelector (my_function, 'LOAD IMAGE') - @type callback: function that accepts a string: f(str) - @param callback: The function that must be provided to ImageSelector() and - will receive the selected filename as parameter. - @type title: string - @param title: The string that appears in the button to confirm the selection - and return from the image selection window. - @type filename: string - @param filename: A filename. This defaults to L{Blender.Get}('filename'). - @warn: script links are not allowed to call the File / Image Selectors. This - is because script links global dictionaries are removed when they finish - execution and the File Selector needs the passed callback to stay around. - An alternative is calling the File Selector from another script (see - L{Blender.Run}). - """ - -def DrawProgressBar (done, text): - """ - Draw a progress bar in the upper right corner of the screen. To cancel it - prematurely, users can press the "Esc" key. Start it with done = 0 and end - it with done = 1. - @type done: float - @param done: A float in [0.0, 1.0] that tells the advance in the progress - bar. - @type text: string - @param text: Info about what is currently being done "behind the scenes". - """ - -def GetCursorPos (): - """ - Get the current 3d cursor position. - @rtype: list of three floats - @return: the current position: [x, y, z]. - """ - -def GetActiveLayer (): - """ - Get the bitmask for the active layer. - @note: if there is no 3d view it will return zero. - @rtype: int - @return: layer bitmask - """ - -def SetActiveLayer(layermask): - """ - Set the bitmask for the active layer. - @type layermask: int - @param layermask: An integer bitmask, to use humanly readable values do (1<<0) for the first layer, (1<<19) for the last layer. - """ - -def SetCursorPos (coords): - """ - Change the 3d cursor position. - @type coords: 3 floats or a list of 3 floats - @param coords: The new x, y, z coordinates. - @note: if visible, the 3d View must be redrawn to display the change. This - can be done with L{Redraw}. - """ - -def GetPivot (): - """ - Get the pivot for the active 3D view. - @rtype: int - @return: constant - Window.PivotTypes - """ - -def SetPivot (pivot): - """ - Set the pivot on the active 3D view. - @type pivot: int - @param pivot: constant - Window.PivotTypes - """ - -def WaitCursor (bool): - """ - Set cursor to wait or back to normal mode. - - Example:: - Blender.Window.WaitCursor(1) - Blender.sys.sleep(2000) # do something that takes some time - Blender.Window.WaitCursor(0) # back - - @type bool: int (bool) - @param bool: if nonzero the cursor is set to wait mode, otherwise to normal - mode. - @note: when the script finishes execution, the cursor is set to normal by - Blender itself. - """ - -def GetViewVector (): - """ - Get the current 3d view vector. - @rtype: list of three floats - @return: the current vector: [x, y, z]. - """ - -def GetViewMatrix (): - """ - Get the current 3d view matrix. - @rtype: 4x4 float matrix (WRAPPED DATA) - @return: the current matrix. - """ - -def GetPerspMatrix (): - """ - Get the current 3d perspective matrix. - @rtype: 4x4 float matrix (WRAPPED DATA) - @return: the current matrix. - """ - -def EditMode(enable = -1, undo_msg = 'From script', undo = 1): - """ - Get and optionally set the current edit mode status: in or out. - - Example:: - in_editmode = Window.EditMode() - # MUST leave edit mode before changing an active mesh: - if in_editmode: Window.EditMode(0) - # ... - # make changes to the mesh - # ... - # be nice to the user and return things to how they were: - if in_editmode: Window.EditMode(1) - @type enable: int - @param enable: get/set current status: - - -1: just return current status (default); - - 0: leave edit mode; - - 1: enter edit mode. - - It's not an error to try to change to a state that is already the - current one, the function simply ignores the request. - @type undo_msg: string - @param undo_msg: only needed when exiting edit mode (EditMode(0)). This - string is used as the undo message in the Mesh->Undo History submenu in - the 3d view header. Max length is 63, strings longer than that get - clamped. - @param undo: don't save Undo information (only needed when exiting edit - mode). - @type undo: int - @rtype: int (bool) - @return: 0 if Blender is not in edit mode right now, 1 otherwise. - @warn: this is an important function. NMesh operates on normal Blender - meshes, not edit mode ones. If a script changes an active mesh while in - edit mode, when the user leaves the mode the changes will be lost, - because the normal mesh will be rebuilt based on its unchanged edit mesh. - """ - -def PoseMode(enable = -1): - """ - Get and optionally set the current pose mode status: in or out. - @type enable: int - @param enable: get/set current status: - - -1: just return current status (default); - - 0: leave edit mode; - - 1: enter edit mode. - - @return: 0 if Blender is not in edit mode right now, 1 otherwise. - @warn: This uses the active armature objects posemode status, enabling pose - mode for non armature objects will always fail. - """ - -def ViewLayers (layers = [], winid = None): - """ - Get and optionally set the currently visible layers in all 3d Views. - @type layers: list of ints - @param layers: a list with indexes of the layers that will be visible. Each - index must be in the range [1, 20]. If not given or equal to [], the - function simply returns the visible ones without changing anything. - @type winid: window id from as redurned by GetScreenInfo - @param winid: An optional argument to set the layer of a window - rather then setting the scene layers. For this to display in the 3d view - the layer lock must be disabled (unlocked). - @rtype: list of ints - @return: the currently visible layers. - """ - -def GetViewQuat (): - """ - Get the current VIEW3D view quaternion values. - @rtype: list of floats - @return: the quaternion as a list of four float values. - """ - -def SetViewQuat (quat): - """ - Set the current VIEW3D view quaternion. - @type quat: floats or list of floats - @param quat: four floats or a list of four floats. - """ - -def GetViewOffset (): - """ - Get the current VIEW3D offset values. - @rtype: list of floats - @return: a list with three floats: [x,y,z]. - @note: The 3 values returned are flipped in comparison object locations. - """ - -def SetViewOffset (ofs): - """ - Set the current VIEW3D offset values. - @type ofs: 3 floats or list of 3 floats - @param ofs: the new view offset values. - @note: The value you give flipped in comparison object locations. - """ - -def CameraView (camtov3d = 0): - """ - Set the current VIEW3D view to the active camera's view. If there's no - active object or it is not of type 'Camera', the active camera for the - current scene is used instead. - @type camtov3d: int (bool) - @param camtov3d: if nonzero it's the camera that gets positioned at the - current view, instead of the view being changed to that of the camera. - """ - -def QTest (): - """ - Check if there are pending events in the event queue. - @rtype: int - @return: 0 if there are no pending events, non-zero otherwise. - """ - -def QRead (): - """ - Get the next pending event from the event queue. - - Example:: - # let's catch all events and move the 3D Cursor when user presses - # the left mouse button. - from Blender import Draw, Window - - v3d = Window.GetScreenInfo(Window.Types.VIEW3D) - id = v3d[0]['id'] # get the (first) VIEW3D's id - - done = 0 - - while not done: # enter a 'get event' loop - evt, val = Window.QRead() # catch next event - if evt in [Draw.MOUSEX, Draw.MOUSEY]: - continue # speeds things up, ignores mouse movement - elif evt in [Draw.ESCKEY, Draw.QKEY]: done = 1 # end loop - elif evt == Draw.SPACEKEY: - Draw.PupMenu("Hey!|What did you expect?") - elif evt == Draw.Redraw: # catch redraw events to handle them - Window.RedrawAll() # redraw all areas - elif evt == Draw.LEFTMOUSE: # left button pressed - Window.QAdd(id, evt, 1) # add the caught mouse event to our v3d - # actually we should check if the event happened inside that area, - # using Window.GetMouseCoords() and v3d[0]['vertices'] values. - Window.QHandle(id) # process the event - # do something fancy like putting some object where the - # user positioned the 3d cursor, then: - Window.Redraw() # show the change in the VIEW3D areas. - - @rtype: list - @return: [event, val], where: - - event: int - the key or mouse event (see L{Draw}); - - val: int - 1 for a key press, 0 for a release, new x or y coordinates - for mouse movement events. - """ - -def QAdd (win, event, val, after = 0): - """ - Add an event to some window's (actually called areas in Blender) event queue. - @type win: int - @param win: the window id, see L{GetScreenInfo}. - @type event: positive int - @param event: the event to add, see events in L{Draw}. - @type val: int - @param val: 1 for a key press, 0 for a release. - @type after: int (bool) - @param after: if nonzero the event is put after the current queue and added - later. - """ - -def QHandle (winId): - """ - Process immediately all pending events for the given window (area). - @type winId: int - @param winId: the window id, see L{GetScreenInfo}. - @note: see L{QAdd} for how to send events to a particular window. - """ - -def GetMouseCoords (): - """ - Get mouse's current screen coordinates. - @rtype: list with two ints - @return: a [x, y] list with the coordinates. - """ - -def SetMouseCoords (coords): - """ - Set mouse's current screen coordinates. - @type coords: (list of) two ints - @param coords: can be passed as x, y or [x, y] and are clamped to stay inside - the screen. If not given they default to the coordinates of the middle - of the screen. - """ - -def GetMouseButtons (): - """ - Get the current mouse button state (see / compare against L{MButs}). - @rtype: int - @return: an OR'ed flag with the currently pressed buttons. - """ - -def GetKeyQualifiers (): - """ - Get the current qualifier keys state (see / compare against L{Qual}). - @rtype: int - @return: an OR'ed combination of values in L{Qual}. - """ - -def SetKeyQualifiers (qual): - """ - Fake qualifier keys state. This is useful because some key events require - one or more qualifiers to be active (see L{QAdd}). - @type qual: int - @param qual: an OR'ed combination of values in L{Qual}. - @rtype: int - @return: the current state, that should be equal to 'qual'. - @warn: remember to reset the qual keys to 0 once they are not necessary - anymore. - """ - -def GetAreaID (): - """ - Get the current area's ID. - """ - -def GetAreaSize (): - """ - Get the current area's size. - @rtype: list with two ints - @return: a [width, height] list. - @note: the returned values are 1 pixel bigger than what L{GetScreenInfo} - returns for the 'vertices' of the same area. - """ - -def GetScreenSize (): - """ - Get Blender's screen size. - @rtype: list with two ints - @return: a [width, height] list. - """ - -def GetScreens (): - """ - Get the names of all available screens. - @rtype: list of strings - @return: a list of names that can be passed to L{SetScreen}. - """ - -def SetScreen (name): - """ - Set as current screen the one with the given name. - @type name: string - @param name: the name of an existing screen. Use L{GetScreens} to get - a list with all screen names. - """ - -def GetScreenInfo (type = -1, rect = 'win', screen = ''): - """ - Get info about the current screen setup. - @type type: int - @param type: the space type (see L{Types}) to restrict the - results to. If -1 (the default), info is reported about all available - areas. - @type rect: string - @param rect: the rectangle of interest. This defines if the corner - coordinates returned will refer to: - - the whole area: 'total' - - only the header: 'header' - - only the window content part (default): 'win' - @type screen: string - @param screen: the name of an available screen. The current one is used by - default. - @rtype: list of dictionaries - @return: a list of dictionaries, one for each area in the screen. Each - dictionary has these keys (all values are ints): - - 'vertices': [xmin, ymin, xmax, ymax] area corners; - - 'win': window type, see L{Types}; - - 'id': this area's id. - """ |