Declare

From Real Software Documentation

Used to make API calls. Both PPC and x86 machines are supported. DLLs can be called from a built Windows application. Shared libraries can be called from Macintosh and Linux applications.

Syntax

[Soft] Declare Sub/Function Name Lib LibraryName [Alias AliasName] [selector theSelector] ([Parameters]) [As ReturnType]

Part	Type	Description
Name	Name	Name of the API call. Use Name in your code to refer to the API call.
LibraryName	String	Library in which API call is found.
AliasName	String	Optional: If the API call has the same name as a Real Studio method, declare the call with a different name and use the alias to refer to the actual API call.
Selector	String	Mac OS X only: the parameters separated with a colon (but no space) to uniquely identify a Cocoa method. This is mutually exclusive with the "Alias" clause. For example: "addSubview:" like in: declare sub addSubview lib "Cocoa" selector "addSubview:" ( NSView as integer, subview as integer )
Parameters Changed 2005r1		The parameters of the API call. You can pass Nil to a parameter of type Ptr.
ReturnType		Optional: The data type of the value returned by the call if it is a function.

Notes

Function names for the OS are case-sensitive. For example, SetLocalTime works on Win32 but SetlocalTime does not.

Declare statements must not call strictly “classic” libraries like AppearanceLib to run on Mac OS X.

The Declare statement allows use of constants for Lib names.

The Declare statement can be used to call external functions that return structure values.

When building a Carbon application in the Mach-O format, the Lib parameter to a Declare statement now accepts the name of a system framework in place of a full path to the library. If you wrote a declare against "CoreMIDI", for example, the compiler would see that the Lib string did not contain any path separators, and would expand it to "/System/Library/Frameworks/CoreMIDI.framework/CoreMIDI".

You can pass Nil to a Declare parameter of type Ptr. Passing Nil is not the same as passing a Nil MemoryBlock. The former is a constant and the latter require a conversion operation at run time. If the MemoryBlock is Nil, then the conversion operator will generate a NilObjectException. However, this isn't a problem when passing the constant Nil, as no conversion is needed.

Soft Declares

In versions of Real Studio prior to 2005, the only supported type of declares was a “hard” declare. A hard declare of the form:

tells Real Studio that Foo will always be in Bar, and Bar will always be installed on the user’s system. When building your application, Real Studio puts this dependency in your application’s Import table. When the system loader tries to load your application, it will automatically find all of these Declares and try to resolve them. If it can’t resolve a library or a function from a library, your application would refuse to load and terminate.

The Soft Declare keyword provides some important flexibility. Soft declares are not put into your application’s import table so the system loader doesn’t try to resolve them. Instead, when you first try to use the softly declared method, Real Studio is responsible for resolving the library and functions. This provides you with a few handy features.

First, it means that you now have a graceful way to deal with the situation of a function or library that isn&rsuo;t found. Instead of your application just not launching, you now have a FunctionNotFound exception that you can catch. Second, Real Studio can be more flexible about loading the library.

For example, LibC on many newer Linux distributions is really a ld loader script that GCC uses to determine which version of LibC to actually link against. This means that you can't write hard declares that link against LibC in Real Studio because libc.so isn't really a symbolic link to the proper shared library (like most other .so files are). You would have to write a Declare against the actual LibC version you wanted, which provides for a very poor experience for users who don't have the same version of LibC installed as you. However, with a soft declare, Real Studio can resolve the loader script for LibC and find the proper shared library to load against In other words, what used to be declared like this:

Can now be declared like this:

With the Soft keyword, you don't have to try to link against a specific version of that library.

On Windows, any function that uses a string will have two different versions, the A version, and the W version. This is the Win32 way of dealing with Unicode. The disadvantage is that the W version of the method is usually available only on Windows NT machines, not 9x ones. If you could not use a Soft declare, you'd have to make two different versions of your application. Using Soft declares, you can do this:

This code runs on any version of Windows. The reason is simple: if the wide char version (W version) is available, then your call will not throw an exception, and because of the WString data type, all your strings will be automatically converted into UTF-16 strings when passed into the function.

Note: On OS X Cocoa, all Cocoa declares are "soft"; there is no need to explicitly specify it.

Checking that a Function is Available

To check whether a function can be resolved, you can use the IsFunctionAvailable function of the System module. It determines whether a function can be resolved without having to actually declare it and try to call into it.

Data Types

The following data types are for use with Declares:

Type	Description
Byte	Unsigned 8-bit integer.
CFStringRef	A CFString reference. Note that framework will attempt to automatically manage the memory of the CFStringRef based off of the CoreFoundation naming rules (and Objective-C naming rules if it is an Objective-C declare). If the framework does not get this right, you can manually manage the reference counting with CFRetain/CFRelease.
CString	A null-terminated string.
OSType	A four char code.
PString	A "Pascal" string.
Ptr	4-byte pointer to memory.
Short	2-byte signed integer.
UByte	Unsigned 8-bit integer.
UShort	Unsigned 2-byte integer.
WindowPtr	4-byte integer to a handle
WString	A UTF-16 string.

See the descriptions of each data type for more information.

Automatic Types

There are two new automatic types: WString and CFStringRef. You can pass Nil in place of a CString, WString, CFStringRef, or PString.

You can use these two new types with declares that need a wchar_t * or CFStringRef, respectively. Their usage is the same as with CString, and all data is cleaned up when appropriate. For example:

Examples

Name Conflicts

Suppose you want to write a function that got the various system metrics. You use a method declaration like this:

However, this conflicts with the Win32 API which the function wraps. In this case, you can rename the declare using an alias such as this:

Defining Double-clicks

The following example displays the maximum number of ticks between mouse clicks for two clicks to be considered a "double-click." Above this value, two clicks are considered separate mouse events.

The following example gets the current process ID and illustrates soft declares for Mac OS, Windows, and Linux. In addition, it illustrates the use of the Alias parameter to set the name of the declared function to the same value for all platforms.

The following example adds the ability to detect a double-click to a Canvas control. The code is placed in a Canvas's MouseUp event handler.

Cocoa Declare and CocoaObject Examples

The Cocoa Declare project in the Examples folder that ships with Real Studio has several examples of calls to NSWindow methods. Calls for both Soft Declares and hard declares are included. Whether to use the Soft Declare version is controlled by the value of the UseCocoaObj radio button (top-right corner of the window). Each event handler includes both types of calls.

Centering a Window

Centers the window to draw attention to it.

Miniaturizes the window to the Mac OS X Dock

Move

Moves the window to the top of the screen and provides smooth animation of the process.

Color

Displays the Color Picker so you can set the background color of the window.

Background Transparency

This method uses a Slider to set the transparency level of the window.

Dragging the window by the title bar

This checkbox controls whether or not the setMovable flag is set.

Window can be dragged via the background

If this checkbox is disabled and the first checkbox is enabled, then the window can only be dragged by the title bar. It it is also enabled, then the window can also be dragged by the surface of the window.

See Also

TargetCarbon, TargetCocoa, TargetLinux, TargetMacOS, TargetMachO, TargetWin32 constants; System module, FunctionNotFound exception; Byte, CFStringRef, CString, ObjCException, OSType, PString, Ptr, Short,UShort, WindowPtr, WString data types.