0
# Cross-Platform Utilities
1

2
Core utilities that provide consistent APIs across Windows, macOS, and Linux platforms. These utilities abstract away platform-specific differences and provide unified interfaces for common system operations.
3

4
## Capabilities
5

6
### File Operations
7

8
Cross-platform file system operations with platform-specific implementations.
9

10
```java { .api }
11
/**
12
 * Abstract base class providing cross-platform file operations
13
 */
14
public abstract class FileUtils {
15
    /**
16
     * Get platform-specific implementation of FileUtils
17
     * @return FileUtils instance appropriate for current platform
18
     */
19
    public static FileUtils getInstance();
20
    
21
    /**
22
     * Move files to the system trash/recycle bin
23
     * @param files Files to move to trash
24
     * @throws IOException if trash operation fails
25
     */
26
    public abstract void moveToTrash(File... files) throws IOException;
27
    
28
    /**
29
     * Check if the current platform supports trash functionality
30
     * @return true if trash is available
31
     */
32
    public abstract boolean hasTrash();
33
}
34
```
35

36
**Platform Implementations:**
37
- **Windows**: `W32FileUtils` - Uses Shell32 API to move files to Recycle Bin
38
- **Mac**: `MacFileUtils` - Uses Finder to move files to Trash
39
- **Unix/Linux**: Platform-specific trash directory handling
40

41
**Usage Examples:**
42

43
```java
44
import com.sun.jna.platform.FileUtils;
45
import java.io.File;
46
import java.io.IOException;
47

48
// Get platform-specific file utilities
49
FileUtils fileUtils = FileUtils.getInstance();
50

51
// Check if trash is supported
52
if (fileUtils.hasTrash()) {
53
    try {
54
        // Move files to trash
55
        fileUtils.moveToTrash(
56
            new File("temp.txt"),
57
            new File("old_data.csv")
58
        );
59
        System.out.println("Files moved to trash successfully");
60
    } catch (IOException e) {
61
        System.err.println("Failed to move files to trash: " + e.getMessage());
62
    }
63
} else {
64
    System.out.println("Trash functionality not available on this platform");
65
}
66
```
67

68
### Window Manipulation
69

70
Advanced window effects and manipulation that work across different windowing systems.
71

72
```java { .api }
73
/**
74
 * Cross-platform window manipulation utilities
75
 * Provides shape masking, transparency effects, and window information
76
 */
77
public class WindowUtils {
78
    /** Use this to clear a window mask */
79
    public static final Shape MASK_NONE = null;
80
    
81
    // Window Masking Methods
82
    /**
83
     * Apply a shape mask to a window, making parts transparent
84
     * @param w Window to apply mask to
85
     * @param mask Shape defining visible area (bitmap treated, ignores transparency)
86
     */
87
    public static void setWindowMask(Window w, Shape mask);
88
    
89
    /**
90
     * Apply a shape mask to a heavyweight component
91
     * @param c Component to apply mask to
92
     * @param mask Shape defining visible area
93
     */
94
    public static void setComponentMask(Component c, Shape mask);
95
    
96
    /**
97
     * Apply an icon-based mask to a window
98
     * @param w Window to apply mask to
99
     * @param mask Icon to use as mask (non-transparent pixels included)
100
     */
101
    public static void setWindowMask(Window w, Icon mask);
102
    
103
    // Alpha/Transparency Methods
104
    /**
105
     * Check if window alpha transparency is supported
106
     * @return true if global alpha setting is supported
107
     */
108
    public static boolean isWindowAlphaSupported();
109
    
110
    /**
111
     * Get graphics configuration compatible with alpha compositing
112
     * @return GraphicsConfiguration suitable for alpha operations
113
     */
114
    public static GraphicsConfiguration getAlphaCompatibleGraphicsConfiguration();
115
    
116
    /**
117
     * Set window transparency level (Windows requires sun.java2d.noddraw=true)
118
     * @param w Window to make transparent
119
     * @param alpha Transparency level (1.0f = opaque, 0.0f = transparent)
120
     */
121
    public static void setWindowAlpha(Window w, float alpha);
122
    
123
    /**
124
     * Make window transparent with per-pixel alpha (macOS requires apple.awt.draggableWindowBackground)
125
     * @param w Window to make transparent
126
     * @param transparent true for per-pixel transparency, false for opaque
127
     */
128
    public static void setWindowTransparent(Window w, boolean transparent);
129
    
130
    // Window Information Methods (Windows-only)
131
    /**
132
     * Get icon from window handle (Windows only)
133
     * @param hwnd Window handle (HWND)
134
     * @return BufferedImage of window icon, or null if error
135
     */
136
    public static BufferedImage getWindowIcon(HWND hwnd);
137
    
138
    /**
139
     * Get size of an icon (Windows only)
140
     * @param hIcon Icon handle (HICON)
141
     * @return Dimension of icon, or (0,0) if error
142
     */
143
    public static Dimension getIconSize(HICON hIcon);
144
    
145
    /**
146
     * Get all desktop windows with detailed information (Windows only)
147
     * @param onlyVisibleWindows true to return only visible/non-minimized windows
148
     * @return List of DesktopWindow objects with window information
149
     */
150
    public static List<DesktopWindow> getAllWindows(boolean onlyVisibleWindows);
151
    
152
    /**
153
     * Get window title from handle (Windows only)
154
     * @param hwnd Window handle (HWND)
155
     * @return Window title string, or empty string if error
156
     */
157
    public static String getWindowTitle(HWND hwnd);
158
    
159
    /**
160
     * Get file path of process that owns the window (Windows only)
161
     * @param hwnd Window handle (HWND)
162
     * @return Full file path of executable, or null if error
163
     */
164
    public static String getProcessFilePath(HWND hwnd);
165
    
166
    /**
167
     * Get window location and size (Windows only)
168
     * @param hwnd Window handle (HWND)
169
     * @return Rectangle with window bounds
170
     */
171
    public static Rectangle getWindowLocationAndSize(HWND hwnd);
172
}
173

174
/**
175
 * Information about a desktop window (Windows only)
176
 */
177
public class DesktopWindow {
178
    /**
179
     * Create DesktopWindow with window information
180
     * @param hwnd Window handle
181
     * @param title Window title
182
     * @param filePath Path to executable
183
     * @param locAndSize Window bounds
184
     */
185
    public DesktopWindow(HWND hwnd, String title, String filePath, Rectangle locAndSize);
186
    
187
    /**
188
     * Get the Windows window handle
189
     * @return HWND window handle
190
     */
191
    public HWND getHWND();
192
    
193
    /**
194
     * Get window title
195
     * @return Window title string
196
     */
197
    public String getTitle();
198
    
199
    /**
200
     * Get file path of window's associated application
201
     * @return Full file path string
202
     */
203
    public String getFilePath();
204
    
205
    /**
206
     * Get window bounds
207
     * @return Rectangle defining window position and size
208
     */
209
    public Rectangle getLocAndSize();
210
}
211
```
212

213
**Usage Examples:**
214

215
```java
216
import com.sun.jna.platform.WindowUtils;
217
import com.sun.jna.platform.DesktopWindow;
218
import javax.swing.JFrame;
219
import java.awt.Shape;
220
import java.awt.geom.Ellipse2D;
221
import java.util.List;
222

223
// Create a JFrame for demonstration
224
JFrame frame = new JFrame("Test Window");
225
frame.setSize(300, 200);
226
frame.setVisible(true);
227

228
// Apply transparency
229
WindowUtils.setWindowAlpha(frame, 0.7f); // 70% opacity
230

231
// Create circular mask
232
Shape circleMask = new Ellipse2D.Double(0, 0, 300, 200);
233
WindowUtils.setWindowMask(frame, circleMask);
234

235
// Get all desktop windows
236
List<DesktopWindow> windows = WindowUtils.getAllWindows(true);
237
for (DesktopWindow window : windows) {
238
    System.out.println("Window: " + window.getTitle());
239
    System.out.println("  Path: " + window.getFilePath());
240
    System.out.println("  Bounds: " + window.getBounds());
241
}
242
```
243

244
### Keyboard State Access
245

246
Cross-platform access to current keyboard state, allowing applications to check if specific keys are currently pressed.
247

248
```java { .api }
249
/**
250
 * Cross-platform keyboard state utilities
251
 * Provides access to the local keyboard state across platforms
252
 * Requires graphics environment (throws HeadlessException on headless systems)
253
 * Note: macOS support is not yet implemented
254
 */
255
public class KeyboardUtils {
256
    /**
257
     * Check if a specific key is currently pressed
258
     * @param keycode Key code to check (uses KeyEvent constants like KeyEvent.VK_A, KeyEvent.VK_SHIFT)
259
     * @return true if the specified key is currently pressed
260
     */
261
    public static boolean isPressed(int keycode);
262
    
263
    /**
264
     * Check if a specific key at a specific location is currently pressed
265
     * @param keycode Key code to check (uses KeyEvent constants)
266
     * @param location Key location (uses KeyEvent location constants like KEY_LOCATION_LEFT, KEY_LOCATION_RIGHT)
267
     * @return true if the specified key at the specified location is currently pressed
268
     */
269
    public static boolean isPressed(int keycode, int location);
270
}
271
```
272

273
**Platform Support:**
274
- **Windows**: Full support using `User32.GetAsyncKeyState()`
275
- **Linux/Unix X11**: Basic support using X11 `XQueryKeymap()`  
276
- **macOS**: Not yet implemented (throws `UnsupportedOperationException`)
277

278
**Usage Examples:**
279

280
```java
281
import com.sun.jna.platform.KeyboardUtils;
282
import java.awt.event.KeyEvent;
283

284
// Check if 'A' key is pressed
285
boolean aPressed = KeyboardUtils.isPressed(KeyEvent.VK_A);
286

287
// Check if left Shift key is specifically pressed
288
boolean leftShiftPressed = KeyboardUtils.isPressed(KeyEvent.VK_SHIFT, KeyEvent.KEY_LOCATION_LEFT);
289

290
// Check if right Control key is specifically pressed  
291
boolean rightCtrlPressed = KeyboardUtils.isPressed(KeyEvent.VK_CONTROL, KeyEvent.KEY_LOCATION_RIGHT);
292

293
// Check if any Alt key is pressed (location unknown)
294
boolean altPressed = KeyboardUtils.isPressed(KeyEvent.VK_ALT);
295

296
// Example game input checking
297
if (KeyboardUtils.isPressed(KeyEvent.VK_W)) {
298
    moveForward();
299
}
300
if (KeyboardUtils.isPressed(KeyEvent.VK_A)) {
301
    moveLeft();
302
}
303
```
304

305

306
### Enum Conversion Utilities
307

308
Utilities for converting between enum values and integer representations, with special support for flag-based enums.
309

310
```java { .api }
311
/**
312
 * Helper methods to convert between enum values and integer flags/indices
313
 * Supports both simple enum-to-index conversion and flag-based enum sets
314
 */
315
public class EnumUtils {
316
    /** Uninitialized integer flag constant */
317
    public static final int UNINITIALIZED = -1;
318
    
319
    /**
320
     * Convert enum to its ordinal index
321
     * @param val Enum value to convert
322
     * @return Index position of the enum in its declaration order
323
     */
324
    public static <E extends Enum<E>> int toInteger(E val);
325
    
326
    /**
327
     * Convert integer index back to enum value
328
     * @param idx Index position to retrieve
329
     * @param clazz Enum class type
330
     * @return Enum value at specified index, or null if idx == UNINITIALIZED
331
     */
332
    public static <E extends Enum<E>> E fromInteger(int idx, Class<E> clazz);
333
    
334
    /**
335
     * Convert bitwise OR'd flags to a Set of FlagEnum values
336
     * @param flags Bitwise combination of flag values
337
     * @param clazz FlagEnum class type
338
     * @return Set containing all enum values whose flags are set
339
     */
340
    public static <T extends FlagEnum> Set<T> setFromInteger(int flags, Class<T> clazz);
341
    
342
    /**
343
     * Convert Set of FlagEnum values to combined integer flags
344
     * @param set Set of FlagEnum values to convert
345
     * @return Bitwise OR combination of all flag values in the set
346
     */
347
    public static <T extends FlagEnum> int setToInteger(Set<T> set);
348
}
349

350
/**
351
 * Image processing utilities for window masking and effects
352
 */
353
public class RasterRangesUtils {
354
    /**
355
     * Convert a Shape to raster ranges for window masking
356
     * @param shape Shape to convert
357
     * @param bounds Bounds of the area
358
     * @return Raster ranges suitable for native masking APIs
359
     */
360
    public static int[] shapeToRasterRanges(Shape shape, Rectangle bounds);
361
}
362
```
363

364
## Platform Detection Examples
365

366
```java
367
import com.sun.jna.Platform;
368

369
// Check current platform and use appropriate utilities
370
if (Platform.isWindows()) {
371
    // Windows-specific operations
372
    FileUtils fileUtils = FileUtils.getInstance(); // Returns W32FileUtils
373
} else if (Platform.isMac()) {
374
    // macOS-specific operations  
375
    FileUtils fileUtils = FileUtils.getInstance(); // Returns MacFileUtils
376
} else if (Platform.isLinux()) {
377
    // Linux-specific operations
378
    FileUtils fileUtils = FileUtils.getInstance(); // Returns Unix FileUtils
379
}
380

381
// Or use cross-platform APIs directly
382
WindowUtils.setWindowAlpha(myWindow, 0.8f); // Works on all platforms
383
```