Xojo Documentation for Declare

General
1

I searched in the Documentation the entries for Declare (say for macOS…), but only found the useless:
Calling native macOS APIs

Then, I searched in the Examples:Declare…

Same useless example.

Why do I say these are useless ?

You do not read an explanation that allows you to start with the macOS documentation and translate that for use in Xojo…

Oh, yes, one can buy Add-On Plug-In, or How do I… or Read xDev or…

From the Roadmap document, Delivered section, we can read:

2022r1
New documentation system
Documentation available in an updated, modern format.

This (Marketing sentence) have to be translated (for customer reading) as “new documentation presentation / same contents”.

Of course, I recall “Inside Mac”… so many changes since then have been done.

Am I wrong ? If so, a link to the new Xojo documentation talking about translating OS Declare to Xojo is welcome.

2

Hi @Emile_Schwarz

The documentation page you refer also points to these additional resources (besides the macOSLib project, whose code you may want to inspect in order to learn more about how declares work):

I hope these helps you!

3

Do the Declare method names have to be the same as the Selector string? If so, why? If not, it would make things clearer if names like “mySub” were used in the examples to make it clear what the we can choose to suit sourselves and what is fixed.

4

No. Here’s the way typical macOS declares are:

Declare Sub NameForXojo Lib "Foundation" Selector "selector:Name:From:Apple:" (obj as Ptr)

Declare Function NameForXojo Lib "Foundation" Selector "selector:Name:From:Apple:" (obj as Ptr) as Ptr

1 Like
5

AFAIK “Selector” is only required for “Objective” API, regular flat API doesn’t need it.
The names do not have to match.

declare sub NSObject_release lib Foundation.kLibrary selector "release" ( NSObjectInstance as integer ) // --- This is Objective API.
declare sub CGImageRelease   lib CoreGraphics.kLibrary                  ( CGImagePtr as ptr )           // --- This is flat API.
6

I left out some parts as to why my declares look different from others.

I personally use className_message for Objective API as this means when I need to look up that API, I get the correct one and when using it in code, it calls the correct API.

I use classNameInstance or classNameClass for property names as this helps remind me what the parameter types need to be. The idea is to spend a little more time when writing the declare, will save time when you need to re-use it 1, 2, 5 or even 10 years later.

Finally I try to either comment in-line declares or add to the “Description” of external method, the minimum OS version that the API works on.

I also prefer NOT to hardcode library names as there have been times when Apple has changed the name of framework you link against, so during a “transition” period, I might make a whole block of declares link against “Cocoa” until my apps minimum version means there’s only one framework I need to worry about, hence why I use constants.

While there are those on this very forum who just think I’m being <insertWordHere/>, these have all come from the experience of working with Xojo declares and Apple’s API for 15 or so years.

2 Likes