AGS Pointers for Dummies: Difference between revisions

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'''{{footnote parent|1}}, 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''{{footnote parent|2}} infinite length. A '''float'''-type variable can store floating-point decimals within the range -2147483648.0 to 2147483647.0, and has precision{{footnote parent|3}} up to approximately 6 decimal places, though this will vary based on the actual number.

In AGS, you can only create pointers to certain data types. These are called the ''managed'' types{{footnote parent|4}}.

AGS has certain ''managed'' types{{footnote alt parent|4}} that you can not create an instance (variable declaration) of, but you ''can'' create pointers to{{footnote parent|5}}.  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}}.

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 (*){{footnote parent|6}}, 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:

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*){{footnote parent|7}} 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").

Using an integral system you would have to acess the gui array any time you wanted to perform any operations on the GUI{{footnote parent|8}}. So, if we wanted to move MYGUI to (30, 120), in an integral system we could do this:

You can also make a pointer a member of a struct{{footnote parent|9}}, which provides some interesting possibilities. With a pointer as a member, you can essentially extend built-in datatypes (i.e., the managed types).

{{footnote text|1|The String type is only defined as of AGS v2.71 and higher. Older versions use the now deprecated string type.}}

{{footnote text|2|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.}}

{{footnote text|3|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.}}

{{footnote text|4|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.}}

{{footnote text|5|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).}}

{{footnote text|6|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.}}

{{footnote text|7|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).}}

{{footnote text|8|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.}}

{{footnote text|9|Structs can only have pointers as members in AGS 2.71 and later.}}