DLP Anne: hi all
Magine: hi
ZebLith: Hello :)
DLP Anne: was getting lonely here lol
Magine: wow, 3.4 out next week huh?
ZebLith: can't wait ^^
DLP Anne: so they say lol
Magine: well let me see now...what shall we talk about today? :D
Magine: any questions from last time?
ZebLith: no questions :)
Magine: either of you try experimenting or playing around with the bot since last time?
DLP Anne: im playing with the bot some  lol but i get frustrated easy
Magine: what kinds of problems you having?
DLP Anne: its  a blonde thing lol
Magine: lol :P
DLP Anne: nothing I cant work out its the distractions in dlp is all
Magine: ah yes, distractions...i understand completely :D
ZebLith: lol :)  Well, I have just set it up for simple things, such as it will report to the $owner when someone enters or leaves.  and allows you to set $owner  that's it so far...
Magine: well today i'm going to talk about the custom buttons
Magine: and then we could talk about the programming language some more, but there is really so much to it, it would take a dozen more sessions to cover all that, so
Magine: i'm  going to rely on you guys to give a hint about the parts that aren't making sense to you [or that you want to know more about].
Magine: i'm hoping you've both looked at the help pages, right?
DLP Anne: yes a bit
ZebLith: not throughly, but I have used them occasionally
Magine: but you have a pretty good idea how to find something you want to look up....what category to look under and so forth?
DLP Anne: yes
ZebLith: yeah :D
Magine: ok...good. i probably need to revise the help, add frames or something, but i'm not a web page guru :D
DLP Anne: they look fine to me  and I say if it works dont fix it lol
Magine: ok, good :)
Magine: well, anyway...on to the buttons
Magine: first let's create a new category tab on the actions panel for our experiments
Magine: just right click anywhere on the actions panel (any tab),
Magine: and choose category>add
Magine: and enter some name for the category
Magine: now on the new category tab, right click [on the page] and choose "new" [from the popup menu]
DLP Anne: im not able to right click hmmm
Magine: not able to right click?
DLP Anne: it wont let me
DLP Anne: like on the build tab  i try right clicking and nothing
Magine: you click on the page itself, not the tab, actually....maybe i wasn't using the right word
DLP Anne: gawd  nevermind I see now its gonna  be a bad day
Magine: what i meant was, it doesn't matter what tab is selected when you click
Magine: when creating a new category.
Magine: so you have your new category tab (page) now?
DLP Anne: yes
ZebLith: yes ^^
Magine: then right click on that and choose "new" to start editing  a new button
Magine: or, you can just press Insert when the tab is selected
Magine: try entering
Magine: say "hello world"
Magine: and click ok
Magine: (give the button some name of your choice, of course)
[Mags]: hello world
Magine: then click it
[Chilaou]: Hello World!
Magine: got it, anne? :)
DLP Anne: hmmm lol
[Eve]: Hello World.
DLP Anne: yup
Magine: there ya go :)
Magine: ok
Magine: now to edit the button to make changes, just right click the button or the button name, and choose Edit.
Magine: for now just cancel though, don't need to make any changes yet
DLP Anne: k
Magine: you'll also see on that popup menu, that you can save buttons individually, or save categories individually
DLP Anne: right
Magine: you can also copy, cut and paste buttons to transfer them between categories
Magine: or even between magsbot programs if you have two running at once
Magine: you can select multiple buttons for delete, copy and cut,
DLP Anne: cool
Magine: but you can only save one button at a time, even if several are selected
Magine: (hm, maybe i need to enhance that)
Magine: to select multiple buttons, you click on the button NAME, not the grey button icon itself
Magine: and hold down ctrl or shift, the same as when selecting multiple files in windows
Magine: if you do want to save multiple buttons, you can do so by saving a whole category to one file
Magine: using category>save, of course.
Magine: all button files, even when you only save one button, contain the category name as well as the button
Magine: so when you use the main File/Action Buttons/Merge Buttons menu
Magine: it will stick the buttons that you are merging or loading into the right category
Magine: let's do that just to show you how. first select the new button you created (click on the button name so it's highlighted)
Magine: then, either right click and choose "save", or just press F4
Magine: and save your button.
Magine: did that work ok?
DLP Anne: yeah
ZebLith: yes :)
Magine: ok, now right-click your button and choose delete
Magine: poof, it's gone.
DLP Anne: yes
Magine: to get it back, just use the File/Action Buttons/Merge Action Buttons menu
DLP Anne: cool its back
ZebLith: ah :D
Magine: you can also look at the button file with a text editor
Magine: although it isn't recommended that you edit it that way unless you are super careful
DLP Anne: no problem lol i wont touch it LOL
Magine: because there are some non-printing characters [in the .btn file] that separate the category and button names and code.
Magine: the behavior table file is also just a text file, btw
DLP Anne: yes I already saw it in edit pad
Magine: if you've loaded your button back in, now right click it and choose "copy" then right click the page again and choose "paste"
DLP Anne: cool
Magine: or you can just click the button name to select it, and press ctrl-insert to copy and shift-insert to paste
Magine: of course normally you wouldn't want a lot of copies of the same button, so after copying it, you would edit it and change the name
DLP Anne: right
Magine: as well as making whatever other changes you would want to make [in the button's code].
Magine: click shift-ins a few times and make a lot of copies of your button
Magine: then hold down the shift key and select all but one of them, and hit delete (just like deleting multiple files in windows)
[Eve]: Hiya Magine.
DLP Anne: lol oops
Magine: hi eve :)
Magine: ok, if all that is clear, now let's see how you can call buttons from other buttons.
Magine: create a second button on your category there, with a different name,
Magine: and in it put this:
Magine: clickbtn "MyButtonName"
Magine: (whatever name you gave your first button)
[Mags]: hello world
Magine: when you click the second button, it will activate the first one
Magine: try it :)
[Chilaou]: Ohayougozaimasu!
[Eve]: Hello world.
ZebLith: great :)
DLP Anne: aha
Magine: you can also use clickbtn in the behavior table to call on buttons
Magine: but in that case, you would also use the category name
Magine: like clickbtn "MyCategory/MyButtonName"
DLP Anne: ok I  have a question
Magine: yes anne?
DLP Anne: why would you click that one to activate the first one?  why not just cllick the first one?
Magine: well you will see as we get to more complicated examples
DLP Anne: ok
Magine: suppose you have some code that you want to use in several places
Magine: instead of putting it in each place, you could put it in a button and call that button from the different places
DLP Anne: ahhh ok
Magine: and i'll give you an example in just a few minutes
Magine: but right now i want to show you about passing variables between buttons
DLP Anne: k
Magine: again edit your original button, and change it so it says
Magine: say $x
Magine: instead of say "hello world"
Magine: then edit your second button, and before the clickbtn "mybuttonname", put $x="hello world";
Magine: oh btw, button names ARE case sensitive,
Magine: so if the name has capital letters in them, then put the name exactly as it is
Magine: ok, done that?
DLP Anne: hmmm yeah
Magine: now click the second button
[Mags]: hello world
Magine: your bot will still say "hello world" (or whatever phrase you chose) but now it will be getting the string from the second button
Magine: try it :)
DLP Anne: not working here
Magine: ok, what do you have in button one, exactly?
DLP Anne: yes first oone does
Magine: it should have, exactly:
Magine: say $x
Magine: and button two should have this:
Magine: $x="hello world"; clickbtn "ButtonOneName"
Magine: (whatever the first button name is)
[Eve]: Hello World
Magine: there ya go :)
DLP Anne: there  i didnt have the ;
[Chilaou]: Ogenki desu ka?
ZebLith: there :)
DLP Anne: konichiwa
DLP Anne: LOL
Magine: yes, you always need the ; between commands
ZebLith: lol :D
Magine: domo arigato :D
Magine: mr. bot-o
DLP Anne: lol thats all I know in japanese
Magine: ok, all clear so far?
ZebLith: hehehe ^^  yeah :)
DLP Anne: yes
Magine: so far what we've seen is the way buttons operated in old versions of magsbot
Magine: but in 4.0 i added some commands to let you call buttons as functions
Magine: which is even more useful.
Magine: when you use the clickbtn command, as you have seen, any variables (like $x) are passed into the button being called.
Magine: that is, ALL local variables created in the calling routine (either button or behavior table) are passed into the button [and all variables are passed back out of the button]
Magine: but you can instead use the FTN command ("ftn" = abbreviation for "function")
Magine: which will call the button, but pass only the variables that you list in the FTN command.
Magine: let's edit the second button again to see what i mean
Magine: in the second button, remove the $x="hello world";
Magine: and instead of
Magine: clickbtn "mybuttonname"
Magine: put
Magine: ftn "mybuttonname" "hello world"
Magine: then in the first button,
Magine: add at the top:
Magine: args $x;
Magine: so now your first button should have
Magine: args $x; say $x
Magine: and your second button should have
Magine: ftn "mybuttonname" "hello world"
Magine: got that?
[Mags]: hello world
Magine: once you have that, click the second button again
[Chilaou]: Bienvenue!
ZebLith: ah :D
[Eve]: Howdy Folks
DLP Anne: yup
Magine: :)
Magine: another thing that's good about the FTN command is
Magine: it doesn't pass variables back out, either, unless you want it to.
Magine: when you use clickbtn it not only passes all local variables into the button,
Magine: but any variables changed or created within the button are also passed out.
Magine: but when you use the FTN command
Magine: only the variables you specify are passed in,
Magine: and within the called button, only the variables you specify are passed back out
       [variables are passed back out using the RETURNS, RETURN or RETURN_ commands, see below]
Magine: so if the button uses a variable named $x for instance
Magine: it may be an entirely different $x than one outside the button
Magine: which is a good thing, since when you create a button intended to be called from somewhere else,
Magine: you don't need to worry about [variables inside the button] interfering with variables [outside the button]
Magine: does all that make sense? :D
DLP Anne:  it will in time lol
ZebLith: I think I understood it. ;)
Magine: ok, now let's try this
Magine: in the first button,
Magine: add this:
Magine: $z="some phrase of your choice"
Magine: (make sure you put the ; between the commands)
Magine: so now in the first button you should have
Magine: ARGS $x; SAY $x; $z="guess what?"
Magine: and in the second button add
Magine: report $z
Magine: so in the second button you should have
Magine: FTN "test" "hello world"; REPORT $z
Magine: ok, now before you try to click that to see what happens :)
Magine: here is a trick question for you
Magine: what do you think will happen when you click button two now?
[Eve]: Howdy Folks
[Mags]: hello world
ZebLith: You'll get an error I think...
DLP Anne: hmmm said variable not found
Magine: well you were supposed to guess first :P
Magine: but that's right, you got an error
DLP Anne: LOL
Magine: can you tell me why?
ZebLith: because $z doesn't exist yet, and it calls it before the first button can set it.
Magine: nope
Magine: $z definitely exists [inside the button]
Magine: any other guesses? :)
Magine: no? okay, lets do this to figure it out. let's create a third button, and in it, put this:
Magine: $x="hello whirled"; CLICKBTN "test"; REPORT $z
Magine: (assuming your first button is named "test")
Magine: now click that third button and see what happens
[Mags]: hello whirled
[Chilaou]: Bienvenue!
Magine: any error that time? [no]
ZebLith: ah
Magine: both the second and third buttons are calling the first button, but what is the difference?
Magine: the second button is using FTN and the third button is using CLICKBTN
Magine: so what does that mean? :)
Magine: are you baffled? :)  what does FTN do that CLICKBTN  does not do?
Magine: or vice versa? :D

[this is a bit of a side track here]
DLP Anne: mine isnt working
Magine: not at all anne?
DLP Anne: says test cannot be found
Magine: right, sorry, i said you should use your first button name instead of "Test"
DLP Anne: and it shut down
Magine: shut down? :O
Magine: the program shut down??
DLP Anne: yeah just closed on me lol
Magine: hmmm
DLP Anne: and my catagory is gone lol
DLP Anne: but go ahead I print these out so I will redo it later
Magine: yeah if the bot crashed and you hadn't saved the buttons [your changes will be lost].
Magine: press F7 to save all the buttons, BTW
DLP Anne: k
Magine: ok so anne,
Magine: create your category, and create three buttons
Magine: the first should contain
Magine: ARGS $x; SAY $x; $z="guess what?"
Magine: the second should contain
Magine: FTN "firstbuttonname" "hello world"; REPORT $z
Magine: and the third should contain
Magine: $x="hello whirled"; CLICKBTN "firstbuttonname"; REPORT $z
Magine: then press F7 to save that
Magine: i can't imagine why it shut down though :D
ZebLith: baffled? xD
Magine: anyway, while you are doing all that

DLP Anne: sheesh again mine not working and I  have it axactly like you said
Magine: ok, you created a new button that had exactly this:
Magine: ftn "Chat/[SayLong]" "hello world"
Magine: in it?
[Eve]: Hello World
Magine: there ya go :)
DLP Anne: hmmm no I had this is a test lol
Magine: well whatever, that doesn't matter :D
DLP Anne: as you all can see im stuggling on this one
Magine: "this is a test" should work too :D
Magine: i know it's difficult
DLP Anne: it didnt tho lol worked when I put in hellp world
Magine: i take it for granted because this sort of passing of variables in what most all programming languages do some way or other, so it's a familiar concept
Magine: it didn't work?
Magine: you had quotes around it?
[Mags]: help world
DLP Anne: no when I changed This is a test  to Hello world it worked
Magine: change it back to "this is a test"
[Mags]: this is a test
[Eve]: This is a test
Magine: there ya go :)
DLP Anne: well dang now it does
DLP Anne: weird
Magine: maybe you left off a quote the first time?
DLP Anne: maybe  hmmm

DLP Anne: when I try toi save  it says numeric value expected
Magine: ok, does it say exactly
Magine: $x=$ftn["[PickAv]"]; @av=@sessionof[$x]; SAY $fmt["%s is at %s, %s",$x,@avz[@av],@avx[@av]]
DLP Anne: yeah
[Mags]: DLP Anne is at 16553, -775720
[Chilaou]: [Gardener] is at 21000, -775000
Magine: (to [Eve]) version
[Eve]: Magsbot 4.0 b23 - AW SDK Build 31 - Bot Bone Build 11
Magine: anne, press F5, type
Magine: enlist control magine
Magine: say when :)
DLP Anne: when
Magine: eve do $x=$ftn["[PickAv]"]; @av=@sessionof[$x]; SAY $fmt["%s is at %s, %s",$x,@avz[@av],@avx[@av]]
[Eve]: Your wish is my command!
Magine: eve do say $error
[Eve]: Avatar not present: @sessionof[$x]««
[Eve]: Your wish is my command!
[Eve]:
Magine: oh yeah, duh, i can't do it that way, someone has to pick an av :D
Magine: eve do $x=Magine; @av=@sessionof[$x]; SAY $fmt["%s is at %s, %s",$x,@avz[@av],@avx[@av]]
[Eve]: Your wish is my command!
[Eve]: Magine is at 16053, -774671
Magine: i don't think you have the right stuff in the button, anne
Magine: $x=$ftn["[PickAv]"]; @av=@sessionof[$x]; SAY $fmt["%s is at %s, %s",$x,@avz[@av],@avx[@av]]
DLP Anne: ok let me look again
Magine: copy and paste that :)
[Eve]: DLP Anne is at 16553, -775720
Magine: there ya go :)
DLP Anne: must of had a typo somewhere
[Mags]: Magine is at 16.053N 16.053W -774.671a -71.2, 0
[Eve]: ZebLith is at 15061, -774415
DLP Anne: haha cant hide now

The CLICKBTN and FTN commands both allow you to activate buttons on the actions panel from within your program.

With both of these commands, when using them from within the behavior table you should specify the category tab name as well as the button name, unless the button is in the root "." category.  Like this:

CLICKBTN "SomeCategory/MyButton";
or
FTN "SomeCategory/MyButton";

The difference between CLICKBTN and FTN (FTN is for "function") is that when you use CLICKBTN, all local variables are passed to the button, and all local variables are passed back out, including any variables that are created in the button itself, or any changes that are made to variables in the button. But when you use FTN instead, then no variables are passed in. Only the values (not variables) that you specify are passed in, and those are renamed for use within the button. Also, FTN does not pass back any variables unless you specify them using the RETURNS command (explained below). The reason for this is so that when you use FTN, you don't need to worry about variables within the button changing the variables outside of the button, so you don't even need to care what variable names are used within the button.

How FTN works is like this:

FTN "SomeCategory/MyButton"  $x 12 "some string";

ARGS $z @n $s;

If you want to pass variables back out of the button called using FTN, then you can use the RETURNS command within the button to list the variables to be passed back, like this:

RETURNS $s @n;

RETURNS  128  "blah";

Yet another way you can call action buttons is by using the @ftn and $ftn functions. These act exactly like the FTN command, except with the additional ability of passing back a single value directly.  The @ftn function passes back a numeric value and the $ftn function passes back a string value, from the called button.

For example, you would use @ftn like this:

@v=@ftn["SomeCategory/MyButton",$x,12,"some string"];

RETURN_ @m

RETURN_ 12;

Or even this:

RETURN_  6+12/8;

To avoid confusing people who may be familiar with the C "return" statement, let me point out that in Magsbot the RETURNS, RETURN and RETURN_ commands do not cause the button to be exited at that point, they only specify what is going to be passed out when the button code does finish. You would use the BREAK command (outside of any loops) to exit the button early.  Also note that only the first call to RETURNS, RETURN_ or RETURN that is executed will be significant. If you assign one value using RETURN then assign another value later in the code, the second assignment will be ignored.

Another thing to note: if you pass values to a button and neglect to have an ARGS command, or if your ARGS command doesn't include names for all of the values passed in, then no error message will be given when the button is called, but, of course, the unnamed values won't be available within the button and may cause an error message when the button tried to use them.  Similarly, if you specify variable names using an ARGS command and do not actually pass anything in to assign to those variables, there will be no error message when the button is called, but the variables in the ARGS command that weren't assigned anything won't exist within the button, and you will get a "variable not found" error message if you try to use them.  However if you want to create a button with optional arguments, you could check within the button to see if the variable got assigned, and if not, assign it some value within the button code. Like this:

FTN "SomeCategory/MyButton"  47 "foobar";

ARGS @n $x $z;
IF @isvar[z]=0 {
   $z="" };

I hope that clarifies the above lesson somewhat. :)