Simple (I think) question about declares

Lot’s of people shy aware from declares because there aren’t a lot of good examples or tutorials on how they work. People just tend to cut and paste examples and hope for the best.

I’m trying to wrap my head around them more clearly (I might even get round to writing a 101 if I succeed) but I have a few simple (macOS) declare-related questions:

Getting an instance

Am I right in thinking that this code will get a pointer to a new instance of a class with the specified name. For example, passing “NSColor” as the string will give me back a pointer to a new instantiated NSColor, right?

Declare Function NSClassFromString Lib "AppKit" (className As CFStringRef) As Ptr
Var newInstance = NSClassFromString("NSColor")


The Xojo docs give examples of calling functions and subroutines using declares but not specifically accessing the property of an external class. Am I right in thinking that the general approach is to get an instance of a class (for example, using the NSClassFromString() function above and then pass that pointer to another declare whose selector is the name of the property to access?

For example, I currently use this declare in my code (so I know it works). Behind the scenes, is it essentially saying “return to me the NSColorInstance.redComponent value”:

Declare Function NSClassFromString Lib "AppKit" (className As CFStringRef) As Ptr
Var newInstance = NSClassFromString("NSColor")

// Get a property value from newInstance
Declare Function getRedComponent Lib "AppKit" selector "redComponent"(instance As Ptr) As CGFloat
Var red As Integer = getRedComponent(newInstance)

Memory management

Are there any memory management issues I need to be aware of when messing around with declares? I choose Xojo because it abstracts memory management away but I’m concerned about memory leaks with declares. What happens to these pointers to NSColor objects when I’m done with them? Are they freed by Xojo in the normal way?

  1. Documentation of the functions, enums and properties is found here.

  2. Enable crash on NSException, so when you get it wrong, it will tell you where. The init method of the Ohanaware App Kit will enable this option for you. Otherwise there’s some suggestions here for alternatives.

  3. Learn to read Objective-C or Swift, so you can take advantage of sample code on the internet, to understand how to use a function.

This gets the Ptr to the NSColor class, it doesn’t create a new instance of the class. You create an instance by calling a factory method on a class (or by allocating memory and using a class constructor). In the header files, class functions (not instance functions) are marked with “+” in front of the name.
+ (NSColor *)colorWithWhite:(CGFloat)white alpha:(CGFloat)alpha API_AVAILABLE(macos(10.9));

*note: not all class functions are factory functions. The header files will tell you which ones are.

Yes. Looking at NSColor.h, it says.
@property (readonly) CGFloat redComponent; // Valid only on component based colors whose colorSpace model is NSColorSpaceModelRGB.

Xojo make memory management way tooooooo easy! If you continue down this rabbit hole, you’re going to learn about Memory Management!

There’s many rules, but in principle, these are the basics.

  1. A factory function, like + (NSColor *)colorWithWhite:(CGFloat)white alpha:(CGFloat)alpha will return an object that is Auto Released. Which means, you can use it in a function and at the end of the run loop, the OS will release it for you.
  2. If you want to store that object for use later, you need to “Retain” it and “Release” it when you’re finished.
  3. Constructors (which usually start with init) require you to allocate the memory for the ptr before hand. You’re also responsible for releasing the memory on completion.
1 Like

I’d also grab the old versions of MACOSLib from

and focus on charles code (not a lot of the other cruft that crept in)

It has a very distinct style
But, correct me if I’m wrong @samRowlands , that he also notes the ownership rules etc that must be followed and does so quite well (personally its a good example of declares done well)

1 Like

I swear I read somewhere that macOS is 32-bit only? I guess I’m mis-remembering.

Awesome info @samRowlands - it’s a real help. Thanks.

1 Like

Sorry, don’t 100% understand, are you asking me if the macOSLib explains ownership rules of NSObjects?

Read the headers while you can, swift doesn’t use 'em so eventually they’ll go away and we’ll be left with Apple’s web documentation, which often results in “no overview available”. The headers also list enums in order, which is vital for using them with Xojo.

more or less yes
Charles macOSLib does implement the ownership and I think he even has notes about it in the code

there are some 64 bits variants out there

1 Like

yeah I just wish so many hadnt forked and started their own repos and had pushed their stuff back into the main one