Sorry your browser is not supported!

You are using an outdated browser that does not support modern web technologies, in order to use this site please update to a new browser.

Browsers supported include Chrome, FireFox, Safari, Opera, Internet Explorer 10+ or Microsoft Edge.

AppGameKit Classic Chat / AGK Help Examples

Author
Message
Paul Johnston
TGC Developer
21
Years of Service
User Offline
Joined: 16th Nov 2002
Location: United Kingdom
Posted: 13th Jun 2013 05:17
The new help files have been put online here with the ability to submit examples for individual commands. Unfortunately we don't have the resources to do an example for every command, but by opening it up to you guys we might have a chance! If you have knowledge of how a particular command works we would be very grateful if you submit an example for it.

There is also a section for C++ examples if you press the C++ icon in the top right corner of the page. The offline help files will be updated in the next version to include the same functionality and examples as the online ones (currently they can't show C++ examples).
Naphier
13
Years of Service
User Offline
Joined: 2nd Oct 2010
Location: St Petersburg, Florida
Posted: 13th Jun 2013 05:32 Edited at: 13th Jun 2013 05:40
This is really great!
It prevents the need for an external wiki which seems to be difficult to manage. Hopefully many people will fill this up. I almost wish I was first learning the language again. It was a perfect time that I could have filled in a ton of examples. I'll try to do what I can now.

EDIT:
Sorry - a couple suggestions:
1 - Would it be possible to embed a Google site search into the documentation pages? I'd love to use the online docs, but no F1 from the compiler and typing "openfiletowrite site:appgamekit.com/documentation/" into the browser everytime is just a bear. You know, ever millisecond counts.

2 - Would it be possible to note on the command's page either when it was implemented or a changelog? I think PHP.net does it nicely.

Thanks a ton!!

MikeMax
AGK Academic Backer
12
Years of Service
User Offline
Joined: 13th Dec 2011
Location: Paris
Posted: 13th Jun 2013 05:56
Awesome !
easter bunny
11
Years of Service
User Offline
Joined: 20th Nov 2012
Playing: Dota 2
Posted: 13th Jun 2013 05:59 Edited at: 13th Jun 2013 05:59
Should the code be commented?
ie:

OR


Naphier
13
Years of Service
User Offline
Joined: 2nd Oct 2010
Location: St Petersburg, Florida
Posted: 13th Jun 2013 06:01
I was commenting mine so that someone can just cut and paste (plus I can't code ithout comments).

Paul Johnston
TGC Developer
21
Years of Service
User Offline
Joined: 16th Nov 2002
Location: United Kingdom
Posted: 13th Jun 2013 06:08
Quote: "Would it be possible to embed a Google site search into the documentation pages?"


I'll see what I can do.

Quote: "Would it be possible to note on the command's page either when it was implemented"


I honestly don't remember for most of the commands when they came into existence so I'd have to trace back through the backups. Maybe once I run out of other things to do

Quote: "Should the code be commented?"


If you think a section of code is doing something important or non-obvious then a comment would be very useful, but I wouldn't go so far as to comment every line unless it's necessary.

Comments could also be used to show what a particular line of code will output, for example string manipulation could show the result of a function in a comment.
Naphier
13
Years of Service
User Offline
Joined: 2nd Oct 2010
Location: St Petersburg, Florida
Posted: 13th Jun 2013 06:17
Quote: "I honestly don't remember for most of the commands when they came into existence so I'd have to trace back through the backups. Maybe once I run out of other things to do "

I didn't mean for you to go backwards and figure all that out... that'd be horrendous and I wouldn't wish that project on my worst enemy. Future would be great though. Just to know when a function was implemented or something major had changed, like when the SetSpriteShapes went from using offset to top left corner. But no need to go back in time! *shudders at the very thought*

easter bunny
11
Years of Service
User Offline
Joined: 20th Nov 2012
Playing: Dota 2
Posted: 13th Jun 2013 06:57
what about adding the ability to link to other commands in the example?
eg:

etc
even better, it automatically scans for AppGameKit commands and links to them! (hoping but not expecting)

Tone Dialer
Valued Member
18
Years of Service
User Offline
Joined: 17th Oct 2005
Location: England, well a town in it !
Posted: 13th Jun 2013 09:10
@ Paul

Excellent idea, I will get to work adding some examples.

There is no access to the 'Language' commands? most have examples already but some have errors, for example Dim is still showing the use of square brackets around the declared values, which will cause a compiler error if used.

dim myValues [ 3 ] as string = [ "abc", "def", "ghi" ]

JimHawkins
14
Years of Service
User Offline
Joined: 26th Jul 2009
Location: Hull - UK
Posted: 13th Jun 2013 10:06
It says "What's new in 1.07" on the very first page!

-- Jim DO IT FASTER, EASIER AND BETTER WITH AppGameKit FOR PASCAL
Lucas Tiridath
AGK Developer
15
Years of Service
User Offline
Joined: 28th Sep 2008
Location: Kings Langley, UK
Posted: 13th Jun 2013 10:56
Sounds like a good idea. So how is the best way to do this? It seems to me that giving an example for each command would be kind of useless:

Open To Read
OpenToRead( ID, szFile )
integer OpenToRead( szFile )

Example
OpenToRead(1, "MyFile.dat") ` opens MyFile.dat to read
myFile = OpenToRead("MyFile.dat") ` opens MyFile.dat to read

You take my point. Maybe it would be better to have an example that includes many of the file commands so that new users can see how they would work together.

Example
myFile = OpenToWrite("MyFile.dat")
WriteString(myFile, "Bob")
WriteInteger(myFile, 25)
WriteFloat(myFile, 1.8)
CloseFile(myFile)
myFile = OpenToRead("MyFile.dat")
name$ = ReadString(myFile)
age = ReadInteger(myFile)
height# = ReadFloat(myFile)
CloseFile(myFile)

So would it be sensible to write examples for blocks of commands and then copy that example for each included command? Or would that just confuse the issue?

Hodgey
14
Years of Service
User Offline
Joined: 10th Oct 2009
Location: Australia
Posted: 13th Jun 2013 14:05
I'm pretty sure that would be fine Lucas. IIRC that's what they did for the examples in the DBP help docs.

Phaelax
DBPro Master
21
Years of Service
User Offline
Joined: 16th Apr 2003
Location: Metropia
Posted: 13th Jun 2013 15:07 Edited at: 13th Jun 2013 16:19
Quote: "even better, it automatically scans for AppGameKit commands and links to them! (hoping but not expecting)"

I've considered doing that on my website. I have a few commands which link to others, but I set the link code in the database when the description was stored.

One method I think would be to append any command you want linked with '@' symbol or something. Other than that, you'd basically have to write an entire parser since you wouldn't want to create links to commands that are mentioned inside comments and whatnot.


I just wrote an example of setSpriteScissor but I didn't use prettify for the code snippets.
http://www.zimnox.com/resources/agk/docs/?c=SetSpriteScissor


Quote: "1 - Would it be possible to embed a Google site search into the documentation pages?"

I just added a search to my online docs. It'll search in the name and description fields.
http://www.zimnox.com/resources/agk/docs/

Ancient Lady
Valued Member
20
Years of Service
User Offline
Joined: 17th Mar 2004
Location: Anchorage, Alaska, USA
Posted: 13th Jun 2013 17:17
Paul, the concept sounds great. But the link you showed is the old v1076 documentation. Even though the Examples page does appear to be the new one.

But I don't see anything that lets us offer examples. Unless you actually mean for us to submit them to this thread?

About comments. They are a great idea. But they should be on the line above the command being commented on. Definitely not inline with the command. That is visually confusing.

One of the examples I'd like to work up is how to do a simple state engine in Tier 2 for dealing with the issue of only being able to use Sync() for user/network inputs in the app::Loop() method (and it only works at the end for that). It would be a relatively comprehensive one including dealing with http request sending/handling.

Cheers,
Ancient Lady
AGK Community Tester and AppGameKit Master
Paul Johnston
TGC Developer
21
Years of Service
User Offline
Joined: 16th Nov 2002
Location: United Kingdom
Posted: 13th Jun 2013 17:30 Edited at: 13th Jun 2013 17:30
The link works for me, perhaps the old version is being cached somewhere. The examples are submitted on the command page, for example http://www.appgamekit.com/documentation/Reference/Core/Abs.htm has the examples section at the bottom.
Ancient Lady
Valued Member
20
Years of Service
User Offline
Joined: 17th Mar 2004
Location: Anchorage, Alaska, USA
Posted: 13th Jun 2013 17:48
You appear to be correct. I was checking from my Mac and Firefox on it is caching the pages (something I have turned off on every other browser and machine, and it is about to be turned off on this one).

My apologies. I should have checked for caching issues before commenting.

I like it, nice format.

Cheers,
Ancient Lady
AGK Community Tester and AppGameKit Master
Phaelax
DBPro Master
21
Years of Service
User Offline
Joined: 16th Apr 2003
Location: Metropia
Posted: 13th Jun 2013 19:18
Weird, first time I looked I didn't see that part, but now the examples are showing up.

easter bunny
11
Years of Service
User Offline
Joined: 20th Nov 2012
Playing: Dota 2
Posted: 14th Jun 2013 06:59 Edited at: 14th Jun 2013 07:01
whoops, I've submitted an example for this page.
But I've just noticed that I didn't close the brackets for GetSpriteHitTest() and it got past the moderation.
It may be a good idea to allow users to edit examples (sort of like a wiki), or to allow people to flag one's that don't work, which will then be checked by a mod.

Scary Little Rabbit
14
Years of Service
User Offline
Joined: 4th Aug 2009
Location: Chelyabinsk, Russian Federation.
Posted: 14th Jun 2013 16:16 Edited at: 14th Jun 2013 16:45
I - as well as Naphier - like php.net too, so you have another ton, thanks.

I attempted to illustrate some.

error #1:
"too many stars, too many stares. disembody."
WIP: MIND!! | free fonts for your AGKs
Naphier
13
Years of Service
User Offline
Joined: 2nd Oct 2010
Location: St Petersburg, Florida
Posted: 14th Jun 2013 16:23
Wait a tick! You can make a white sprite without an image?!?!?!
I really need to pay better attention to the help files LOL
Thanks for making me notice that MissJoJo

Paul Johnston
TGC Developer
21
Years of Service
User Offline
Joined: 16th Nov 2002
Location: United Kingdom
Posted: 14th Jun 2013 16:56
Editing would be a good feature, for now I've fixed your example
Markus
Valued Member
20
Years of Service
User Offline
Joined: 10th Apr 2004
Location: Germany
Posted: 14th Jun 2013 19:31 Edited at: 14th Jun 2013 19:36
maybe its better to post a working example that you can run.

@Scary Little Rabbit
*k4
why not write width and height instead of www hhh^^,n not nnn.
it would have more learning effect.
Scary Little Rabbit
14
Years of Service
User Offline
Joined: 4th Aug 2009
Location: Chelyabinsk, Russian Federation.
Posted: 15th Jun 2013 19:54
Markus, there are nnn instead n (and all that) for easy highlighting of stuff which matches when you select it in IDE; if use width and height instead www and hhh, then memblock instead mmm.
it will be great, if we all will use one names of variables for all our examples. let's talk about. imageID, memID how it is in help now? so maybe imageWidth, imageHeight?

error #1:
"too many stars, too many stares. disembody."
WIP: MIND!! | free fonts for your AGKs
Markus
Valued Member
20
Years of Service
User Offline
Joined: 10th Apr 2004
Location: Germany
Posted: 15th Jun 2013 20:59
@Scary Little Rabbit
just a little bit more readable would be fine.
if you have the time maybe like the agk help.
for some rows i don't need this highlighting matches but now
i understand why u use 3 chars
function img_create_RGBA(www,hhh, klr_r,klr_g,klr_b, klr_a)
function CreateImage(width,height,red,green,blue,alpha)
XanthorXIII
AGK Gold Backer
12
Years of Service
User Offline
Joined: 13th May 2011
Location:
Posted: 17th Jun 2013 19:31
Two things.
Can we get a Tier 2 Switch that doesn't require to be turned for each command that we click on? I'd rather have that for the entire document.
The Second is can we get a listing of the functions by categories that shows just their calling Signature? I think it would make working with the manual quicker.
Tone Dialer
Valued Member
18
Years of Service
User Offline
Joined: 17th Oct 2005
Location: England, well a town in it !
Posted: 19th Jun 2013 08:58
@Paul

While working on some examples, I have found that using the ResetTimer() command causes the GetOrientation() command to fail when using the AGKPlayer.

For example, this code is working OK


But this does not, GetOrientation() appears to get stuck in Portrait Mode


Any ideas?

Paul Johnston
TGC Developer
21
Years of Service
User Offline
Joined: 16th Nov 2002
Location: United Kingdom
Posted: 19th Jun 2013 17:28
Quote: "I have found that using the ResetTimer() command causes the GetOrientation() command to fail when using the AGKPlayer"


Fixed, thanks
XanthorXIII
AGK Gold Backer
12
Years of Service
User Offline
Joined: 13th May 2011
Location:
Posted: 28th Jun 2013 21:21
Paul,
How about something to flag a command and submit a correction. For example under Sprites there is a command to see if an Animation is playing for a Sprite called GetSpritePlaying however it is not listed with the Animation group. Maybe something we can do to help clear that up and others?
Tone Dialer
Valued Member
18
Years of Service
User Offline
Joined: 17th Oct 2005
Location: England, well a town in it !
Posted: 30th Jun 2013 10:56
@Paul,

There is a typo in the Parameters section of
SetEditBoxUseAlternateInput

Currently says
Quote: "mode - 1 to display stars, 0 to display the normal input."


Should Read
Quote: "mode - 1 Use Alternative Input (default), 0 Turn Off"


Please amend.

Paul Johnston
TGC Developer
21
Years of Service
User Offline
Joined: 16th Nov 2002
Location: United Kingdom
Posted: 30th Jun 2013 17:42
Fixed, thanks.
Tone Dialer
Valued Member
18
Years of Service
User Offline
Joined: 17th Oct 2005
Location: England, well a town in it !
Posted: 1st Jul 2013 22:44
@Paul

Testing the example I uploaded for SetMusicFileVolume did not seem to have any noticeable effect on my test systems (Windows 7 and Android), the volume did not alter.

The example for SetMusicSystemVolume did work correctly for me.

I uploaded both because it could just be my equipment, if you could confirm my findings please.

Paul Johnston
TGC Developer
21
Years of Service
User Offline
Joined: 16th Nov 2002
Location: United Kingdom
Posted: 2nd Jul 2013 04:34
You are correct, it appears SetMusicFileVoume only has an affect before the file is played, not sure why I coded it like that. I'll see if I can correct it.
RickV
TGC Development Director
23
Years of Service
User Offline
Joined: 27th Apr 2000
Location: United Kingdom
Posted: 4th Jul 2013 23:18
@Tone Dialer - Paul told me how many help files you have documented. Thanks a million for this contribution! We have awarded you with a Valued Member badge for doing such sterling work for TGC and the community.

Rick

Financial Director
TGC Team
Tone Dialer
Valued Member
18
Years of Service
User Offline
Joined: 17th Oct 2005
Location: England, well a town in it !
Posted: 4th Jul 2013 23:40
@RickV

Thank you for the badge, its a pleasure, currently working through examples for some of the core commands, especially as there could be many new AppGameKit users out there.
There is a real 'buzz' around AppGameKit and the forum at the moment.
Good luck to the whole team.

Plus my OUYA arrived today

RickV
TGC Development Director
23
Years of Service
User Offline
Joined: 27th Apr 2000
Location: United Kingdom
Posted: 5th Jul 2013 00:00
We're more focused now as a team and we want to be much more involved and closer to our community. Our two main projects are AppGameKit and Reloaded and that will remain the case in the longer term.

Rick

Financial Director
TGC Team
Marl
12
Years of Service
User Offline
Joined: 19th Nov 2011
Location: Bradford, UK
Posted: 12th Jul 2013 15:16 Edited at: 12th Jul 2013 15:29
My Submission for SetScissor is a screen magnifier using view offset and zoom (the submit doesn't seem to be working for me (chrome) - http://www.appgamekit.com/documentation/Reference/Core/SetScissor.htm)

Version: 108.14
Tier: 1



edit: Typos and additional comments in code

Attachments

Login to view attachments
Ancient Lady
Valued Member
20
Years of Service
User Offline
Joined: 17th Mar 2004
Location: Anchorage, Alaska, USA
Posted: 12th Jul 2013 16:48
Marl, if you check the help page, you will see that your example is now posted.

I suspect there is some moderation going on with the examples and you may have submitted at a time they weren't looking?

Cheers,
Ancient Lady
AGK Community Tester and AppGameKit Master
Marl
12
Years of Service
User Offline
Joined: 19th Nov 2011
Location: Bradford, UK
Posted: 12th Jul 2013 18:46
Thanks AL. Indeed it is.

It was weird, no error or anything, the page didn't change or show acknowledgement - it was just like the submit button was a fake

The other odd thing is that when posting, it had the message
Quote: "As you currently don't have a screen name you can create one that will appear on all your submitted examples"

whereas now checking back it has
Quote: "Logged in as: Marl "

using the same link
(I don't log out much)
Tone Dialer
Valued Member
18
Years of Service
User Offline
Joined: 17th Oct 2005
Location: England, well a town in it !
Posted: 3rd Aug 2013 18:45
@Paul

Could you produce a list of the V108 commands which do not yet have any Help Examples please.

Paul Johnston
TGC Developer
21
Years of Service
User Offline
Joined: 16th Nov 2002
Location: United Kingdom
Posted: 5th Aug 2013 19:19 Edited at: 5th Aug 2013 19:19
Here are the commands that don't have examples yet

Marl
12
Years of Service
User Offline
Joined: 19th Nov 2011
Location: Bradford, UK
Posted: 18th Aug 2013 00:10
^^ Some work to be done there then.

I thought there might be a few but ...

... Just Wow!

It's so easy to forget just how many commands there are

( wonder what most of 'em do )
Marl
12
Years of Service
User Offline
Joined: 19th Nov 2011
Location: Bradford, UK
Posted: 21st Aug 2013 01:39 Edited at: 21st Aug 2013 01:45
sorry for the double post, but nobody else has posted

I was looking at adding a couple of examples from the code I'm working on, but had a thought about the layout of the help.

Often examples feature several commands at the same time - some commands simply cannot be used in isolation - so why not have a shared example?

So for example with Joysticks, the commands to read the values are all very similar, and yet the same example could apply to all of them.

Here's an example for some Raw joystick commands - I simply don't know which command to put it under ATM and it would be a lot of duplication to put it under each one.


This would probably need to have the help sections broken down further to functional levels and have an example of all the commands at that level.

But with V2 in the pipes, perhaps now is the time to consider it.

Edit:

I realize there is an examples section, which covers a lot more than the help, but having (brief) examples with the commands as well provides a reminder of the syntax used in a real app (as apposed to the command format; eg. "integer GetRawJoystickButtonPressed( index, button )")
Tone Dialer
Valued Member
18
Years of Service
User Offline
Joined: 17th Oct 2005
Location: England, well a town in it !
Posted: 21st Aug 2013 09:24
@Marl,

It has been mentioned before that within each command sub-group many of the AppGameKit commands are very similar, however the way I looked at it (while doing many examples) was that a new user might encounter a command for the first time, and to have an example that uses the actual command they want, even if it is similar or in some cases identical to another example was still helpful.
Also where command sub-group examples are provided by different forum members, this leads to a richer mix of examples for the user to learn from.
Please add any examples you have, if Paul feels that there is too much duplication I am sure he will say so and/or use his approval procedure to make amendments.

BatVink
Moderator
21
Years of Service
User Offline
Joined: 4th Apr 2003
Location: Gods own County, UK
Posted: 27th Sep 2014 16:05
Tone Dialer
Valued Member
18
Years of Service
User Offline
Joined: 17th Oct 2005
Location: England, well a town in it !
Posted: 19th Jan 2015 19:39
@ Paul

Just a bit of a bump!
I have found a little time to write and test a few more examples for the AppGameKit commands on-line help files.

http://www.appgamekit.com/documentation/commands.html

I hope they are useful.

Login to post a reply

Server time is: 2024-04-25 02:56:22
Your offset time is: 2024-04-25 02:56:22