Some fundamental concepts

[uelandbob]

I'm trying to understand the vocabulary of LC. Fundamental concepts like object, system, message, system message, command script, handler. I get little confused because different people use it little differently . So I attempted to make clear distinctions looking back at some early work from Dan Winkler, the creator of HyperTalk.

Definition: An object is any unit capable of sending and receiving messages.

* An object has also properties. Exactly which properties it has is determined by the type of the object. An object can be a button, a text field, a card, etc.

Definition: Although the LiveCard engine is capable of sending and receiving messages, we will not include it in our definition of objects. Instead we will consider it a special kind of object called the system.

* Although Dan Winkler considered the system (aka the engine) to be an object, I think we should exclude it. One reason is that the system is the most important object defining the language itself, and the other reason is that we can't edit or see its handlers, as we can with all other objects. So it is fundamentally different from all the other normal "objects".

Definition: A message is an instruction that can be sent from one object to another.

Definition: A system message is message that LC engine (system) sends to some object. A command (aka command message) is a message that an object sends to the system.

* Dan Winkler reserved the word command for a message sent to the system. I have seen that many people call the message handlers (see below) commands. That is confusing and I think we should try to avoid it. But I'm not dogmatic about it and willing to listen to any reasonable arguments.

Definition: A system function is message an object can sends to the system and get a return value back.

Definition: A script is collection of handlers associated with an object.

Definition: A handler is named collection of statements. When the objects receives a message that corresponds to the name of the handler, it executes the statements within the handler. There are two types of handlers, function handlers and message handlers. Function handlers return a value, but message handlers do not. (In LiveCode there are actually four type of handlers, getProp handlers and setProp handlers for handling custom properties.)

* It is the message handlers that are fundamental. Function handlers are handlers that are in service of the message handlers. The reason is that system sends messages to message handlers, but it never sends messages to function handlers.

[richmond62]

Sounds very complicated to me.

I just get on and make things with Livecode.

AND . . . my experience with children (7-12 year olds) learning Livecode is to put a load of cups on a table: point out that many of the cups can
have bigger cups inside them, and those, and the bigger cups can also have interesting things such as buttons in them.

After about 15 minutes of that I start writing messages on slips of paper, dropping them into cups, and them moving them between cups.

If it works for kids, why over complicate things with fancy termonology?

[FourthWorld]

That's a very good summary. In some respects it's similar to the opening section of the User Guide's "Getting Started" chapter (p36), but the bullet-point outline form may be especially useful for some learners.

[dunbarx]

Hi.

I saw your YouTube Video. Nice job. You were a HC fan?

In your text:

- You might think of the terms "Control" and "Object" to distinguish between, say, engines and buttons, or buttons and cards.
- I would not call a "message" an "instruction". It is what it is, a message.
- Do you think it a good idea to have a "system message" go from the engine to an object, whereas a "system function" go from an object to the engine?
- A script is a property of an object. It may contain text. It is no different a property than, say, the text of a field.
- Note that commands can indeed return a value to a handler that called another handler. You use the "return" command.

What sorts of confusion are you having with the current definitions? Anyway, this discussion may be very useful if it creates new and better teaching resources.

Craig

[uelandbob]

In some respects it's similar to the opening section of the User Guide's "Getting Started" chapter (p36), but the bullet-point outline form may be especially useful for some learners.

Thank you Richard, always learning something from you I must get it into my head to always look up first and foremost what the User Guide says. Here is the relevant quote from p36.

A LiveCode application is driven by user actions. LiveCode constantly watches the computer for common actions, such as clicking on a button, typing into a field, sending data across a network, or quitting an application.
Whenever an event occurs, LiveCode sends a message. When writing your program, you decide what messages you want your program to respond to. LiveCode automatically sends each message to the most relevant object. For example, if a user clicks on a button, LiveCode sends a message to the button. You place code within the button that tells it how to respond to being clicked on.

It talks about events and messages. But it doesn't explicitly mention system messages and system commands and many of the other concepts that I've mentioned in my post. The distinction between system commands and message handlers is not made in User Guide, in fact on p123, message handlers are called commands.

Well probably you think I'm picking the details, but Dan Winkler was very precise with his use of concepts and I too think it is important to be clear on that front, probably because I am a teacher and a mathematician. Others don't bother with terminology, and I'm Ok with that.

[FourthWorld]

It talks about events and messages. But it doesn't explicitly mention system messages and system commands and many of the other concepts that I've mentioned in my post.

In that high-level introduction they don't get into much detail, instead referencing at the bottom of that section 2.1.2 that further details are provided in the "Coding in LiveCode" chapter.

The distinction between system commands and message handlers is not made in User Guide, in fact on p123, message handlers are called commands.

That may just be a subtlety they chose not to address, focusing on the mechanics of usage instead. After, the structure of a message handler is the same whether the message came from the engine or another script:

Code: Select all

on HandlerName
   SomeStatements
end HandlerName

Well probably you think I'm picking the details, but Dan Winkler was very precise with his use of concepts and I too think it is important to be clear on that front, probably because I am a teacher and a mathematician. Others don't bother with terminology, and I'm Ok with that.

I think it's very useful for all of us to constantly reevaluate the learning process and its supporting materials. I've never seen perfect docs; all leave room for improvement.

I can't tell you how many hours I spent trying to figure out how to create a field dynamically from a script back in my early HyperCard days, and ultimately the answer I found wasn't in Apple's docs at all, but in a third-party book (Goodman's). It may well have been addressed in HC's Help but I couldn't find it there, whereas Goodman's index was a godsend for me.

In some respects, Winkler/Kamins/DeVoto (and incidentally, Jeanne DeVoto helped create much of LiveCode's Dictionary content) had a relatively easy job compared to LC, given the scope of the latter's language. Not only does LC provide a wide range of things we'd only dreamed about in HC (custom properties, arrays, integrated color, integrated window styles. and so much more), but it has to provide all this across seven platforms, each of which has its own nuances and feature options.

Custom properties alone add a tremendous amount of new concepts to the language, including two message handler types not found in HC, getProp and setProp.

Given the sheer volume of material to be covered, focusing on the mechanics may not be a bad move, esp. when supplemental detail is provided such as Section 5.2.1's "What Causes Messages to be Sent?".

This volume of material is about to get even larger as LiveCode moves xTalk into bold new uncharted territory with Version 8.0 - for a glimpse of what's coming see this video Kevin put together on the company blog:
http://livecode.com/blog/2014/07/08/the ... ts-themes/

While the new features RunRev's Open Language initiative delivers are profoundly valuable, we all recognize the risks to the learning curve. Hopefully, that's where you come in, if you have time and interest:

For v8 LiveCode is undergoing a complete overhaul to the documentation. Some of these moves are described in this blog post by RunRev's Elanor Buchanan:
http://livecode.com/blog/2014/11/18/mar ... ser-guide/

The level of effort needed to complete these revisions is more than the company can pull off by itself, so some of us in the community are forming a Community Documentation Team to lend a hand with this effort.

The project lead for this Community team is Dan Shafer - yes, that Dan Shafer. Jeanne DeVoto is also on the team, and we have about half a dozen others who've signed up to participate.

If contributing to this volunteer community effort appeals to you, feel free to drop me an email at richard@livecode.org and I'll make sure you're included as we kick off the project.

Alternatively, we're seeing rapid growth among third-party learning resources from LiveCode, including many new books. If you choose to help folks learn LiveCode through your own independent projects, I'd be happy to help promote them where I can.

[uelandbob]

Thank you Craig, this was just the type of feedback I was hoping for

You were a HC fan?

I was and I still am

- You might think of the terms "Control" and "Object" to distinguish between, say, engines and buttons, or buttons and cards.

I realize that there are control objects like buttons and text fields and objects like cards and stacks that are not controls. I do think though that it is useful to distinguish between the objects (be it controls or not) and the engine itself.

- I would not call a "message" an "instruction". It is what it is, a message.

I am quoting from Winkler's book
"An object executes the statements within one of its handlers when it receives an instruction to do so. That instruction is called a message."

- Do you think it a good idea to have a "system message" go from the engine to an object, whereas a "system function" go from an object to the engine?

You've got me there . It is not a good idea, I admit that. Look at these two messages sent from an object to the engine
put "Hello World" into msg
put the date into msg

The first is a command. The second is what?

- A script is a property of an object. It may contain text. It is no different a property than, say, the text of a field.

I agree, a script is a property. But it is a special kind of property, in that that it contains handlers that define what the object shall do when it receives messages sent to it.

- Note that commands can indeed return a value to a handler that called another handler. You use the "return" command.

Do you mean that they return the value in the global variable the result? Or do you mean something else? Can you give an example.

What sorts of confusion are you having with the current definitions?
Craig

I am confused that commands and message handlers are called the same thing, see page 123 in User Guide. I am also confused when there is no clear distinction between the engine and the other objects. I think that distinction is important.

[jacque]

I think it is important to note that LiveCode is not HyperCard, and some of the HC documentation is not exactly how we use the same terms today. They are close, but terminology has evolved. Winkler's definitions are useful in a broad sense but I'm not sure they are definitive any more.

Definition: A system message is message that LC engine (system) sends to some object. A command (aka command message) is a message that an object sends to the system.

* Dan Winkler reserved the word command for a message sent to the system. I have seen that many people call the message handlers (see below) commands. That is confusing and I think we should try to avoid it. But I'm not dogmatic about it and willing to listen to any reasonable arguments.

We use "command" to mean any instruction in the broadest, umbrella sense. A single word in the dictionary can be a command, we "send commands" (meaning both commands and functions,) and so forth. It's a generic term so we don't have to say "commands and functions and messages" all the time. Commands (and functions and messages) are not sent only to the engine, they can be sent to any object or just pushed into the message path without any object/target at all.

Definition: A system function is message an object can sends to the system and get a return value back.

True, though I usually include all messages, not just functions. I do use the term "system messages." It's interesting though, when I used it with the chief engineer at RR he had no idea what I meant and asked me twice to define it. He didn't agree with my definition. To him, messages are just instructions that flow freely and originate anywhere. He uses "system" only to refer to the OS. He does not discriminate about where the message comes from or is going to.

Definition: A script is collection of handlers associated with an object.

Usually. But then there are front and backscripts that just kind of hang around in the message path.

Definition: A handler is named collection of statements. When the objects receives a message that corresponds to the name of the handler, it executes the statements within the handler. There are two types of handlers, function handlers and message handlers. Function handlers return a value, but message handlers do not. (In LiveCode there are actually four type of handlers, getProp handlers and setProp handlers for handling custom properties.)

At least one copy of the documentation (I've lost track) refer to the two types of handlers as "function handlers" and "command handlers." I believe that's the common terminology LC uses. A message handler would be any type of handler, since both commands and functions send or receive messages. And as Craig pointed out, command handlers can also return values.

* It is the message handlers that are fundamental. Function handlers are handlers that are in service of the message handlers. The reason is that system sends messages to message handlers, but it never sends messages to function handlers.

To be picky, the engine does not send its messages to objects specifically. It pushes them into the message path according to a pre-defined hierarchy and they travel from there. The engine produces a constant flow of event messages which may or may not affect any object in its path.

[Klaus]

Hi Bob,

did you actually create something with Livecode so far or are you only trying to write a book about it?
Which I estimate to be finished with your 50th posting.

Sorry, just kidding...


Best

Klaus

[FourthWorld]

- A script is a property of an object. It may contain text. It is no different a property than, say, the text of a field.

I agree, a script is a property. But it is a special kind of property, in that that it contains handlers that define what the object shall do when it receives messages sent to it.

FWIW, supporting the view that a script is a special property, it's not among the elements returned from the properties function.

- Note that commands can indeed return a value to a handler that called another handler. You use the "return" command.

Do you mean that they return the value in the global variable the result? Or do you mean something else? Can you give an example.

We're stepping into dangerous territory here, possibly more contentious than the age-old division in our community between those who draw message path diagrams from the top down and those who draw them from the bottom up.

Pascal and xTalk are among a relatively small number of languages that distinguish between functions and commands, while C, JavaScript, and most others have only functions.

In xTalk both commands and functions can return a value, but functions will always return a value whereas with commands a return value is optional and requires a separate query to "the result" to obtain.

In other languages functions are expected, if not required, to return a value, even if it's NULL.

Whether it's best to have two types of handlers (or if we include getProp and setProp, four) rather than just one is an argument that can lead to bloodshed. Best to just accept how it is and step away gracefully, before any axes are thrown.

I am confused that commands and message handlers are called the same thing, see page 123 in User Guide.

I agree that it's conceptually useful to be aware of how messages originate, but since the mechanics of handler definitions are the same for each personally I'm not sure it matters much in discussions of writing handlers.

I am also confused when there is no clear distinction between the engine and the other objects. I think that distinction is important.

This is perhaps a philosophical question bordering on a koan, but is the engine an object? After all, objects define behaviors, and the engine provides default behaviors. Maybe it's a special kind of object, much like scripts are a special kind of property.

[FourthWorld]

Hi Bob,

did you actually create something with Livecode so far or are you only trying to write a book about it?

I wouldn't be surprised if he does. He seems to have a keen mind to distilling the core essentials, and exploring ways to communicate those to others.

He's produced at least one video on LiveCode, a nice introduction to the tool and why it's useful, that he linked to in his other thread:
http://forums.livecode.com/viewtopic.ph ... 15#p116073

[Vanceone]

The User Guide defines, actually, 5 different messages. GetProp, SetProp, function, on, and command. Right now, Command and On are synonyms of each other, but the manual encourages you to use On for system defined events and command for your own custom handlers. So you handle "on MouseUp" but you do "Command "runAroundInSocksScreamingWhileTryingToCodeInC#" or something similar.

I don't know of many people aside from myself that uses the "Command" form, but I find it useful. I immediately know if this handler is a defined system command or my own.

[dunbarx]

All good stuff.

You have a huge head start, like some of us, in that you already know HC. I am working on a major upgrade to a 25 year old HC stack right now. Don't ask why, but I own five of the Winkler books.

That said, I go with Jacque. There has been evolution, and not all the terms are, or should be mappable between HC and LC.

As regards the "return" thing:

Code: Select all

on mouseUp
      put "Primary" && random(500)  into temp
    goSecondary
  answer temp & return & the result
end mouseUp

on goSecondary
      put "Secondary" && random(500)  into temp
   return temp
end goSecondary

Note that, just to be cute, I used the same local variable, "temp", in each handler. This just to show how they are different and distinct.

Craig

[uelandbob]

Thank you Jacqueine, what a wonderful post

Commands can be pushed into the message path without any object/target at all.

Don't know exactly what you are referring to here. Do you mean something like "pass mouseUp"

To him, messages are just instructions that flow freely and originate anywhere. .. He does not discriminate about where the message comes from or is going to.

This is interesting. I think we have different abstraction levels. On the highest level there are just objects sending messages, and we don't discriminate if they originate from the engine or from some user made object.

On the next level we do discriminate between the engine and the user made objects. We acknowledge the fact that we can control what messages our objects send, but that we can't control what messages the system sends (there or exceptions, for instance we can have timers and instruct the engine to send us some message at special time intervals). System messages or controlled by events, what the user does (mouse and keyboard) and events from the network. So on this level, we use the term "system message" to refer when the engine is sending a message to our objects. But we use the term command when we refer to the message that our objects send to the engine. As you remark, on this level we are using the term "command" as a generic term to refer both to commands, functions and messages. Most messaging goes between our objects and the engine. But there is of course moments when one of our objects sends a message directly to another object (this can be disputed, since "send" and "call" can be seen as commands send from one object to the engine, which in its turn sends it to the other object.)

On still deeper levels we start to discriminate between functions and commands, and also between control objects like buttons and text fields and other objects like cards and stacks. So on this level the word "command" is used in another sense then the word "command" on the higher level where it was used in the generic sense.

To be picky, the engine does not send its messages to objects specifically. It pushes them into the message path according to a pre-defined hierarchy and they travel from there. The engine produces a constant flow of event messages which may or may not affect any object in its path.

I love when you are picky Could you be little more specific. Let's say that the user clicks on a button. Let's also say that the button does not have a mouseUp handler, but that the card does. It has a handler that says

Code: Select all

on mouseUp
   put "card trapped mouseUp sent to the " & short name of the target  into msg 
   pass mouseUp
end mouseUp  

also the mainStack has a mouseUp handler that says

Code: Select all

on mouseUp
   put CR after msg
   put "stack trapped mouseUp sent to the " & short name of the target after msg
end mouseUp 

Could you explain how the engines pushes the mouseUp message on the stack and what makes the handlers on the card and mainStack to be executed.

[Klaus]

Hi Bob,

... Could you explain how the engines pushes the mouseUp message on the stack and what makes the handlers on the card and mainStack to be executed.

check this: http://www.fourthworld.com/embassy/arti ... _path.html


Best

Klaus