LCB public handler definitions

Handler definitions are used to define functions which can be called from LiveCode Builder code, invoked as a result of events triggering in a widget module, or called from LiveCode Script if public and inside a library module.

There is no distinction between handlers which return a value and ones which do not, apart from the return type.

Definitions can be either public or private (the default is private). Private handlers can only used within the module. Public handlers are available when the module is used by another module, for example public handlers can be called from LiveCode Script.
Handler definitions have the form

<HandlerType> handler <HandlerName>(<ParameterList>) [ returns <ReturnType> ]

end handler

The sayHello handler

The Hello World Library has one handler which returns the string “Hello World!”.
Add the definition for the sayHello handler to the library.

library community.livecode.elanorb.helloworld

public handler sayHello()

end handler

end library

Let’s break down the definitions

• HandlerType – public: we want to be able to call this handler from LiveCode Script so it needs to be public
• HandlerName – sayHello: the name of the handler, used to call the handler from LiveCode Script
• ParameterList – empty, no parameters are passed in

Case Sensitivity in LiveCode Builder

At the moment, due to the nature of the parser being used, keywords are all case-sensitive and reserved. The result of this is that, using all lower-case identifiers for names of definitions should be avoided. However, identifiers are case-insensitive – so a variable with name pFoo can also be referenced as PFOO, PfOO, pfoO etc.

It is highly recommended that the following naming conventions be used for identifiers:

• tVar – for local variables
• pVar – for in parameterns
• rVar – for out parameters
• xVar – for inout parameters
• mVar – for global variables in widgets
• sVar – for global variables in libraries
• kConstant – for constants
• Use identifiers starting with an uppercase letter for handler and type names.

By following this convention, there will not be any ambiguity between identifiers and keywords. (All keywords are all lower-case).

For more on this see the LiveCode Builder Language Reference guide in the Dictionary or Additional Resources section.

Returning a string

To return a string value we can return the string directly.
Add a return statement to the sayHello handler.

library community.livecode.elanorb.helloworld

public handler sayHello()
   return "Hello World!"
end handler

end library