AGS Pointers for Dummies: Difference between revisions
no edit summary
*>Monkey 05 06 m (→testing) |
*>Monkey 05 06 No edit summary |
||
| Line 1: | Line 1: | ||
[[Image:pointerdummies.gif|center]] | |||
<center>'''<font size="4">AGS Pointers for Dummies</font>'''</center> | <center>'''<font size="4">AGS Pointers for Dummies</font>'''</center> | ||
| Line 14: | Line 13: | ||
==Variables== | ==Variables== | ||
A variable, in the context of scripting, is a way to represent a value. In AGS, there are five different | A variable, in the context of scripting, is a way to represent a value. In AGS, there are five different {{link|Script language keywords|Data types|data types}} which can be used to represent a variable. These types include '''char''', '''short''', '''int''', '''String'''<span id = "ref_1"><sup>{{link||end_1|[1]}}</sup></span>, and '''float'''. A '''char'''-type variable is one that can hold only a single character (i.e., 'A', 'B', etc.) or a number within the range 0 to 255. A '''short'''-type variable can store integers within the range -32768 to 32767. An '''int'''-type variable can store integer values within the range -2147483648 to 2147483647. A '''String'''-type variable can hold a string of characters (i.e., "this is some text!") of ''virtually''<span id = "ref_2"><sup>{{link||end_2|[2]}}</sup></span> infinite length. A '''float'''-type variable can store floating-point decimals within the range -2147483648.0 to 2147483647.0, and has precision<span id = "ref_3"><sup>{{link||end_3|[3]}}</sup></span> up to approximately 6 decimal places, though this will vary based on the actual number. | ||
For information on defining and assigning values to variables read the entry in the manual | For information on defining and assigning values to variables read the entry in the manual {{link|Script language keywords|Data types|here}}. | ||
==Pointers== | ==Pointers== | ||
| Line 24: | Line 23: | ||
''And, how do I use them?'' | ''And, how do I use them?'' | ||
In AGS, you can only create pointers to certain data types. These are called the ''managed'' types<sup>4</sup>. | In AGS, you can only create pointers to certain data types. These are called the ''managed'' types<span id = "ref_4"><sup>{{link||end_4|[4]}}</sup></span>. | ||
==Managed Types== | ==Managed Types== | ||
AGS has certain ''managed'' types<sup>4</sup> that you can not create an instance (variable declaration) of, but you ''can'' create pointers to<sup>5</sup>. All of the variables of managed types are ''managed'' by AGS. These include the types: | AGS has certain ''managed'' types<sup>{{link||end_4|[4]}}</sup> that you can not create an instance (variable declaration) of, but you ''can'' create pointers to<span id = "ref_5"><sup>{{link||end_5|[5]}}</sup></span>. All of the variables of managed types are ''managed'' by AGS. These include the types: {{link|GUI Button functions and properties||Button}}, {{link|Character functions and properties||Character}}, {{link|DateTime functions and properties||DateTime}}, {{link|DynamicSprite functions and properties||DynamicSprite}}, {{link|File functions and properties||File}}, {{link|Game / Global functions||Game}}, {{link|GUI functions and properties||GUI}}, {{link|GUI control functions and properties||GUIControl}}, {{link|Hotspot functions and properties||Hotspot}}, {{link|Inventory item functions and properties||InventoryItem}}, {{link|GUI InvWindow functions and properties||InvWindow}}, {{link|GUI Label functions and properties||Label}}, {{link|GUI List Box functions and properties||ListBox}}, {{link|Maths functions and properties||Maths}}, {{link|Object functions and properties||Object}}, {{link|Overlay functions and properties||Overlay}}, {{link|Parser functions||Parser}}, {{link|Region functions and properties||Region}}, {{link|Room functions||Room}}, {{link|GUI Slider properties||Slider}}, {{link|GUI Text Box functions and properties||TextBox}}, and {{link|ViewFrame functions and properties||ViewFrame}}. | ||
==Working With Managed Types== | ==Working With Managed Types== | ||
You can work with these managed types through pointers. You define a pointer by typing the name of the managed data type, then a space, an asterisk (*)<sup>6</sup>, and finally the name of the pointer. So, if we want to create a GUI pointer (this is expressed as GUI*) called GUIPointer, we could type the following: | You can work with these managed types through pointers. You define a pointer by typing the name of the managed data type, then a space, an asterisk (*)<span id = "ref_6"><sup>{{link||end_6|[6]}}</sup></span>, and finally the name of the pointer. So, if we want to create a GUI pointer (this is expressed as GUI*) called GUIPointer, we could type the following: | ||
GUI *GUIPointer; | GUI *GUIPointer; | ||
This creates a pointer that can ''point'' to any GUI stored in the memory. However, until it is assigned a value, it is an empty, or ''null'' pointer. We'll first discuss how to assign pointers a value, then we'll discuss null pointers. | This creates a pointer that can ''point'' to any GUI stored in the memory. However, until it is assigned a value, it is an empty, or ''null'' pointer. We'll first discuss how to assign pointers a value, then we'll discuss null pointers. | ||
==Array of Pointers== | ==Array of Pointers== | ||
It should be noted here that when defining pointers, you can also create an | It should be noted here that when defining pointers, you can also create an {{link|Script language keywords|Arrays|array}} of pointers. When you create an array you are simply defining a set of variables (or in this case, pointers) which all have the same name. You access each one individually using an index between brackets ([ and ]). | ||
Defining an array of pointers works the same way as defining any other array does, so to define an array of GUI*s called myguis to hold 5 GUI*s, you would type: | Defining an array of pointers works the same way as defining any other array does, so to define an array of GUI*s called myguis to hold 5 GUI*s, you would type: | ||
| Line 107: | Line 100: | ||
The String type isn't one of AGS's managed types, nor can you create a pointer to it. So why then am I bringing it up? The fact is, the String type is actually internally defined as a pointer, which is how it is able to have it's virtually infinite maximum length. | The String type isn't one of AGS's managed types, nor can you create a pointer to it. So why then am I bringing it up? The fact is, the String type is actually internally defined as a pointer, which is how it is able to have it's virtually infinite maximum length. | ||
Prior to AGS 2.71, AGS used the now deprecated string type. The string type was internally defined as an | Prior to AGS 2.71, AGS used the now deprecated string type. The string type was internally defined as an {{link|Script language keywords|Arrays|array}} of 200 characters ('''char'''s). This meant that strings had a maximum length of 200 characters themselves. | ||
With the introduction of AGS 2.71 came the new String type which removed that limit. And how did it do it? It used a pointer. Not an AGS-style pointer, but a pointer nonetheless. In programming languages such as C and C++, a pointer-to-char (char*)<sup>7</sup> creates a special type of pointer. Instead of just pointing to one single variable, a char* can point to a virtually infinite number of chars in the form of what is known as a string-literal (such as "this is some text"). | With the introduction of AGS 2.71 came the new String type which removed that limit. And how did it do it? It used a pointer. Not an AGS-style pointer, but a pointer nonetheless. In programming languages such as C and C++, a pointer-to-char (char*)<span id = "ref_7"><sup>{{link||end_7|[7]}}</sup></span> creates a special type of pointer. Instead of just pointing to one single variable, a char* can point to a virtually infinite number of chars in the form of what is known as a string-literal (such as "this is some text"). | ||
Since AGS uses a special type of pointer for managing the String type, it can still hold the value '''null''' (this is what Strings are initialized to), and when used as a function parameter, can be made optional in the same manner (see the section on [[#Optional_Pointer_Parameters|optional parameters]] for more information). | Since AGS uses a special type of pointer for managing the String type, it can still hold the value '''null''' (this is what Strings are initialized to), and when used as a function parameter, can be made optional in the same manner (see the section on [[#Optional_Pointer_Parameters|optional parameters]] for more information). | ||
===Script O-Names=== | ===Script O-Names=== | ||
| Line 124: | Line 115: | ||
For all we know the gui array itself could be an array of pointers to something stored deeper within the bowels of AGS, but it's not really important as in the end they would still both point to the same GUI, and this is just an example anyway. | For all we know the gui array itself could be an array of pointers to something stored deeper within the bowels of AGS, but it's not really important as in the end they would still both point to the same GUI, and this is just an example anyway. | ||
Using an integral system you would have to acess the gui array any time you wanted to perform any operations on the GUI<sup>8</sup>. So, if we wanted to move MYGUI to (30, 120), in an integral system we could do this: | Using an integral system you would have to acess the gui array any time you wanted to perform any operations on the GUI<span id = "ref_8"><sup>{{link||end_8|[8]}}</sup></span>. So, if we wanted to move MYGUI to (30, 120), in an integral system we could do this: | ||
gui[MYGUI].SetPosition(30, 120); | gui[MYGUI].SetPosition(30, 120); | ||
| Line 133: | Line 124: | ||
So it makes our code a bit shorter then, but it's essentially the same. All-in-all not a particularlly convincing example. So let's take a look at another built-in pointer: '''player'''. | So it makes our code a bit shorter then, but it's essentially the same. All-in-all not a particularlly convincing example. So let's take a look at another built-in pointer: '''player'''. | ||
===Player Keyword=== | ===Player Keyword=== | ||
| Line 168: | Line 157: | ||
===File*=== | ===File*=== | ||
Another example can be seen if we look at the | Another example can be seen if we look at the {{link|File functions and properties||File}} type. | ||
In an integral system, you would access an external file like this: | In an integral system, you would access an external file like this: | ||
| Line 220: | Line 209: | ||
==Extending The Built-In (Managed) Types== | ==Extending The Built-In (Managed) Types== | ||
Now that we've seen what pointers are, how they are used, how they relate to AGS, and some basic uses of them, let's take a look at a different kind of usage. In AGS we can create our own custom-defined datatypes using | Now that we've seen what pointers are, how they are used, how they relate to AGS, and some basic uses of them, let's take a look at a different kind of usage. In AGS we can create our own custom-defined datatypes using {{link|Script language keywords|struct}}. | ||
You define a struct like this: | You define a struct like this: | ||
| Line 232: | Line 221: | ||
That would create a new datatype called MyStruct which would have two data members and one member function. You could then create a variable of this type, and do all sorts of fun things with it. Though it's uses don't end there. | That would create a new datatype called MyStruct which would have two data members and one member function. You could then create a variable of this type, and do all sorts of fun things with it. Though it's uses don't end there. | ||
You can also make a pointer a member of a struct<sup>9</sup>, which provides some interesting possibilities. With a pointer as a member, you can essentially extend built-in datatypes (i.e., the managed types). | You can also make a pointer a member of a struct<span id = "ref_9"><sup>{{link||end_9|[9]}}</sup></span>, which provides some interesting possibilities. With a pointer as a member, you can essentially extend built-in datatypes (i.e., the managed types). | ||
===Extending the Character Type=== | ===Extending the Character Type=== | ||
| Line 263: | Line 250: | ||
=Closing= | =Closing= | ||
So you came to me with questions, and I hope I've answered some of them at least. In any case I hope I answered the ones you had about pointers and their usage in AGS. If you have any questions or comments you can | So you came to me with questions, and I hope I've answered some of them at least. In any case I hope I answered the ones you had about pointers and their usage in AGS. If you have any questions or comments you can {{forumPM|ags_id=2015|name=me}} on the AGS forums, or email me at {{email|monkey.05.06@gmail.com}} any time. Thanks for reading my article, and I hope you've enjoyed it as much as I enjoyed writing it. | ||
monkey_05_06 | monkey_05_06 | ||
=Notes= | =Notes= | ||
<span id = "end_1">1. {{link||ref_1|^}} The String type is only defined as of AGS v2.71 and higher. Older versions use the now deprecated string type.</span> | <span id = "end_1">1. <sup>{{link||ref_1|^}}</sup> The String type is only defined as of AGS v2.71 and higher. Older versions use the now deprecated string type.</span> | ||
<span id = "end_2">2. <sup>{{link||ref_2|^}}</sup> The length for Strings is limited by your computer's physical memory. A String will take up 4 bytes of memory, plus 1 byte for each character it contains.</span> | |||
<span id = "end_3">3. <sup>{{link||ref_3|^}}</sup> Floating-point decimals won't always evaluate as you might expect when doing certain mathematical operations (this is due to their precision levels). See the manual entry on {{link|Script language keywords|Data types|data types}} for more information.</span> | |||
<span id = "end_4">4. <sup>{{link||ref_4|^}}</sup> AGS's managed types are those listed here. You cannot create a new managed type within AGS's scripts; to create a new managed type you would need to write a plugin. Some module writers may use the keyword ''managed'' to prevent users from creating instances of structs that are meant to be used statically. This does not however make the type managed. Only AGS's built-in managed types and any managed types created via plugins are actually managed, and therefore are the only types that can have pointers to them.</span> | |||
<span id = "end_5">5. <sup>{{link||ref_5|^}}</sup> Not all of the managed types are meant to have pointers to them. Game, Maths, Parser, and Room do not need pointers (you can't even assign them a value).</span> | |||
<span id = "end_6">6. <sup>{{link||ref_6|^}}</sup> The asterisk doesn't necessarily have to be attached to the name of the pointer, such as "GUI *MyGUIPointer", it can also be attached to the data type itself, such as "GUI* MyGUIPointer". However, it will still be compiled as if it is attached to the name of the pointer, not the data type, so if you define multiple pointers at once, you will still need an asterisk for each pointer.</span> | |||
<span id = "end_7">7. <sup>{{link||ref_7|^}}</sup> In AGS you can't create a char*, as char isn't one of AGS's managed types. This type of pointer is used in scripting languages like C and C++. For storing string-literals AGS uses the String type (or the string type for AGS versions prior to 2.71).</span> | |||
<span id = " | <span id = "end_8">8. <sup>{{link||ref_8|^}}</sup> I have taken the liberty here of envisioning an integral system set up much as AGS 2.7+ is set up, only since it is an integral system it uses integers instead of pointers. In this example AGS structs still have member functions, and all other non-pointer-related functionality of AGS is the same.</span> | ||
<span id = " | <span id = "end_9">9. <sup>{{link||ref_9|^}}</sup> Structs can only have pointers as members in AGS 2.71 and later.</span> | ||
[[Category:Intermediate Tutorials]] | [[Category:Intermediate Tutorials]] | ||