Why does `#import <HIToolbox/Events.h>` fail?

Question

I require kVK_Space which is in HIToolbox/Events.h:

#import <Carbon/Carbon.h>

works, and this file contains:

#include <HIToolbox/HIToolbox.h>

But if I try this second #include directly, it fails.

Can anyone explain why?

Answer 1

Carbon is an "umbrella framework". It encapsulates other frameworks, such as HIToolbox. By design, to hide the implementation details, you can't directly include the headers of the subframeworks.

From the above link:

[T]wo factors distinguish umbrella frameworks from other frameworks. The first is the manner in which they include header files.

Unlike standard frameworks, the Headers directory of an umbrella framework contains a more limited set of header files. It does not contain a collection of the headers in its subframeworks. Instead, it contains only the master header file for the framework. When referring to an umbrella framework in your source files, you should include only the master header file. See Including Frameworks for more information.

From that last link:

[I]f you are including an umbrella framework, you must include the master header file. Umbrella frameworks do not allow you to include the headers of their constituent subframeworks directly.