core-foundation-rs

By default, core-foundation-rs targets macOS 10.7. You can adjust the target version using Cargo features:

• macOS 10.8+ features: Enable the mac_os_10_8_features feature.
• Hybrid 10.7/10.8 support: To use 10.8 features while maintaining 10.7 compatibility, enable both mac_os_10_8_features and mac_os_10_7_support.

Note: Enabling both features requires weak linkage, which is a nightly-only feature in Rust (as of version 1.19).

The core_text crate provides Rust bindings to Apple's Core Text framework. It is organized into several modules that handle font management, text layout (frames, lines, runs), and string attributes.

Important Memory Management Note: Many functions in this crate add objects to the Objective-C autorelease pool. If your application does not have an active autorelease pool, using these functions will cause memory leaks. Ensure you are running within an environment that manages autorelease pools (like a standard Cocoa application loop) or manually manage pools where necessary.

The CFPropertyList type acts as a superclass for several specific types: CFData, CFString, CFArray, CFDictionary, CFDate, CFBoolean, and CFNumber.

Upcasting

To treat a specific type as a generic property list, use the CFPropertyListSubClass trait methods:

• to_CFPropertyList(): Creates a new CFPropertyList instance by incrementing the reference count (Get Rule).
• into_CFPropertyList(): Consumes the original object and transfers ownership to a CFPropertyList without changing the reference count (Create Rule).

Downcasting

If you have a CFPropertyList and want to recover its specific type, use:

• downcast<T>(): Returns an Option<T> by incrementing the reference count if the type matches.
• downcast_into<T>(): Consumes the CFPropertyList and returns Option<T> without touching the reference count.

You can transition between immutable and mutable dictionary types:

1. Immutable to Mutable:

   • Use CFMutableDictionary::from(&cf_dictionary) to create a new mutable copy.
   • Use unsafe { cf_dictionary.to_mutable() } to get a mutable view of the same underlying dictionary (only if the underlying dictionary was originally mutable).

2. Mutable to Immutable:

   • Use cf_mutable_dictionary.to_immutable() to get an immutable view of the same dictionary.

3. Untyped conversion:

   • to_untyped(): Returns a dictionary with types reset to *const c_void (increments retain count).
   • into_untyped(): Consumes the dictionary and returns an untyped version without incrementing the retain count (faster).

To change display settings (like mode, origin, or mirroring), you must follow a transactional pattern:

1. Begin a configuration session with begin_configuration() to get a CGDisplayConfigRef.
2. Apply changes (e.g., configure_display_with_display_mode, configure_display_origin, or configure_display_mirror_of_display) using the configuration reference.
3. Commit the changes using complete_configuration(config_ref, option).

If something goes wrong, use cancel_configuration(config_ref) to abort the changes.

CGConfigureOption values:

• ConfigureForAppOnly: Changes apply only to the current application.
• ConfigureForSession: Changes apply to the current user session.
• ConfigurePermanently: Changes are saved permanently.

A CFArray is a Core Foundation abstraction for an immutable, heterogeneous array. In core-foundation-rs, it is wrapped in a type-safe CFArray<T> struct.

Key Concepts

• Immutability: Once created, the array cannot be modified. To 'change' an array, you must create a new one.
• Type Safety: While the underlying Core Foundation array is heterogeneous (can hold any type), the Rust wrapper uses a phantom type T to provide type-safe access via ItemRef<'_, T>.
• Memory Management: The CFArray wrapper implements Drop to automatically call CFRelease when the object goes out of scope, following the Core Foundation 'Create Rule'.
• Conversion: You can transition between typed (CFArray<T>) and untyped (CFArray) states using to_untyped() or into_untyped() depending on whether you need to preserve the original instance.

When working with containers, the library provides ItemRef (for immutable access) and ItemMutRef (for mutable access) to represent references to elements inside a container. These types wrap the underlying data using ManuallyDrop to manage lifetimes safely.

They implement Deref and DerefMut respectively, allowing you to treat them like the underlying type.

The TCFType trait is the foundation of the library. Almost all Core Foundation types implement this trait. It provides a unified interface for interacting with Core Foundation objects, including:

• Type Identity: Check if an object is an instance of a type using instance_of::<T>() or get its type_id().
• Reference Management: Convert between wrapped types and raw TypeRefs using as_CFTypeRef(), as_CFType(), or into_CFType().
• Metadata: Retrieve the object's retain_count() or type_of() ID.
• Debugging: Use show() to write a debugging version of the object to standard error.