Skip to content

Commit b3965f3

Browse files
a-hursta-hurst
committed
Update ext.window docs, add restore method
1 parent 4848992 commit b3965f3

File tree

1 file changed

+131
-46
lines changed

1 file changed

+131
-46
lines changed

‎sdl2/ext/window.py‎

Lines changed: 131 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -8,36 +8,86 @@
88

99

1010
class Window(object):
11-
"""The Window class represents a visible on-screen object with an
12-
optional border and title text.
11+
"""Creates a visible window with an optional border and title text.
12+
13+
In SDL2, a window is the object through which visuals are displayed and
14+
all input events are captured. This class is a Pythonic alternative to
15+
working directly with SDL2's :obj:`~sdl2.SDL_Window` type, wrapping a
16+
number of useful functions for working with windows.
17+
18+
The created Window is hidden by default, but can be shown using the
19+
:meth:`~Window.show` method. Additionally, the type and properties of the
20+
created window can be configured using various flags:
21+
22+
================================== =========================================
23+
Flag Description
24+
================================== =========================================
25+
sdl2.SDL_WINDOW_SHOWN Will be shown when created
26+
sdl2.SDL_WINDOW_HIDDEN Will be hidden when created
27+
sdl2.SDL_WINDOW_BORDERLESS Will not be decorated by the OS
28+
sdl2.SDL_WINDOW_RESIZABLE Will be resizable
29+
sdl2.SDL_WINDOW_MINIMIZED Will be created in a minimized state
30+
sdl2.SDL_WINDOW_MAXIMIZED Will be created in a maximized state
31+
sdl2.SDL_WINDOW_FULLSCREEN Will be fullscreen
32+
sdl2.SDL_WINDOW_FULLSCREEN_DESKTOP Will be fullscreen at the current desktop
33+
resolution
34+
sdl2.SDL_WINDOW_OPENGL Will be usable with an OpenGL context
35+
sdl2.SDL_WINDOW_VULKAN Will be usable with a Vulkan instance
36+
sdl2.SDL_WINDOW_METAL Will be usable with a Metal context
37+
sdl2.SDL_WINDOW_ALLOW_HIGHDPI Will be created in high-DPI mode
38+
(if supported)
39+
sdl2.SDL_WINDOW_INPUT_FOCUS Will have input focus when created
40+
sdl2.SDL_WINDOW_MOUSE_FOCUS Will have mouse focus when created
41+
sdl2.SDL_WINDOW_INPUT_GRABBED Will prevent the mouse from leaving the
42+
bounds of the window
43+
sdl2.SDL_WINDOW_MOUSE_CAPTURE Will capture mouse to track input outside
44+
of the window when created
45+
================================== =========================================
46+
47+
There are also a few additional window creation flags that only affect the
48+
X11 window manager (i.e. most distributions of Linux and BSD):
49+
50+
================================== =====================================
51+
Flag Description
52+
================================== =====================================
53+
sdl2.SDL_WINDOW_ALWAYS_ON_TOP Should stay on top of other windows
54+
sdl2.SDL_WINDOW_SKIP_TASKBAR Should not be added to the taskbar
55+
sdl2.SDL_WINDOW_UTILITY Should be treated as a utility window
56+
sdl2.SDL_WINDOW_TOOLTIP Should be treated as a tooltip
57+
sdl2.SDL_WINDOW_POPUP_MENU Should be treated as a popup menu
58+
================================== =====================================
59+
60+
To combine multiple flags, you can use a bitwise OR to combine two or more
61+
together before passing them to the `flags` argument. For example, to create
62+
a fullscreen window that supports an OpenGL context and is shown on
63+
creation, you would use::
64+
65+
win_flags = (
66+
sdl2.SDL_WINDOW_FULLSCREEN | sdl2.SDL_WINDOW_OPENGL |
67+
sdl2.SDL_WINDOW_SHOWN
68+
)
69+
sdl2.ext.Window("PySDL2", (800, 600), flags=win_flags)
70+
71+
Args:
72+
title (str): The title to use for the window.
73+
size (tuple): The initial size (in pixels) of the window, in the format
74+
`(width, height)`.
75+
position (tuple, optional): The initial `(x, y)` coordinates of the
76+
top-left corner of the window. If not specified, defaults to letting
77+
the system's window manager choose a location for the window.
78+
flags (int, optional): The window attribute flags with which the window
79+
will be created. Defaults to `SDL_WINDOW_HIDDEN`.
80+
81+
Attributes:
82+
window (:obj:`~sdl2.SDL_Window`, None): The underlying SDL2 Window
83+
object. If the window has been closed, this value will be `None`.
1384
14-
It represents an area on the screen that can be accessed by the
15-
application for displaying graphics and receive and process user
16-
input.
1785
"""
1886
DEFAULTFLAGS = video.SDL_WINDOW_HIDDEN
1987
DEFAULTPOS = (video.SDL_WINDOWPOS_UNDEFINED,
2088
video.SDL_WINDOWPOS_UNDEFINED)
2189

2290
def __init__(self, title, size, position=None, flags=None):
23-
"""Creates a Window with a specific size and title.
24-
25-
The position to show the Window at is undefined by default,
26-
letting the operating system or window manager pick the best
27-
location. The behaviour can be adjusted through the DEFAULTPOS
28-
class variable:
29-
30-
Window.DEFAULTPOS = (10, 10)
31-
32-
The created Window is hidden by default, which can be overriden
33-
at the time of creation by providing other SDL window flags
34-
through the flags parameter.
35-
36-
The default flags for creating Window instances can be adjusted
37-
through the DEFAULTFLAGS class variable:
38-
39-
Window.DEFAULTFLAGS = sdl2.video.SDL_WINDOW_SHOWN
40-
"""
4191
if position is None:
4292
position = self.DEFAULTPOS
4393
if flags is None:
@@ -58,48 +108,48 @@ def __del__(self):
58108

59109
@property
60110
def position(self):
61-
"""The current window position as two-value tuple."""
111+
"""tuple: The (x, y) pixel coordinates of the top-left corner of the
112+
window.
113+
114+
"""
62115
x, y = c_int(), c_int()
63116
video.SDL_GetWindowPosition(self.window, byref(x), byref(y))
64117
return x.value, y.value
65118

66119
@position.setter
67120
def position(self, value):
68-
"""The current window position as two-value tuple."""
69121
if not self.window:
70122
raise SDLError("The window is not available")
71123
video.SDL_SetWindowPosition(self.window, value[0], value[1])
72124
self._position = value[0], value[1]
73125

74126
@property
75127
def title(self):
76-
"""The title of the window."""
128+
"""str: The title of the window."""
77129
return stringify(video.SDL_GetWindowTitle(self.window), "utf-8")
78130

79131
@title.setter
80132
def title(self, value):
81-
"""The title of the window."""
82133
video.SDL_SetWindowTitle(self.window, byteify(value, "utf-8"))
83134
self._title = value
84135

85136
@property
86137
def size(self):
87-
"""The size of the window."""
138+
"""tuple: The dimensions of the window (in pixels) in the form
139+
(width, height).
140+
141+
"""
88142
w, h = c_int(), c_int()
89143
video.SDL_GetWindowSize(self.window, byref(w), byref(h))
90144
return w.value, h.value
91145

92146
@size.setter
93147
def size(self, value):
94-
"""The size of the window."""
95148
video.SDL_SetWindowSize(self.window, value[0], value[1])
96149
self._size = value[0], value[1]
97150

98151
def create(self):
99-
"""Creates the window.
100-
101-
If the window already exists, this method will not do anything.
102-
"""
152+
"""Creates the window if it does not already exist."""
103153
if self.window != None:
104154
return
105155
window = video.SDL_CreateWindow(byteify(self._title, "utf-8"),
@@ -117,43 +167,78 @@ def open(self):
117167
self.show()
118168

119169
def close(self):
120-
"""Closes the window, implicitly destroying the underlying SDL2
121-
window."""
170+
"""Closes and destroys the window.
171+
172+
Once this method has been called, the window cannot be re-opened.
173+
However, you can create a new window with the same settings using the
174+
:meth:`create` method.
175+
176+
"""
122177
if hasattr(self, "window") and self.window != None:
123178
video.SDL_DestroyWindow(self.window)
124179
self.window = None
125180

126181
def show(self):
127-
"""Show the window on the display."""
182+
"""Shows the window on the display.
183+
184+
If the window is already visible, this method does nothing.
185+
186+
"""
128187
video.SDL_ShowWindow(self.window)
129188
video.SDL_GetWindowSurface(self.window)
130189

131190
def hide(self):
132-
"""Hides the window."""
191+
"""Hides the window.
192+
193+
If the window is already hidden, this method does nothing.
194+
195+
"""
133196
video.SDL_HideWindow(self.window)
134197

135198
def maximize(self):
136-
"""Maximizes the window to the display's dimensions."""
199+
"""Maximizes the window."""
137200
video.SDL_MaximizeWindow(self.window)
138201

139202
def minimize(self):
140-
"""Minimizes the window to an iconified state in the system tray."""
203+
"""Minimizes the window into the system's dock or task bar."""
141204
video.SDL_MinimizeWindow(self.window)
142205

206+
def restore(self):
207+
"""Restores a minimized or maximized window to its original state.
208+
209+
If the window has not been minimized or maximized, this method does
210+
nothing.
211+
212+
"""
213+
video.SDL_RestoreWindow(self.window)
214+
143215
def refresh(self):
144-
"""Refreshes the entire window surface.
216+
"""Updates the window to reflect any changes made to its surface.
145217
146-
This only needs to be called, if a SDL_Surface was acquired via
147-
get_surface() and is used to display contents.
218+
.. note: This only needs to be called if the window surface was
219+
acquired and modified using :meth:`get_surface`.
148220
"""
149221
video.SDL_UpdateWindowSurface(self.window)
150222

151223
def get_surface(self):
152-
"""Gets the SDL_Surface used by the Window to display 2D pixel
153-
data.
224+
"""Gets the :obj:`~sdl2.SDL_Surface` used by the window.
225+
226+
This method obtains the SDL surface used by the window, which can be
227+
then be modified to change the contents of the window (e.g draw shapes
228+
or images) using functions such as :func:`sdl2.SDL_BlitSurface` or
229+
:func:`sdl2.ext.fill`.
230+
231+
The obtained surface will be invalidated if the window is resized. As
232+
such, you will need to call this method again whenever this happens
233+
in order to continue to access the window's contents.
234+
235+
.. note: If using OpenGL/Vulkan/Metal rendering or the SDL rendering
236+
API (e.g. :func:`sdl2.SDL_CreateRenderer`) for drawing to the
237+
window, this method should not be used.
238+
239+
Returns:
240+
:obj:`~sdl2.SDL_Surface`: The surface associated with the window.
154241
155-
Using this method will make the usage of GL operations, such
156-
as texture handling, or using SDL renderers impossible.
157242
"""
158243
sf = video.SDL_GetWindowSurface(self.window)
159244
if not sf:

0 commit comments

Comments
 (0)