AGS Pointers for Dummies: Difference between revisions
→Added further description of managed types (vs custom types)
*>Monkey 05 06 |
|||
| Line 29: | Line 29: | ||
''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. | In AGS, you can only create pointers to certain data types. These are called the ''managed'' types<sup>4</sup>. | ||
<sup>4</sup>'''<font size="1">AGS's managed types are those discussed in the next section. 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.</font>''' | |||
==Managed Types== | ==Managed Types== | ||
AGS has certain ''managed'' types that you can not create an instance (variable declaration) of, but you ''can'' create pointers to<sup> | AGS has certain ''managed'' types 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: [http://www.bigbluecup.com/manual/Room%20_%20Screen%20functions.htm Room], [http://www.bigbluecup.com/manual/Game%20_%20Global%20functions.htm Game], [http://www.bigbluecup.com/manual/Parser%20functions.htm Parser], [http://www.bigbluecup.com/manual/File%20functions%20and%20properties.htm File], [http://www.bigbluecup.com/manual/Inventory%20item%20functions%20and%20properties.htm InventoryItem], [http://www.bigbluecup.com/manual/Overlay%20functions%20and%20properties.htm Overlay], [http://www.bigbluecup.com/manual/DynamicSprite%20functions%20and%20properties.htm DynamicSprite], [http://www.bigbluecup.com/manual/GUIFuncsAndProps.htm GUI], [http://www.bigbluecup.com/manual/GUI%20Label%20functions%20and%20properties.htm Label], [http://www.bigbluecup.com/manual/GUI%20Button%20functions%20and%20properties.htm Button], [http://www.bigbluecup.com/manual/GUI%20Slider%20properties.htm Slider], [http://www.bigbluecup.com/manual/GUI%20Text%20Box%20functions%20and%20properties.htm TextBox], [http://www.bigbluecup.com/manual/GUIInvFuncs.htm InvWindow], [http://www.bigbluecup.com/manual/GUI%20List%20Box%20functions%20and%20properties.htm ListBox], [http://www.bigbluecup.com/manual/Character%20functions%20and%20properties.htm Character], [http://www.bigbluecup.com/manual/GUI%20control%20functions%20and%20properties.htm GUIControl], [http://www.bigbluecup.com/manual/Hotspot%20functions%20and%20properties.htm Hotspot], [http://www.bigbluecup.com/manual/Region%20functions%20and%20properties.htm Region], [http://www.bigbluecup.com/manual/Maths%20functions%20and%20properties.htm Maths], [http://www.bigbluecup.com/manual/DateTime%20functions%20and%20properties.htm DateTime], and [http://www.bigbluecup.com/manual/Object%20functions%20and%20properties.htm Object]. | ||
<sup> | <sup>5</sup>'''<font size="1">Not all of the managed types are meant to have pointers to them. Room, Game, Parser, and Maths do not need pointers (you can't even assign them a value).</font>''' | ||
==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 asterik (*)<sup> | 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 asterik (*)<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: | ||
GUI *GUIPointer; | GUI *GUIPointer; | ||
| Line 43: | Line 44: | ||
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. | ||
<sup> | <sup>6</sup>'''<font size="1">The asterik 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 asterik for each pointer.</font>''' | ||
==Array of Pointers== | ==Array of Pointers== | ||
| Line 112: | Line 113: | ||
Prior to AGS 2.71, AGS used the now deprecated string type. The string type was internally defined as an [http://bigbluecup.com/manual/Arrays.htm array] of 200 characters ('''char'''s). This meant that strings had a maximum length of 200 characters themselves. | Prior to AGS 2.71, AGS used the now deprecated string type. The string type was internally defined as an [http://bigbluecup.com/manual/Arrays.htm 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> | 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"). | ||
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). | ||
<sup> | <sup>7</sup>'''<font size="1">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).</font>''' | ||
===Script O-Names=== | ===Script O-Names=== | ||
| Line 127: | Line 128: | ||
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> | 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: | ||
gui[MYGUI].SetPosition(30, 120); | gui[MYGUI].SetPosition(30, 120); | ||
| Line 137: | Line 138: | ||
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'''. | ||
<sup> | <sup>8</sup>'''<font size="1">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.</font>''' | ||
===Player Keyword=== | ===Player Keyword=== | ||
| Line 235: | Line 236: | ||
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> | 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). | ||
<sup> | <sup>9</sup>'''<font size="1">Structs can only have pointers as members in AGS 2.71 and later.</font>''' | ||
===Extending the Character Type=== | ===Extending the Character Type=== | ||