livecode/libscript/src/objc.lcb at develop-9.5 · livecode/livecode

This repository was archived by the owner on Aug 31, 2021. It is now read-only.
613 lines (469 loc) · 19.8 KB
/* Copyright (C) 2017 LiveCode Ltd.
 This file is part of LiveCode.
 LiveCode is free software; you can redistribute it and/or modify it under
 the terms of the GNU General Public License v3 as published by the Free
 Software Foundation.
 LiveCode is distributed in the hope that it will be useful, but WITHOUT ANY
 WARRANTY; without even the implied warranty of MERCHANTABILITY or
 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 for more details.
 You should have received a copy of the GNU General Public License
 along with LiveCode.  If not see <http://www.gnu.org/licenses/>.  */
This module provides utility handlers for converting to and from Obj-C types.
module com.livecode.objc
use com.livecode.foreign
public foreign type ObjcObject binds to "MCObjcObjectTypeInfo"
public foreign type ObjcId binds to "MCObjcIdTypeInfo"
public foreign type ObjcRetainedId binds to "MCObjcRetainedIdTypeInfo"
public foreign type ObjcAutoreleasedId binds to "MCObjcAutoreleasedIdTypeInfo"
private foreign handler MCStringCreateWithCFStringRef(in pNSString as ObjcId, out rString as String) returns CBool binds to "MCStringCreateWithCFStringRef"
private foreign handler MCStringConvertToCFStringRef(in pString as String, out rNSString as ObjcRetainedId) returns CBool binds to "MCStringConvertToCFStringRef"
Summary:    Convert a String into an Objective-C string
Parameters:
pString: The String to convert
A Objective-C object of type NSString
Description
Use <StringToNSString> to convert a variable of type String to an Objective-C
string object (NSString).
public handler StringToNSString(in pString as String) returns ObjcObject
	variable tNSString as ObjcRetainedId
		MCStringConvertToCFStringRef(pString, tNSString)
	end unsafe
	return tNSString
end handler
Summary:    Convert a Objective-C string into a String
Parameters:
pObjcString: The NSString to convert
A String value
Description
Use <StringFromNSString> to convert an Objective-C string object (NSString) to
a variable of type String.
public handler StringFromNSString(in pObjcString as ObjcObject) returns String
	variable tString as String
		MCStringCreateWithCFStringRef(pObjcString, tString)
	end unsafe
	return tString
end handler
private foreign handler MCDataCreateWithCFDataRef(in pNSData as ObjcId, out rData as Data) returns CBool binds to "MCDataCreateWithCFDataRef"
private foreign handler MCDataConvertToCFDataRef(in pData as Data, out rNSData as ObjcRetainedId) returns CBool binds to "MCDataConvertToCFDataRef"
Summary:    Convert a Data into an Objective-C data
Parameters:
pData: The Data to convert
A Objective-C object of type NSData
Description
Use <DataToNSData> to convert a variable of type Data to an Objective-C
data object (NSData).
public handler DataToNSData(in pData as Data) returns ObjcObject
	variable tNSData as ObjcRetainedId
		MCDataConvertToCFDataRef(pData, tNSData)
	end unsafe
	return tNSData
end handler
Summary:    Convert a Objective-C data into a Data
Parameters:
pObjcData: The NSData to convert
A Data value
Description
Use <DataFromNSData> to convert an Objective-C data object (NSData) to
a variable of type Data.
public handler DataFromNSData(in pObjcData as ObjcObject) returns Data
	variable tData as Data
		MCDataCreateWithCFDataRef(pObjcData, tData)
	end unsafe
	return tData
end handler
private foreign handler MCNumberCreateWithCFNumberRef(in pNSNumber as ObjcId, out rNumber as Number) returns CBool binds to "MCNumberCreateWithCFNumberRef"
private foreign handler MCNumberConvertToCFNumberRef(in pNumber as Number, out rNSNumber as ObjcRetainedId) returns CBool binds to "MCNumberConvertToCFNumberRef"
Summary:    Convert a Number into an Objective-C number
Parameters:
pNumber: The Number to convert
A Objective-C object of type NSNumber
Description
Use <NumberToNSNumber> to convert a variable of type Number to an Objective-C
number object (NSNumber).
public handler NumberToNSNumber(in pNumber as Number) returns ObjcObject
	variable tNSNumber as ObjcRetainedId
		MCNumberConvertToCFNumberRef(pNumber, tNSNumber)
	end unsafe
	return tNSNumber
end handler
Summary:    Convert a Objective-C number into a Number
Parameters:
pObjcNumber: The NSNumber to convert
A Number value
Description
Use <NumberFromNSNumber> to convert an Objective-C number object (NSNumber) to
a variable of type Number.
public handler NumberFromNSNumber(in pObjcNumber as ObjcObject) returns Number
	variable tNumber as Number
		MCNumberCreateWithCFNumberRef(pObjcNumber, tNumber)
	end unsafe
	return tNumber
end handler
private foreign handler MCProperListCreateWithCFArrayRef(in pNSArray as ObjcId, in pUseLists as CBool, out rList as List) returns CBool binds to "MCProperListCreateWithCFArrayRef"
private foreign handler MCProperListConvertToCFArrayRef(in pList as List, in pUseLists as CBool, out rNSArray as ObjcRetainedId) returns CBool binds to "MCProperListConvertToCFArrayRef"
Summary:    Convert a List into an Objective-C array
Parameters:
pNumber: The List to convert
A Objective-C object of type NSArray
Description
Use <ListToNSArray> to convert a variable of type List to an Objective-C
array object (NSArray).
public handler ListToNSArray(in pList as List) returns ObjcObject
	variable tNSArray as ObjcRetainedId
		MCProperListConvertToCFArrayRef(pList, true, tNSArray)
	end unsafe
	return tNSArray
end handler
Summary:    Convert a Objective-C array into a List
Parameters:
pObjcNumber: The NSArray to convert
A Number value
Description
Use <ListFromNSArray> to convert an Objective-C array object (NSArray) to
a variable of type List.
public handler ListFromNSArray(in pObjcArray as ObjcObject) returns List
	variable tList as List
		MCProperListCreateWithCFArrayRef(pObjcArray, true, tList)
	end unsafe
	return tList
end handler
private foreign handler MCArrayCreateWithCFDictionaryRef(in pNSDictionary as ObjcId, in pUseLists as CBool, out rArray as Array) returns CBool binds to "MCArrayCreateWithCFDictionaryRef"
private foreign handler MCArrayConvertToCFDictionaryRef(in pArray as Array, in pUseLists as CBool, out rNSDictionary as ObjcRetainedId) returns CBool binds to "MCArrayConvertToCFDictionaryRef"
Summary:    Convert an Array into an Objective-C dictionary
Parameters:
pNumber: The Array to convert
A Objective-C object of type NSDictionary
Description
Use <ArrayToNSDictionary> to convert a variable of type Array to an Objective-C
dictionary object (NSDictionary).
public handler ArrayToNSDictionary(in pArray as Array) returns ObjcObject
	variable tNSArray as ObjcRetainedId
		MCArrayConvertToCFDictionaryRef(pArray, true, tNSArray)
	end unsafe
	return tNSArray
end handler
Summary:    Convert a Objective-C dictionary into a Array
Parameters:
pObjcNumber: The NSDictionary to convert
An Array value
Description
Use <ArrayFromNSDictionary> to convert an Objective-C dictionary object (NSDictionary) to
a variable of type Array.
public handler ArrayFromNSDictionary(in pObjcArray as ObjcObject) returns Array
	variable tArray as Array
		MCArrayCreateWithCFDictionaryRef(pObjcArray, true, tArray)
	end unsafe
	return tArray
end handler
public handler type ObjcActionProxyHandler(in pSender as ObjcObject, in pContext as optional any) returns nothing
private foreign handler MCObjcObjectCreateActionProxy(in pHandler as optional any, in pValue as optional any) returns ObjcObject binds to "MCObjcObjectCreateActionProxy"
private foreign handler MCObjcObjectGetActionProxySelector() returns UIntPtr binds to "MCObjcObjectGetActionProxySelector"
public handler ObjcProxyGetTarget(in pHandler as ObjcActionProxyHandler, in pContext as optional any) returns ObjcObject
		return MCObjcObjectCreateActionProxy(pHandler, pContext)
	end unsafe
end handler
public handler ObjcProxyGetAction() returns UIntPtr
		return MCObjcObjectGetActionProxySelector()
	end unsafe
end handler
private foreign handler _MCObjcObjectCreateWithId_AsPointer(in pPointer as optional Pointer, out rObject as ObjcObject) returns CBool binds to "MCObjcObjectCreateWithId"
private foreign handler _MCObjcObjectGetId_AsPointer(in pObject as ObjcObject) returns optional Pointer binds to "MCObjcObjectGetId"
Summary:    Convert a Pointer into an ObjcObject
Parameters:
pPointer: The Pointer to convert
An ObjcObject wrapping the Pointer
Description:
Use <PointerToObjcObject> to convert a variable of type Pointer to one of type
ObjcObject.
public handler PointerToObjcObject(in pPointer as optional Pointer) returns optional ObjcObject
	variable tObject as optional ObjcObject
		_MCObjcObjectCreateWithId_AsPointer(pPointer, tObject)
	end unsafe
    return tObject
end handler
Summary:    Convert an ObjcObject into a Pointer
Parameters:
pObjcObject: The ObjcObject to convert
The Pointer wrapped by the ObjcObject
Description:
Use <PointerFromObjcObject> to convert a variable of type ObjcObject to one of
type Pointer.
public handler PointerFromObjcObject(in pObjcObject as ObjcObject) returns optional Pointer
	variable tPointer as Pointer
		put _MCObjcObjectGetId_AsPointer(pObjcObject) into tPointer
	end unsafe
	return tPointer
end handler
private foreign handler _MCObjcCreateDelegate(in pProtocol as String, in pHandlerMapping as Array, out rDelegate as ObjcObject) returns CBool \
    binds to "MCObjcCreateDelegate"
Create an Objective-C object with LCB implementations of methods of a protocol.
handler ControlIsValidObjectCallback(in pControl as ObjcId, in pObject as ObjcId) returns CSChar
    return 1
end handler
public handler GetNSControlTextEditingDelegate() returns ObjcObject
    return CreateObjcDelegate("NSControlTextEditingDelegate", \
                              { "control:isValidObject:": \
                                ControlIsValidObjectCallback })
end handler
Parameters:
pProtocol: The name of the protocol
pHandlerMapping: A mapping from the protocol's selector names to LCB handlers
Returns: An Objective-C object which calls the appropriate LCB handler
on receiving any of the specified selectors. 
Description:
Use the <CreateObjcDelegate> handler to create instances of Objective-C 
delegate classes with LCB implementations of protocol methods. Once 
created these can be set in the usual way on an instance of the 
appropriate class (by binding to `-setDelegate:`), typically so that 
callbacks triggered by user interaction with a widget can be handled in
If any context is required to be passed as a parameter to the callback,
use <CreateObjcDelegateWithContext>.
Some protocols consist of purely optional methods. In this case the 
information about the protocol's methods are not available from the     
objective-c runtime API. In this situation <CreateObjcInformalDelegate> 
should be used instead.
References:
CreateObjcDelegateWithContext (handler), 
CreateObjcInformalDelegate (handler), 
CreateObjcInformalDelegateWithContext (handler)
public handler CreateObjcDelegate(in pProtocol as String, in pHandlerMapping as Array) returns optional ObjcObject
        variable tObj as ObjcObject
        if _MCObjcCreateDelegate(pProtocol, pHandlerMapping, tObj) then
            return tObj
        end if
        return nothing
    end unsafe
end handler
private foreign handler _MCObjcCreateDelegateWithContext(in pProtocol as String, in pHandlerMapping as Array, in pContext as optional any, out rDelegate as ObjcObject) returns CBool \
    binds to "MCObjcCreateDelegateWithContext"    
Create an Objective-C object with LCB implementations of methods of a protocol.
handler NumberOfItemsInMenuCallback(in pContext as String, in pMenu as ObjcId) returns CLong
    -- pContext is the tag for this menu
    return the number of elements in mMenuArray[pContext]
end handler
public handler GetNSMenuDelegate(in pMenuTag as String) returns ObjcObject
    return CreateObjcDelegateWithContext("NSMenuDelegate", \
                                           { "numberOfItemsInMenu:": \
                                           NumberOfItemsInMenuCallback }, \
end handler
Parameters:
pProtocol: The name of the protocol
pHandlerMapping: A mapping from the protocol's selector names to LCB handlers
pContext: Any context required in the callback.
Returns: An Objective-C object which calls the appropriate LCB handler
on receiving any of the specified selectors. 
Description:
Use the <CreateObjcDelegateWithContext> handler to create instances of 
Objective-C delegate classes with LCB implementations of protocol 
methods. Once created these can be set in the usual way on an instance 
of the appropriate class (by binding to `-setDelegate:`), typically so 
that callbacks triggered by user interaction with a widget can be
handled in LCB.
If no context is required to be passed as a parameter to the callback,
use <CreateObjcDelegate>.
Some protocols consist of purely optional methods. In this case the 
information about the protocol's methods are not available from the     
objective-c runtime API. In this situation 
<CreateObjcInformalDelegateWithContext> should be used instead.
References:
CreateObjcDelegate (handler), CreateObjcInformalDelegate (handler), 
CreateObjcInformalDelegateWithContext (handler)
public handler CreateObjcDelegateWithContext(in pProtocol as String, in pHandlerMapping as Array, in pContext as any) returns optional ObjcObject
        variable tObj as ObjcObject
        if _MCObjcCreateDelegateWithContext(pProtocol, pHandlerMapping, \
                                           pContext, tObj) then
            return tObj
        end if
        return nothing
    end unsafe
end handler        
private foreign handler _MCObjcCreateInformalDelegate(in pProtocol as List, in pHandlerMapping as Array, out rDelegate as ObjcObject) returns CBool \
    binds to "MCObjcCreateInformalDelegate"
Create an Objective-C object with LCB implementations of methods of an informal protocol.
foreign handler Objc_NSPortMessageGetMsgId(in pMessage as ObjcId) returns UInt32 \
    binds to "objc:NSPort.-msgid"
handler HandlePortMessageCallback(in pMessage as ObjcId) returns nothing
    post "portMessage" with [Objc_NSPortMessageGetMsgId(pMessage)]
end handler
foreign handler Objc_NSPortDelegateHandlePortMessage(in pTarget as ObjcId, in pPortMessage as ObjcId) returns nothing \
    binds to "objc:.-handlePortMessage:"
public handler GetNSPortDelegate()
    return CreateObjcInformalDelegate([Objc_NSPortDelegateHandlePortMessage], \
                                      { "handlePortMessage:": \
                                        HandlePortMessageCalback })
end handler
Parameters:
pProtocol: A list of foreign handlers which bind to protocol methods
pHandlerMapping: A mapping from the protocol's selector names to LCB handlers
Returns: An Objective-C object which calls the appropriate LCB handler
on receiving any of the specified selectors. 
Description:
Use the <CreateObjcInformalDelegate> handler to create instances of 
Objective-C delegate classes with LCB implementations of protocol 
methods, when the Protocol object cannot be found at runtime. This 
occurs for example when all of the protocol methods are optional. 
Instead of a protocol name (as with <CreateObjcDelegate>), the 
<pProtocol> argument of <CreateObjcInformalDelegate> must be a proper 
list of foreign handlers for each of the methods of the protocol for 
which LCB callbacks are provided in the <pHandlerMapping> array.
Once created an informal delegate can be set in the usual way on an 
instance of the appropriate class (by binding to `-setDelegate:`), 
typically so that callbacks triggered by user interaction with a widget 
can be handled in LCB.
If any context is required to be passed as a parameter to the callback,
use <CreateObjcInformalDelegateWithContext>.
If the protocol can be resolved at runtime, it is generally easier to 
use the <CreateObjcDelegate> handler.
References:
CreateObjcDelegate (handler), CreateObjcDelegateWithContext (handler), 
CreateObjcInformalDelegateWithContext (handler)
public handler CreateObjcInformalDelegate(in pProtocol as List, in pHandlerMapping as Array) returns optional ObjcObject
        variable tObj as ObjcObject
        if _MCObjcCreateInformalDelegate(pProtocol, pHandlerMapping, \
            return tObj
        end if
        return nothing
    end unsafe
end handler    
private foreign handler _MCObjcCreateInformalDelegateWithContext(in pProtocol as List, in pHandlerMapping as Array, in pContext as optional any, out rDelegate as ObjcObject) returns CBool \
    binds to "MCObjcCreateInformalDelegateWithContext"    
Create an Objective-C object with LCB implementations of methods of an informal protocol.
foreign handler Objc_NSPortMessageGetMsgId(in pMessage as ObjcId) returns UInt32 \
    binds to "objc:NSPort.-msgid"
handler HandlePortMessageCallback(in pPortIndex as Integer, in pMessage as ObjcId) returns nothing
    post "portMessage" with [mPortList[pPortIndex]["name"], \
                             Objc_NSPortMessageGetMsgId(pMessage)]
end handler
foreign handler Objc_NSPortDelegateHandlePortMessage(in pTarget as ObjcId, in pPortMessage as ObjcId) returns nothing \
    binds to "objc:.-handlePortMessage:"
public handler GetNSPortDelegate(in pPortIndex as Integer)
    return CreateObjcInformalDelegateWithContext([Objc_NSPortDelegateHandlePortMessage], \
                                                 { "handlePortMessage:": \
                                                   HandlePortMessageCalback }, \
end handler
Parameters:
pProtocol: A list of foreign handlers which bind to protocol methods
pHandlerMapping: A mapping from the protocol's selector names to LCB handlers
Returns: An Objective-C object which calls the appropriate LCB handler
on receiving any of the specified selectors. 
Description:
Use the <CreateObjcInformalDelegateWithContext> handler to create instances of 
Objective-C delegate classes with LCB implementations of protocol 
methods, when the Protocol object cannot be found at runtime. This 
occurs for example when all of the protocol methods are optional. 
Instead of a protocol name (as with <CreateObjcDelegateWithContext>), 
the <pProtocol> argument of <CreateObjcInformalDelegateWithContext> must 
be a proper list of foreign handlers for each of the methods of the 
protocol for which LCB callbacks are provided in the <pHandlerMapping> 
Once created an informal delegate can be set in the usual way on an 
instance of the appropriate class (by binding to `-setDelegate:`), 
typically so that callbacks triggered by user interaction with a widget 
can be handled in LCB.
If no context is required to be passed as a parameter to the callback,
use <CreateObjcInformalDelegate>.
If the protocol can be resolved at runtime, it is generally easier to 
use the <CreateObjcDelegateWithContext> handler.
References:
CreateObjcDelegate (handler), CreateObjcDelegateWithContext (handler), 
CreateObjcInformalDelegate (handler)
public handler CreateObjcInformalDelegateWithContext(in pProtocol as List, in pHandlerMapping as Array, in pContext as any) returns optional ObjcObject
        variable tObj as ObjcObject
        if _MCObjcCreateInformalDelegateWithContext(pProtocol, \
                                                   pHandlerMapping, \
            return tObj
        end if
        return nothing
    end unsafe
end handler    
Navigation Menu

Uh oh!

Uh oh!

FilesExpand file tree

objc.lcb

Latest commit

History

objc.lcb

File metadata and controls
