1
2
3 """
4 The Blender.Draw submodule.
5
6 Draw
7 ====
8
9 B{New}:
10 - access to ASCII values in L{events<Register>} callbacks;
11 - 'large' fonts for L{Text} and L{GetStringWidth}.
12 - Pop-up blocks with L{PupBlock}
13 - Color Picker button with L{ColorPicker}
14
15 This module provides access to a B{windowing interface} in Blender. Its widgets
16 include many kinds of buttons: push, toggle, menu, number, string, slider,
17 scrollbar, plus support for text drawing. It also includes keyboard keys and
18 mouse button code values in its dictionary, see a list after this example.
19
20 Example::
21 import Blender
22 from Blender import Draw, BGL
23
24 mystring = ""
25 mymsg = ""
26 toggle = 0
27
28 def event(evt, val): # the function to handle input events
29 global mystring, mymsg
30
31 if not val: # val = 0: it's a key/mbutton release
32 if evt in [Draw.LEFTMOUSE, Draw.MIDDLEMOUSE, Draw.RIGHTMOUSE]:
33 mymsg = "You released a mouse button."
34 Draw.Redraw(1)
35 return
36
37 if evt == Draw.ESCKEY:
38 Draw.Exit() # exit when user presses ESC
39 return
40
41 elif Draw.AKEY <= evt <= Draw.ZKEY: mystring += chr(evt)
42 elif evt == Draw.SPACEKEY: mystring += ' '
43 elif evt == Draw.BACKSPACEKEY and len(mystring):
44 mystring = mystring[:-1]
45 else: return # no need to redraw if nothing changed
46
47 Draw.Redraw(1)
48
49 def button_event(evt): # the function to handle Draw Button events
50 global mymsg, toggle
51 if evt == 1:
52 mymsg = "You pressed the toggle button."
53 toggle = 1 - toggle
54 Draw.Redraw(1)
55
56 def gui(): # the function to draw the screen
57 global mystring, mymsg, toggle
58 if len(mystring) > 90: mystring = ""
59 BGL.glClearColor(0,0,1,1)
60 BGL.glClear(BGL.GL_COLOR_BUFFER_BIT)
61 BGL.glColor3f(1,1,1)
62 Draw.Toggle("Toggle", 1, 10, 10, 55, 20, toggle,"A toggle button")
63 BGL.glRasterPos2i(72, 16)
64 if toggle: toggle_state = "down"
65 else: toggle_state = "up"
66 Draw.Text("The toggle button is %s." % toggle_state, "small")
67 BGL.glRasterPos2i(10, 230)
68 Draw.Text("Type letters from a to z, ESC to leave.")
69 BGL.glRasterPos2i(20, 200)
70 Draw.Text(mystring)
71 BGL.glColor3f(1,0.4,0.3)
72 BGL.glRasterPos2i(340, 70)
73 Draw.Text(mymsg, "tiny")
74
75 Draw.Register(gui, event, button_event) # registering the 3 callbacks
76
77 All available events:
78 - ACCENTGRAVEKEY
79 - AKEY
80 - BACKSLASHKEY
81 - BACKSPACEKEY
82 - BKEY
83 - CAPSLOCKKEY
84 - CKEY
85 - COMMAKEY
86 - DELKEY
87 - DKEY
88 - DOWNARROWKEY
89 - EIGHTKEY
90 - EKEY
91 - ENDKEY
92 - EQUALKEY
93 - ESCKEY
94 - F10KEY
95 - F11KEY
96 - F12KEY
97 - F1KEY
98 - F2KEY
99 - F3KEY
100 - F4KEY
101 - F5KEY
102 - F6KEY
103 - F7KEY
104 - F8KEY
105 - F9KEY
106 - FIVEKEY
107 - FKEY
108 - FOURKEY
109 - GKEY
110 - HKEY
111 - HOMEKEY
112 - IKEY
113 - INPUTCHANGE
114 - INSERTKEY
115 - JKEY
116 - KEYBD
117 - KKEY
118 - LEFTALTKEY
119 - LEFTARROWKEY
120 - LEFTBRACKETKEY
121 - LEFTCTRLKEY
122 - LEFTMOUSE
123 - LEFTSHIFTKEY
124 - LINEFEEDKEY
125 - LKEY
126 - MIDDLEMOUSE
127 - MINUSKEY
128 - MKEY
129 - MOUSEX
130 - MOUSEY
131 - NINEKEY
132 - NKEY
133 - OKEY
134 - ONEKEY
135 - PAD0
136 - PAD1
137 - PAD2
138 - PAD3
139 - PAD4
140 - PAD5
141 - PAD6
142 - PAD7
143 - PAD8
144 - PAD9
145 - PADASTERKEY
146 - PADENTER
147 - PADMINUS
148 - PADPERIOD
149 - PADPLUSKEY
150 - PADSLASHKEY
151 - PAGEDOWNKEY
152 - PAGEUPKEY
153 - PAUSEKEY
154 - PERIODKEY
155 - PKEY
156 - QFULL
157 - QKEY
158 - QUOTEKEY
159 - Q_FIRSTTIME
160 - RAWKEYBD
161 - REDRAW
162 - RETKEY
163 - RIGHTALTKEY
164 - RIGHTARROWKEY
165 - RIGHTBRACKETKEY
166 - RIGHTCTRLKEY
167 - RIGHTMOUSE
168 - RIGHTSHIFTKEY
169 - RKEY
170 - SEMICOLONKEY
171 - SEVENKEY
172 - SIXKEY
173 - SKEY
174 - SLASHKEY
175 - SPACEKEY
176 - TABKEY
177 - THREEKEY
178 - TIMER0
179 - TIMER1
180 - TIMER2
181 - TIMER3
182 - TKEY
183 - TWOKEY
184 - UKEY
185 - UPARROWKEY
186 - VKEY
187 - WHEELDOWNMOUSE
188 - WHEELUPMOUSE
189 - WINCLOSE
190 - WINFREEZE
191 - WINQUIT
192 - WINTHAW
193 - WKEY
194 - XKEY
195 - YKEY
196 - ZEROKEY
197 - ZKEY
198
199 @note: function Button has an alias: L{PushButton}.
200
201 @warn: B{very important}: if using your script causes "Error totblock"
202 messages when Blender exits (meaning that memory has been leaked), this may
203 have been caused by an ignored return value from one of the button types. To
204 avoid this, assign created buttons return values to B{global} variables,
205 instead of ignoring them. Examples::
206
207 # avoid this, it can cause memory leaks:
208 Draw.Toggle(...)
209 Draw.Number(...)
210 Draw.String(...)
211 # this is correct -- assuming the variables are globals:
212 my_toggle_button = Draw.Toggle(...)
213 my_int_button = Draw.Number(...)
214 my_str_button = Draw.String(...)
215
216
217 @warn: Inside the windowing loop (after Draw.Register() has been executed and
218 before Draw.Exit() is called), don't use the redraw functions from other
219 modules (Blender and Window). The Draw submodule has its own Draw.Redraw() and
220 Draw.Draw() functions that can be used inside the windowing loop.
221 """
222
224 """
225 Exit the windowing interface.
226 """
227
229 """
230 Buttons after this function will draw aligned (button layout only).
231 """
232
234 """
235 Use after BeginAlign() to stop aligning the buttons (button layout only).
236 """
237
239 """
240 This function creates a popup area where buttons, labels, sliders etc can be drawn.
241
242 @type draw: function
243 @param draw: A function to draw to the popup area, taking no arguments: draw().
244
245 @note: The size of the popup will expand to fit the bounds of the buttons created in the draw function.
246 @note: Be sure to use the mouse coordinates to position the buttons under the mouse,
247 so the popup dosn't exit as soon as it opens.
248 The coordinates for buttons start 0,0 at the bottom left hand side of the screen.
249 @note: Within this popup, Redraw events and the registered button callback will not work.
250 For buttons to run events, use per button callbacks.
251 @note: OpenGL drawing functions wont work within this popup, for text use L{Label} rather then L{Text}
252 @warning: L{Menu} will not work properly within a UIBlock, this is a limitation with blenders user interface internals.
253 """
254
255 -def Register(draw = None, event = None, button = None):
256 """
257 Register callbacks for windowing.
258 @type draw: function
259 @type event: function
260 @type button: function
261 @param draw: A function to draw the screen, taking no arguments: draw().
262 @param event: A function to handle keyboard and mouse input events, taking
263 two arguments: f(evt, val), where:
264 - 'evt' (int) is the event number;
265 - 'val' (int) is the value modifier. If val = 0, the event refers to a
266 key or mouse button being released. Otherwise it's a key/button press.
267 @param button: A function to handle Draw Button events, taking one argument:
268 f(evt), where:
269 - 'evt' is the button number (see the I{event} parameter in L{Button}).
270 @note: note that in the example at the beginning of this page Draw.Register
271 is called only once. It's not necessary to re-register the callbacks,
272 they will stay until Draw.Exit is called. It's enough to redraw the
273 screen, when a relevant event is caught.
274 @note: only during the B{event} callback: the L{Blender}.ascii variable holds
275 the ASCII integer value (if it exists and is valid) of the current event.
276 """
277
279 """
280 Queue a redraw event. Redraw events are buffered so that, regardless of how
281 many events are queued, the window only receives one redraw event.
282 @type after: int
283 @param after: If non-zero, the redraw is processed before other input events.
284 """
285
287 """
288 Force an immediate redraw. Forced redraws are not buffered. In other words,
289 the window is redrawn once every time this function is called.
290 """
291
293 """
294 Create a default Button object.
295 @type value: int, float, string or 3 floats
296 @param value: The value to store in the button.
297 @rtype: Blender Button
298 @return: The Button created.
299 @note: String values must have less then 400 characters.
300 """
301
330
332 """
333 Create a pop-up menu.
334
335 The menu options are specified through the 'name' parameter, like with
336 L{Menu}: options are followed by a format code and separated by the '|'
337 character. Valid format codes are:
338 - %t - The option should be used as the title of the pop-up;
339 - %l - insert a separating line (only works if 'maxrow' isn't given);
340 - %xB{N} - Chosen this option, PupMenu should return the integer B{N}.
341
342 Example::
343 name = "OK?%t|QUIT BLENDER" # if no %xN int is set, indices start from 1
344 result = Draw.PupMenu(name)
345 if result:
346 Draw.PupMenu("Really?%t|Yes|No")
347
348 @type name: string
349 @param name: The format string to define the contents of the button.
350 @type maxrow: int
351 @param maxrow: The maximum number of rows for each column in the pop-up.
352 @rtype: int
353 @return: the chosen entry number or -1 if none was chosen.
354 """
355
357 """
358 Create a popup menu tree.
359
360 Each item in the list is a menu item - (str, event), separator - None or submenu - (str, [...]).
361
362 Submenus list uses the same syntax as the menu list.
363
364 Example::
365 result = Draw.PupTreeMenu( [ ("Menu Item 1", 10), ("Menu Item 2", 12), ("SubMenu", [("Menu Item 3", 100), ("MenuItem4", 101) ] ) ] )
366
367 @type menu: string
368 @param menu: A menu list
369 @rtype: int
370 @return: the chosen entry number or -1 if none was chosen.
371 """
372
402
438
459
461 """
462 Display a pop-up block.
463
464 Possible formats for the items in the sequence parameter.
465 (Value are objects created with L{Create})
466 - string: Defines a label
467 - (string, Value, string): Defines a toggle button. The first string is the text on the button, the optional second string is the tooltip.
468 - (string, Value, min, max, string): Defines a numeric or string button, depending on the content of Value. The first string is the text on the button, the optional second string is the tooltip. I{For string, max is the maximum length of the string and min is unused.}
469
470 Example::
471 import Blender
472
473 text = Blender.Draw.Create("short text")
474 f = Blender.Draw.Create(1.0)
475 i = Blender.Draw.Create(2)
476 tog = Blender.Draw.Create(0)
477
478 block = []
479
480 block.append(("Name: ", text, 0, 30, "this is some tool tip"))
481 block.append("Some Label")
482 block.append(("Value: ", f, 0.0, 100.0))
483 block.append(("Value: ", i, 0, 100))
484 block.append(("Option", tog, "another tooltip"))
485
486 retval = Blender.Draw.PupBlock("PupBlock test", block)
487
488 print "PupBlock returned", retval
489
490 print "text\\t", text
491 print "float\\t", f
492 print "int\\t", i
493 print "toggle\\t", tog
494
495 @warning: On cancel, the Value objects are brought back to there initial values except for string values which will still contain the modified values.
496 @type title: string
497 @param title: The title of the block.
498 @param sequence: A sequence defining what the block contains.
499 The order of the list is the order of appearance, from top down.
500 @rtype: int
501 @return: 1 if the pop-up is confirmed, 0 otherwise
502 """
503
505 """
506 Create a new Menu Button object.
507
508 The menu options are specified through the 'name' of the button. Options are
509 I{followed} by a format code and separated by the '|' (pipe) character. Valid
510 format codes are:
511 - %t - The option should be used as the title;
512 - %l - Insert a separating line;
513 - %xB{N} - The option should set the integer B{N} in the button value.
514
515 Example::
516 name = "The Title %t|First Entry %x1|Second Entry %x2|Third Entry %x3"
517 menu = Draw.Menu(name, 2, 60, 120, 200, 40, 3, "Just a test menu.")
518 # note that, since default = 3, the "Third Entry"
519 # will appear as the default choice in the Menu.
520
521 @type name: string
522 @param name: The format string to define the contents of the button.
523 @type event: int
524 @param event: The event number to pass to the button event function when
525 activated.
526 @type x: int
527 @type y: int
528 @param x: The lower left x (horizontal) coordinate of the button.
529 @param y: The lower left y (vertical) coordinate of the button.
530 @type width: int
531 @type height: int
532 @param width: The button width.
533 @param height: The button height.
534 @type default: int
535 @param default: The number of the option to be selected by default.
536 @type tooltip: string
537 @param tooltip: The button's tooltip (the string that appears when the mouse
538 is kept over the button).
539 @type callback: function
540 @param callback: an optional argument so this button can have its own
541 callback function. the function will run whenever this button is pressed.
542 This function must accept 2 arguments (event, val).
543 @rtype: Blender Button
544 @return: The Button created.
545 """
546
547 -def Toggle(name, event, x, y, width, height, default, tooltip = None, callback = None):
548 """
549 Create a new Toggle Button object.
550 @type name: string
551 @param name: The string to display on the button.
552 @type event: int
553 @param event: The event number to pass to the button event function when
554 activated.
555 @type x: int
556 @type y: int
557 @param x: The lower left x (horizontal) coordinate of the button.
558 @param y: The lower left y (vertical) coordinate of the button.
559 @type width: int
560 @type height: int
561 @param width: The button width.
562 @param height: The button height.
563 @type default: int
564 @param default: The value specifying the default state:
565 (0 for "up", 1 for "down").
566 @type tooltip: string
567 @param tooltip: The button's tooltip (the string that appears when the mouse
568 is kept over the button).
569 @type callback: function
570 @param callback: an optional argument so this button can have its own
571 callback function. the function will run whenever this button is pressed.
572 This function must accept 2 arguments (event, val).
573 @rtype: Blender Button
574 @return: The Button created.
575 """
576
577 -def Slider(name, event, x, y, width, height, initial, min, max, realtime = 1,
578 tooltip = None, callback = None):
579 """
580 Create a new Slider Button object.
581 @type name: string
582 @param name: The string to display on the button.
583 @type event: int
584 @param event: The event number to pass to the button event function when
585 activated.
586 @type x: int
587 @type y: int
588 @param x: The lower left x (horizontal) coordinate of the button.
589 @param y: The lower left y (vertical) coordinate of the button.
590 @type width: int
591 @type height: int
592 @param width: The button width.
593 @param height: The button height.
594 @type initial: int or float
595 @type min: int or float
596 @type max: int or float
597 @param initial: The initial value.
598 @param min: The minimum value.
599 @param max: The maximum value.
600 @type realtime: int
601 @param realtime: If non-zero (the default), the slider will emit events as
602 it is edited.
603 @type tooltip: string
604 @param tooltip: The button's tooltip (the string that appears when the mouse
605 is kept over the button).
606
607 @type callback: function
608 @param callback: an optional argument so this button can have its own
609 callback function. the function will run whenever this button is pressed.
610 This function must accept 2 arguments (event, val).
611 @rtype: Blender Button
612 @return: The Button created.
613 @note: slider callbacks will not work if the realtime setting is enabled.
614 """
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647 -def ColorPicker(event, x, y, width, height, initial, tooltip = None, callback = None):
648 """
649 Create a new Color Picker Button object.
650 @type event: int
651 @param event: The event number to pass to the button event function when
652 activated.
653 @type x: int
654 @type y: int
655 @param x: The lower left x (horizontal) coordinate of the button.
656 @param y: The lower left y (vertical) coordinate of the button.
657 @type width: int
658 @type height: int
659 @param width: The button width.
660 @param height: The button height.
661 @type initial: 3-float tuple
662 @param initial: The initial color value. All values must be between 0 and 1
663 @type tooltip: string
664 @param tooltip: The button's tooltip (the string that appears when the mouse
665 is kept over the button).
666 @type callback: function
667 @param callback: an optional argument so this button can have its own
668 callback function. the function will run whenever this button is pressed.
669 This function must accept 2 arguments (event, val).
670 @rtype: Blender Button
671 @return: The Button created.
672 @note: The color picker will not work if the Register's event function is None.
673 @note: Using the same button variable with more then 1 button at a time will corrupt memory.
674 """
675
676 -def Normal(event, x, y, width, height, initial, tooltip = None, callback = None):
677 """
678 Create a new Normal button, this allows you to set a 3d vector by rotating a sphere.
679 @type event: int
680 @param event: The event number to pass to the button event function when
681 activated.
682 @type x: int
683 @type y: int
684 @param x: The lower left x (horizontal) coordinate of the button.
685 @param y: The lower left y (vertical) coordinate of the button.
686 @type width: int
687 @type height: int
688 @param width: The button width - non square normal buttons .
689 @param height: The button height.
690 @type initial: 3-float tuple
691 @param initial: The initial vector value.
692 @type tooltip: string
693 @param tooltip: The button's tooltip (the string that appears when the mouse
694 is kept over the button).
695 @type callback: function
696 @param callback: an optional argument so this button can have its own
697 callback function. the function will run whenever this button is pressed.
698 This function must accept 2 arguments (event, val).
699 @rtype: Blender Button
700 @return: The Button created.
701 @note: The normal button will not work if the Register's event function is None.
702 @note: Using the same button variable with more then 1 button at a time will corrupt memory.
703 """
704
705 -def Number(name, event, x, y, width, height, initial, min, max, tooltip = None, callback = None):
706 """
707 Create a new Number Button object.
708 @type name: string
709 @param name: The string to display on the button.
710 @type event: int
711 @param event: The event number to pass to the button event function when
712 activated.
713 @type x: int
714 @type y: int
715 @param x: The lower left x (horizontal) coordinate of the button.
716 @param y: The lower left y (vertical) coordinate of the button.
717 @type width: int
718 @type height: int
719 @param width: The button width.
720 @param height: The button height.
721 @type initial: int or float
722 @type min: int or float
723 @type max: int or float
724 @param initial: The initial value.
725 @param min: The minimum value.
726 @param max: The maximum value.
727 @type tooltip: string
728 @param tooltip: The button's tooltip (the string that appears when the mouse
729 is kept over the button).
730 @type callback: function
731 @param callback: an optional argument so this button can have its own
732 callback function. the function will run whenever this button is pressed.
733 This function must accept 2 arguments (event, val).
734 @rtype: Blender Button
735 @return: The Button created.
736
737 I{B{Example:}}
738
739 This example draws a single floating point value::
740 from Blender import Draw
741 b= Draw.Create(0.0) # Data for floating point button
742 def bevent(evt):
743 print 'My Button event:', evt
744 def gui():
745 global b
746 b= Draw.Number('value: ', 1000, 0,0, 200, 20, b.val, 0,10, 'some text tip')
747
748 Draw.Register(gui, None, bevent) # we are not going to worry about keyboard and mouse events
749 """
750
751
752 -def String(name, event, x, y, width, height, initial, length, tooltip = None, callback = None):
753 """
754 Create a new String Button object.
755 @type name: string
756 @param name: The string to display on the button.
757 @type event: int
758 @param event: The event number to pass to the button event function when
759 activated.
760 @type x: int
761 @type y: int
762 @param x: The lower left x (horizontal) coordinate of the button.
763 @param y: The lower left y (vertical) coordinate of the button.
764 @type width: int
765 @type height: int
766 @param width: The button width.
767 @param height: The button height.
768 @type initial: string
769 @param initial: The string to display initially.
770 @type length: int
771 @param length: The maximum input length.
772 @type tooltip: string
773 @param tooltip: The button's tooltip (the string that appears when the mouse
774 is kept over the button).
775 @type callback: function
776 @param callback: an optional argument so this button can have its own
777 callback function. the function will run whenever this button is pressed.
778 This function must accept 2 arguments (event, val).
779 @rtype: Blender Button
780 @return: The Button created.
781 """
782
784 """
785 Get the width in pixels of a string.
786 @type string: string
787 @param string: A string.
788 @type fontsize: string
789 @param fontsize: The size of the font: 'large', 'normal', 'normalfix', 'small' or 'tiny'.
790 @rtype: int
791 @return: The width of I{string} with the chosen I{fontsize}.
792 """
793
794 -def Text(string, fontsize = 'normal'):
795 """
796 Draw a string on the screen.
797
798 Text location is set using the OpenGL raster location functions L{BGL.glRasterPos} before the text is drawn.
799 This sets the text location from the lower left corner of the current window.
800
801 Text color is set using the OpenGL color functions L{BGL.glColor} before the text is drawn.
802
803 @type string: string
804 @param string: The text string to draw.
805 @type fontsize: string
806 @param fontsize: The size of the font: 'large', 'normal', 'normalfix', 'small' or 'tiny'.
807 @rtype: int
808 @return: The width of I{string} drawn with the chosen I{fontsize}.
809 @note: For drawing text in the 3d view see the workaround in L{BGL.glRasterPos}
810 """
811
812 -def Label(string, x, y, w, h):
813 """
814 Draw a text lable on the screen.
815
816 @type string: string
817 @param string: The text string to draw.
818 @rtype: None
819 @return: None
820 """
821
822 -def Image(image, x, y, zoomx=1.0, zoomy=1.0, clipx=0, clipy=0, clipw=-1, cliph=-1):
823 """
824 Draw an image on the screen.
825
826 The image is drawn at the location specified by the coordinates (x,y). A
827 pair of optional zoom factors (in horizontal and vertical directions) can
828 be applied to the image as it is drawn, and an additional clipping rectangle
829 can be applied to extract a particular sub-region of the image to draw.
830
831 Note that the clipping rectangle is given in image space coordinates. In
832 image space, the origin is located at the bottom left, with x coordinates
833 increasing to the right and y coordinates increasing upwards. No matter
834 where the clipping rectangle is placed in image space, the lower-left pixel
835 drawn on the screen is always placed at the coordinates (x,y). The
836 clipping rectangle is itself clipped to the dimensions of the image. If
837 either the width or the height of the clipping rectangle are negative then
838 the corresponding dimension (width or height) is set to include as much of
839 the image as possible.
840
841 For drawing images with alpha blending with the background you will need to enable blending as shown in the example.
842
843 Example::
844 import Blender
845 from Blender import BGL, Image, Draw
846
847 myimage = Image.Load('myimage.png')
848
849 def gui():
850 BGL.glEnable( BGL.GL_BLEND ) # Only needed for alpha blending images with background.
851 BGL.glBlendFunc(BGL.GL_SRC_ALPHA, BGL.GL_ONE_MINUS_SRC_ALPHA)
852
853 Draw.Image(myimage, 50, 50)
854
855 BGL.glDisable( BGL.GL_BLEND )
856 def event(evt, val):
857 if evt == Draw.ESCKEY:
858 Draw.Exit()
859
860 Draw.Register(gui, event, None)
861
862 @type image: Blender.Image
863 @param image: The image to draw.
864 @type x: int
865 @param x: The lower left x (horizontal) position of the origin of the image.
866 @type y: int
867 @param y: The lower left y (vertical) position of the origin of the image.
868 @type zoomx: float
869 @param zoomx: The x (horizontal) zoom factor to use when drawing the image.
870 @type zoomy: float
871 @param zoomy: The y (vertical) zoom factor to use when drawing the image.
872 @type clipx: int
873 @param clipx: The lower left x (horizontal) origin of the clipping rectangle
874 within the image. A value of 0 indicates the left of the
875 image.
876 @type clipy: int
877 @param clipy: The lower left y (vertical) origin of the clipping rectangle
878 within the image. A value of 0 indicates the bottom of the
879 image.
880 @type clipw: int
881 @param clipw: The width of the clipping rectangle within the image. If this
882 value is negative then the clipping rectangle includes as much
883 of the image as possible in the x (horizontal) direction.
884 @type cliph: int
885 @param cliph: The height of the clipping rectangle within the image. If this
886 value is negative then the clipping rectangle includes as much
887 of the image as possible in the y (vertical) direction.
888 """
889
898