win32: A Dart repository from halildurmus

Homepage | Documentation | Examples | Packages | Blog

Access Win32 APIs "directly" from Dart.

win32 is a Dart package that provides access to the most common Win32 APIs using FFI to make them accessible to Dart code without requiring a C compiler or the Windows SDK.

🎯 What is win32?

win32 allows Dart developers to tap into a broad range of Win32 API calls using FFI, simplifying access to Windows hardware and system services. By offering easy-to-use bindings for both traditional Win32 and COM (Component Object Model) APIs, it enables you to fully leverage Windows-specific functionalities directly in your Dart code.

💡 Why Use win32?

win32 is incredibly versatile and can be useful in a variety of scenarios, including:

Flutter Development on Windows: Need to access hardware accessories like gamepads or retrieve settings from the Windows registry in your app? win32 makes this possible with ease.
Cross-Platform Package Development: When writing a new cross-platform package, you can use win32 for the Windows-specific implementation, ensuring your package works seamlessly on Windows.
Enhanced Command-Line Utilities: If you're developing a command-line utility with Dart and require more advanced file APIs than what the dart:io library offers, win32 provides the necessary functionality.
Integration with Existing Windows Libraries: Smoothly integrate your apps with other Windows libraries that have published metadata using win32.

The main goal of win32 is to provide Dart developers with direct access to underlying Windows APIs, eliminating the need to manually map API conventions to Dart, simplifying development, and enhancing productivity.

📝 Documentation

Explore the full documentation at win32.pub/docs to dive deeper into the features and capabilities of the win32 package.

🚀 Getting Started

Add ffi and win32 packages to your project by running the appropriate command below:

For Flutter projects:

flutter pub add ffi win32

For Dart-only projects:

dart pub add ffi win32

Here's an example that demonstrates how to display a message box using the MessageBox function from the Windows API.

import 'package:ffi/ffi.dart';
import 'package:win32/win32.dart';

void main() {
  final lpCaption = 'Dart MessageBox Demo'.toNativeUtf16();
  final lpText = '''
This is not really an error, but we are pretending for the sake of this demo.

Resource error.
Do you want to try again?
'''
      .toNativeUtf16();

  final result = MessageBox(
    NULL,
    lpText,
    lpCaption,
    MESSAGEBOX_STYLE.MB_ICONWARNING | // Warning icon
        MESSAGEBOX_STYLE.MB_CANCELTRYCONTINUE | // Action button
        MESSAGEBOX_STYLE.MB_DEFBUTTON2, // Second button is the default
  );

  free(lpText);
  free(lpCaption);

  switch (result) {
    case MESSAGEBOX_RESULT.IDCANCEL:
      print('Cancel pressed');
    case MESSAGEBOX_RESULT.IDTRYAGAIN:
      print('Try Again pressed');
    case MESSAGEBOX_RESULT.IDCONTINUE:
      print('Continue pressed');
  }
}

🌟 Use Cases

Here are a few use cases showcasing the power of win32:

Building Windows Apps with Flutter: Create a Flutter-based Windows app that relies on Win32 APIs.

Accessing System Information: Retrieve system information not directly accessible through Dart's core libraries.

Enumerating Installed Fonts: Use EnumFontFamiliesEx to list all locally-installed fonts.

Developing Traditional Win32 Apps in Dart: Build classic Windows applications purely in Dart.

Game Development: Create a fully-fledged game using GDI, like the example below.

Advanced Console Applications: Build packages like dart_console that enable advanced console manipulation.

Modern File Pickers: Use filepicker_windows for a modern Windows file picker experience in your Dart/Flutter apps.

Access .NET Components: Access .NET components through COM interop.

Monitor System Events: Detect and respond to USB drive insertion and removal events.

This package provides minimal modifications to the Win32 API to support Dart idioms, aiming for high familiarity with existing Windows developers. Other Dart packages can build on these primitives to provide a more idiomatic API for Dart and Flutter developers.

A good example is win32_registry, which offers a set of APIs for accessing the Windows Registry without requiring knowledge of FFI.

📚 Examples

There are many examples included with this package that demonstrate calling various Win32 and COM APIs. These can be found in the examples subdirectory, and a short description of each example can be found here.

📦 Packages Built on win32

A growing number of Dart packages are built on the low-level APIs exposed by win32, providing more idiomatic class wrappers that are easy to integrate into your Flutter and Dart apps.

Here are some of the packages built on top of win32:

filepicker_windows: Provides access to Windows file open/save common dialog boxes.
win32_clipboard: Access the Windows Clipboard from Dart.
win32_gamepad: A friendly Dart API for accessing gamepads on Windows.
win32_gui: Provides object-oriented API for Win32 GUI development.
win32_registry: Easy access to the Windows Registry from Dart.
win32_runner: An experimental shell (runner) for hosting Flutter apps without a C++ compiler.

Find more packages on pub.dev.

🐞 Features and Bugs

win32 package offers a subset of the Win32 API, with more APIs being added regularly based on user demand. If you require additional functionality or encounter any bugs, please file an issue on our issue tracker.

🔄 Backwards Compatibility

While win32 follows semantic versioning (semver), some breaking changes may occur in minor versions due to improvements in the win32metadata scraper or the addition of new APIs.

To avoid potential issues, consider pinning to a specific version of win32 or regularly testing with the latest version.

🙏 Contributors

A heartfelt thank you to all our contributors who help improve win32 by creating packages, assisting with issues and pull requests, and participating in discussions.

🎉 Acknowledgements

The Tetris example was adapted from a C version by Chang-Hung Liang.

The C implementation of Snake by David Jones was ported with his permission.

The original C version of the Notepad example was authored by Charles Petzold, licensed by him without restriction.

The original C version of the custom titlebar example is by Dmitriy Kubyshkin and is licensed under the MIT License.

Win32 API documentation comments are licensed by Microsoft under the Creative Commons Attribution 4.0 International Public License.

halildurmus/win32