0
# System Integration and Utilities
1
2
System integration functions for clipboard access, file system paths, platform detection, and power management. These utilities provide cross-platform access to system services and information.
3
4
## Capabilities
5
6
### Clipboard Access
7
8
Functions for reading and writing text to the system clipboard.
9
10
```python { .api }
11
def SDL_SetClipboardText(text: bytes) -> int:
12
"""
13
Put UTF-8 text into the clipboard.
14
15
Parameters:
16
- text: text to copy to clipboard as bytes
17
18
Returns:
19
0 on success, negative on error
20
"""
21
22
def SDL_GetClipboardText() -> bytes:
23
"""
24
Get UTF-8 text from the clipboard.
25
26
Returns:
27
Clipboard text as bytes, or empty bytes if no text available
28
"""
29
30
def SDL_HasClipboardText() -> bool:
31
"""
32
Check whether the clipboard has text.
33
34
Returns:
35
True if clipboard has text, False otherwise
36
"""
37
38
def SDL_SetPrimarySelectionText(text: bytes) -> int:
39
"""
40
Put UTF-8 text into the primary selection (Unix/Linux only).
41
42
Parameters:
43
- text: text to set as primary selection
44
45
Returns:
46
0 on success, negative on error
47
"""
48
49
def SDL_GetPrimarySelectionText() -> bytes:
50
"""Get UTF-8 text from the primary selection (Unix/Linux only)."""
51
52
def SDL_HasPrimarySelectionText() -> bool:
53
"""Check whether the primary selection has text (Unix/Linux only)."""
54
```
55
56
### File System Paths
57
58
Functions for getting standard application directories and paths.
59
60
```python { .api }
61
def SDL_GetBasePath() -> bytes:
62
"""
63
Get the path where the application resides.
64
65
Returns:
66
Path to the application directory as bytes, or None on error
67
"""
68
69
def SDL_GetPrefPath(org: bytes, app: bytes) -> bytes:
70
"""
71
Get the user-specific preferences directory for the application.
72
73
Parameters:
74
- org: organization name as bytes
75
- app: application name as bytes
76
77
Returns:
78
Path to preferences directory as bytes, or None on error
79
"""
80
```
81
82
### Platform Detection
83
84
Functions for detecting the current platform and system information.
85
86
```python { .api }
87
def SDL_GetPlatform() -> bytes:
88
"""
89
Get the name of the platform.
90
91
Returns:
92
Platform name as bytes (e.g., b"Windows", b"Mac OS X", b"Linux")
93
"""
94
```
95
96
### Power Management
97
98
Functions for querying battery and power state information.
99
100
```python { .api }
101
def SDL_GetPowerInfo(secs: int, pct: int) -> int:
102
"""
103
Get current power supply details.
104
105
Parameters:
106
- secs: pointer to store seconds of battery life left (-1 if unknown)
107
- pct: pointer to store percentage of battery life left (-1 if unknown)
108
109
Returns:
110
SDL_PowerState value indicating current power state
111
"""
112
```
113
114
### Power State Constants
115
116
```python { .api }
117
# Power states
118
SDL_POWERSTATE_UNKNOWN = 0 # Cannot determine power status
119
SDL_POWERSTATE_ON_BATTERY = 1 # Not plugged in, running on battery
120
SDL_POWERSTATE_NO_BATTERY = 2 # Plugged in, no battery available
121
SDL_POWERSTATE_CHARGING = 3 # Plugged in, charging battery
122
SDL_POWERSTATE_CHARGED = 4 # Plugged in, battery charged
123
```
124
125
## Usage Examples
126
127
### Clipboard Operations
128
129
```python
130
import sdl2
131
132
# Initialize SDL
133
sdl2.SDL_Init(0)
134
135
# Check if clipboard has text
136
if sdl2.SDL_HasClipboardText():
137
# Get clipboard text
138
clipboard_text = sdl2.SDL_GetClipboardText()
139
print(f"Clipboard contains: {clipboard_text.decode('utf-8')}")
140
else:
141
print("Clipboard is empty")
142
143
# Set clipboard text
144
text_to_copy = "Hello from PySDL2!"
145
result = sdl2.SDL_SetClipboardText(text_to_copy.encode('utf-8'))
146
if result == 0:
147
print("Text copied to clipboard successfully")
148
else:
149
print("Failed to copy text to clipboard")
150
```
151
152
### File System Paths
153
154
```python
155
import sdl2
156
import os
157
158
# Initialize SDL
159
sdl2.SDL_Init(0)
160
161
# Get application base path
162
base_path = sdl2.SDL_GetBasePath()
163
if base_path:
164
print(f"Application directory: {base_path.decode('utf-8')}")
165
166
# Use base path for loading resources
167
resource_path = os.path.join(base_path.decode('utf-8'), "assets", "image.png")
168
print(f"Resource path: {resource_path}")
169
170
# Get preferences path
171
pref_path = sdl2.SDL_GetPrefPath(b"MyCompany", b"MyGame")
172
if pref_path:
173
print(f"Preferences directory: {pref_path.decode('utf-8')}")
174
175
# Use for saving config files, save games, etc.
176
config_file = os.path.join(pref_path.decode('utf-8'), "config.ini")
177
save_file = os.path.join(pref_path.decode('utf-8'), "savegame.dat")
178
```
179
180
### Platform Detection
181
182
```python
183
import sdl2
184
185
# Initialize SDL
186
sdl2.SDL_Init(0)
187
188
# Get platform name
189
platform = sdl2.SDL_GetPlatform()
190
platform_str = platform.decode('utf-8')
191
192
print(f"Running on: {platform_str}")
193
194
# Platform-specific code
195
if platform_str == "Windows":
196
print("Windows-specific initialization")
197
elif platform_str == "Mac OS X":
198
print("macOS-specific initialization")
199
elif platform_str == "Linux":
200
print("Linux-specific initialization")
201
else:
202
print(f"Unknown platform: {platform_str}")
203
```
204
205
### Power Management
206
207
```python
208
import sdl2
209
from ctypes import c_int, pointer
210
211
# Initialize SDL
212
sdl2.SDL_Init(0)
213
214
# Get power information
215
seconds_left = c_int()
216
percentage_left = c_int()
217
218
power_state = sdl2.SDL_GetPowerInfo(pointer(seconds_left), pointer(percentage_left))
219
220
# Interpret power state
221
if power_state == sdl2.SDL_POWERSTATE_UNKNOWN:
222
print("Power state unknown")
223
elif power_state == sdl2.SDL_POWERSTATE_ON_BATTERY:
224
print("Running on battery")
225
if seconds_left.value >= 0:
226
minutes = seconds_left.value // 60
227
print(f"Battery time remaining: {minutes} minutes")
228
if percentage_left.value >= 0:
229
print(f"Battery level: {percentage_left.value}%")
230
elif power_state == sdl2.SDL_POWERSTATE_NO_BATTERY:
231
print("Plugged in, no battery")
232
elif power_state == sdl2.SDL_POWERSTATE_CHARGING:
233
print("Plugged in, charging")
234
if percentage_left.value >= 0:
235
print(f"Battery level: {percentage_left.value}%")
236
elif power_state == sdl2.SDL_POWERSTATE_CHARGED:
237
print("Plugged in, battery fully charged")
238
```
239
240
### Cross-Platform File Handling
241
242
```python
243
import sdl2
244
import os
245
246
def get_app_data_path(app_name):
247
"""Get appropriate data directory for the application"""
248
# Get platform
249
platform = sdl2.SDL_GetPlatform().decode('utf-8')
250
251
if platform == "Windows":
252
# Use preferences path on Windows
253
return sdl2.SDL_GetPrefPath(b"", app_name.encode('utf-8'))
254
else:
255
# Use preferences path on other platforms too
256
return sdl2.SDL_GetPrefPath(b"", app_name.encode('utf-8'))
257
258
def save_game_data(app_name, data):
259
"""Save game data to appropriate location"""
260
data_path = get_app_data_path(app_name)
261
if data_path:
262
save_file = os.path.join(data_path.decode('utf-8'), "savegame.dat")
263
with open(save_file, 'w') as f:
264
f.write(data)
265
print(f"Game saved to: {save_file}")
266
return True
267
return False
268
269
# Usage
270
if save_game_data("MyGame", "player_level=5\nscore=1500"):
271
print("Game saved successfully")
272
```
273
274
## Types
275
276
```python { .api }
277
# Power state enumeration
278
SDL_PowerState = int
279
"""
280
Power state values:
281
- SDL_POWERSTATE_UNKNOWN: Cannot determine power status
282
- SDL_POWERSTATE_ON_BATTERY: Not plugged in, running on battery
283
- SDL_POWERSTATE_NO_BATTERY: Plugged in, no battery available
284
- SDL_POWERSTATE_CHARGING: Plugged in, charging battery
285
- SDL_POWERSTATE_CHARGED: Plugged in, battery charged
286
"""
287
```