windows_api_utils/

lib.rs

//! Windows API utilities for coordinate conversion, bit operations, and message parameter handling.
//!
//! This crate provides utilities for working with Windows API concepts including:
//! - Coordinate conversion between client and screen coordinates
//! - Bit manipulation (LOWORD, HIWORD, LOBYTE, HIBYTE)
//! - Windows message parameter handling (WPARAM, LPARAM)
//!
//! # Features
//!
//! - **Coordinate Conversion**: ClientToScreen, ScreenToClient functionality
//! - **Bit Manipulation**: Extract high/low words and bytes from integers
//! - **Message Parameters**: Type-safe WPARAM and LPARAM handling
//! - **Cross-platform**: Works on Windows, Linux, and macOS
//! - **No-std support**: Core functionality available without std
//! - **Feature Gating**: Enable only the functionality you need
//! - **Serialization**: Optional serde support for message types
//! - **Windows Interop**: Seamless compatibility with windows crate
//!
//! # Feature Flags
//!
//! - `coordinates`: Enables coordinate conversion types and traits
//! - `bit-ops`: Enables bit manipulation utilities  
//! - `messages`: Enables Windows message handling
//! - `serde`: Enables serialization support for types
//! - `windows-interop`: Enables seamless compatibility with windows crate
//! - `full`: Enables all features
//! - `minimal`: Disables all optional features (default: enabled)
//!
//! # Quick Start
//!
//! ## Using default features (coordinates + messages)
//!
//! ```toml
//! [dependencies]
//! windows-api-utils = "0.1"
//! ```
//!
//! ```rust
//! use windows_api_utils::prelude::*;
//!
//! // Coordinate conversion
//! let window = Window::new(12345, Rect::new(100, 100, 500, 400), Default::default());
//! let client_point = Point::new(50, 30);
//! let screen_point = window.client_to_screen(client_point).unwrap();
//!
//! // Message handling
//! let message = WindowMessage::mouse_move(100, 200, KeyModifiers::default());
//! if let Some(mouse_event) = MessageParser::parse_mouse_message(message) {
//!     println!("Mouse at ({}, {})", mouse_event.x, mouse_event.y);
//! }
//! ```
//!
//! ## Using with windows crate interop
//!
//! ```toml
//! [dependencies]
//! windows-api-utils = { version = "0.1", features = ["windows-interop"] }
//! windows = "0.52"
//! ```
//!
//! ```rust
//! use windows_api_utils::prelude::*;
//! use windows::Win32::Foundation::{WPARAM, LPARAM};
//!
//! // 完全兼容，无需转换！
//! let win_wparam = WPARAM(0x1234);
//! let our_wparam = WParam::from(win_wparam);
//! let back_to_win: WPARAM = our_wparam.into();
//!
//! assert_eq!(win_wparam.0, back_to_win.0);
//!
//! // 坐标转换测试
//! let win_lparam = LPARAM(0x00C80064); // x=100, y=200
//! let our_lparam = LParam::from(win_lparam);
//! let (x, y) = our_lparam.as_point();
//! assert_eq!(x, 100);
//! assert_eq!(y, 200);
//!
//! // from_point -> our_lparam -> win_lparam 完整流程测试
//! let our_lparam_from_coords = LParam::from_point(300, 400);
//! let win_lparam_from_our: LPARAM = our_lparam_from_coords.into();
//! let (x_back, y_back) = our_lparam_from_coords.as_point();
//! assert_eq!(x_back, 300);
//! assert_eq!(y_back, 400);
//!
//! // 验证转换后的值是正确的坐标编码
//! let expected_value = ((400 as u32) << 16) | (300 as u32);
//! assert_eq!(win_lparam_from_our.0 as u32, expected_value);
//! ```
//!
//! ## Using only coordinate features
//!
//! ```toml
//! [dependencies]
//! windows-api-utils = { version = "0.1", default-features = false, features = ["coordinates"] }
//! ```
//!
//! ```rust
//! use windows_api_utils::{Point, Rect, Window, CoordinateTransformer};
//!
//! let window = Window::new(12345, Rect::new(100, 100, 500, 400), Default::default());
//! let client_point = Point::new(50, 30);
//! let screen_point = window.client_to_screen(client_point).unwrap();
//! ```
//!
//! ## Using only bit operations
//!
//! ```toml
//! [dependencies]
//! windows-api-utils = { version = "0.1", default-features = false, features = ["bit-ops"] }
//! ```
//!
//! ```rust
//! # // 注意：这个测试需要 bit-ops 特性
//! # use windows_api_utils::{loword, hiword, make_long, BitUtils};
//! #
//! let value = 0x12345678;
//! let low = loword(value);  // 0x5678
//! let high = hiword(value); // 0x1234
//! let reconstructed = make_long(high, low);
//! ```
//!
//! ## Minimal usage (no-std compatible)
//!
//! ```toml
//! [dependencies]
//! windows-api-utils = { version = "0.1", default-features = false }
//! ```
//!
//! ```rust
//! use windows_api_utils::WindowsUtilsError;
//!
//! // Only error types available in minimal mode
//! ```

#![cfg_attr(not(feature = "std"), no_std)]
#![warn(missing_docs)]

// Core modules - always available
pub mod error;

// Feature-gated modules
#[cfg(feature = "coordinates")]
pub mod coordinates;

#[cfg(feature = "bit-ops")]
pub mod bit_ops;

#[cfg(feature = "messages")]
pub mod messages;

// Re-export error types (always available)
pub use error::*;

// Conditional re-exports based on features
#[cfg(feature = "coordinates")]
pub use coordinates::*;

#[cfg(feature = "bit-ops")]
pub use bit_ops::*;

#[cfg(feature = "messages")]
pub use messages::*;

/// Prelude for convenient imports based on enabled features.
pub mod prelude {
    pub use crate::WindowsUtilsError;
    pub use crate::WindowsUtilsResult;

    #[cfg(feature = "coordinates")]
    pub use crate::{CoordinateTransformer, Point, Rect, Window, WindowStyle};

    #[cfg(feature = "bit-ops")]
    pub use crate::{hibyte, hiword, lobyte, loword, make_long, make_word, BitUtils, LowHighWord};

    #[cfg(feature = "messages")]
    pub use crate::{
        windows_messages, KeyEvent, KeyModifiers, LParam, MessageParser, MouseButton, MouseEvent,
        WParam, WindowMessage, LPARAM, LRESULT, WPARAM,
    };

    // Windows interop 预导入
    #[cfg(feature = "windows-interop")]
    pub use crate::messages::windows_interop;
}