Changes between Initial Version and Version 1 of GUI_-_Data_Types

Timestamp:

Feb 23, 2008, 4:19:00 AM (16 years ago)

Author:

trac

Comment:

--

GUI_-_Data_Types

@@ +1 @@
+This section defines the types of values permissible as specified in [wiki:GUI_-_Properties object properties].
+
+== string ==
+Just a free string with the inclusion of any characters if nothing else is specified.
+== name ==
+name is almost like string, except that it has to follow the standard naming convention for GUI variables (ie alphanumerics and underscores).
+== int ==
+Just a plain integer such as "-10" or "1024". If you enter in the form of a float value it will work too, but it will be cast to an integer with regular C++ truncation.
+== float ==
+Float value, like "2.32" or ".0001". If you input it in the form of an integer that�s fine too.
+== bool ==
+A boolean value can be either 1 or 0, on or off. These values can be set to "true" or "false" (case sensitive).
+== enum ==
+This can be a number of strings, and those are always shown in a comment. Check textalign for instance where you have an enum that can be "left", "center" and "right" (case sensitive).
+== color ==
+A color value can be entered in many different ways, usually with 3 or 4 (alpha) 1-byte integers with a blank space delimiter: like "255 255 255" or "0 0 0 100".
+Also a standard setup of colors can also be used, such as: "black", "white", "blue", "red" (case sensitive). "black" for instance would be the equivalent of "0 0 0".
+== rect ==
+Rectangle with 4 integer values: left, top, right and bottom (in that order). The delimiter of the values are a blank space so it could look like "0 0 100 200".
+== pos ==
+A position: x, y (in that order). It can look something like "25 100".
+== list ==
+The list data type is a list of strings. It is used in controls such as [wiki:GUI_-_List List] and [wiki:GUI_-_Drop-down Drop-down]. Due to its complexity it cannot be defined with a string, and relies solely on the <item> tag, like this:
+
+{{{
+  <object type="list"
+          name="my_list_control"
+  >
+          <item>Select 1</item>
+          <item>Select 2</item>
+  </object>
+}}}
+
+To manipulate the list with Javascript, see [wiki:Exposed_GUI_Functions#List_functions List functions].
+
+== client area ==
+The exact position and size of a rectangle relative to a parent rectangle; The area of the screen (client area) that the object occupies. For instance an object relative to the screen rectangle, or a texture tiling within the image rectangle. 
+
+It includes both pixel modifier and percentage modifier. Examples: "0 0 100% 100%", "50%-10 50%+10 50%-10 %+10". It is similar to a rect, but you can use [percentage][+-][pixel] for each value.
+
+=== Examples ===
+The client area is a bit confusing at first, but once you understand its concept, it's not so intimidating.
+The GUISize Properties are a bit confusing at first, but once you understand them they aren�t so intimidating.  As you will later see, the client area not only accounts for the size of the object, but also its position.
+
+The most commonly used client area is the object's [wiki:GUI_-_Properties#size size] property, let's use this as basis for our example.
+
+Here is how you may perhaps see a size function displayed in a user interface xml file (expanded for ease of reading):
+
+{{{
+  <object 
+        name =          "pregame_mp_modesel_titlebar" 
+        type =          "button" 
+        absolute =      "false" 
+        size =          "50%-150 10%+9 50%+150 10%+25" 
+        font =          "prospero18" 
+        sprite =                "0ad_window_title" 
+        text_align =    "center" 
+        text_valign =   "center"
+  >
+  </object>
+}}}
+
+We are focusing on the size parameter.  Notice there are four groups of numbers separated by a space.  
+
+{{{
+  "50%-150 10%+9 50%+150 10%+25" 
+}}}
+
+More specifically it can be broken down as corners of the sized object
+
+{{{
+  Left/Top: 50%-150 10%+9
+  Right/Bottom: 50%+150 10%+25
+}}}
+
+Therefore it may be further broken down to:
+
+{{{
+  "relative_left<+/->left
+  relative_top<+/->top
+  relative_right<+/->right
+  relative_bottom<+/->bottom"
+}}}
+
+�Relative� means relative to the parent object�s properties.
+
+Now that this is clear as mud, lets try some examples.
+
+[[Image(http://wildfiregames.com/~code/resources/wiki/gui/sizexample.gif)]]
+
+The above image is a shrunken down version of a computer screen.  Its size is 400x300, but let us pretend it is 800x600 in reality (easier to work with than 1024x768 for those who are not comfortable with their ^2 numbers).  Each box in the grid is therefore equal to a 40x40 square.
+
+'''Box 1'''
+
+''Option 1:''
+
+The quickest and easiest way to size it would be: "80 80 720 520" 
+Or to be precise: "0%+80 0%+80 0%+720 0%+520"  (but you don't need to specify 0% values.)
+
+This spaces the object 80 pixels away from the top left corner of the 800x600 screen, giving us a box that is 640px wide and 440px tall.
+
+A potential issue with this method is that if the screen resolution changed, �Box 1� would always be this size relative to the top left corner of the screen.  So if the screen resolution was changed to 1024x768, �Box 1� would remain 640x440 in size, and it would stay 80 pixels from the left and 80 pixels from the top. 
+
+''Option 2:''
+
+What if we wanted it to always look as it looks now -- proportional to the screen, no matter the resolution?  Here is how.  Remember that 80 pixel space.  Keep in mind that 800/80 = 10% and 600/80 = 7.5%: "10% 7.5% 90% 92.5%"
+
+Why the 90% and 92.5%?  Well because that is saying that the right side is 90% (100%-10%) the width of the parent, and the bottom edge is 92% (100%-7.5%) the height of the parent.
+
+This will also give us a 640x440 rectangle, but only when the resolution is 800x600.  If we changed the resolution up to 1024x768 then the rectangle would grow to be 819.2x652.8, but it would remain in the center, and it would have a space at the top and bottom that was 7.5% of the height and a space on the left and right that was 10% the width.
+
+''Option 3:''
+
+What if we wanted the box to always remain the same size, and if we wanted it to remain in the center of the screen?  For this, we will need to use a mixture of both the relative percentages and the absolute pixels.  Here is the answer: "50%-320 50%+220 50%+320 50%-220"
+
+Let�s break it down.  The relative portion (50% 50% 50% 50%) is basically just defining a point on the screen; there is no area involved.  All four corners of that rectangle are exactly the middle of the parent object (in our case the screen).  
+
+We need to open the rectangle back up with the absolute pixel offsets.  We can do this by looking at the absolute portion (-320 +220 +320 -220) (Remember left and down is negative, and up and right is positive in math class) This is saying that the left size is going to be defined 320 pixels to the left of the relative position.  The top is 220 pixels above the relative position.  The right is 320 pixels to the right and the bottom is 220 pixels down.
+
+'''Box 2'''
+
+That wasn�t so bad was it?  Lets do another, and let�s assume we went with Option 3 for �Box 1� and that �Box 2� is a child of �Box 1�.  This means that our box we are working with will always be in the center of the screen and it will always be 640x440.  Knowing that �Box 1� is pretty absolute, it probably won�t hurt to make �Box 2� absolute either by doing this:  "80 80 400 160"
+
+Not too bad; notice also that it is not "160 160 480 240".  Why? Because the parent of �Box 2� is not the screen, it is �Box 1�.
+
+'''Box 3'''
+
+We would probably want to make this absolute also, but for fun let�s make it relative in some weird ways.
+
+Let�s say I want to make it relative to the top left of �Box 3�.  To make it easy, I�ll just count squares when doing my math.  
+
+The parent (Box 1) is 16x11, the top left corner is 12x2 so 12/16=75% and 2/11=18.181818%.  
+
+Left and right are going to use the 75% and top and bottom the 5.5%; that gives me "75% 18.181818% 75% 18.181818%".  
+
+Because I�m using the top left of "Box 3", I�m going to need to expand my �point� to the right 80 and down 80 which gives me: "0 0 +80 -80".  I�ll put it together, and do a few other variations:
+
+Relative to the top left of �Box 3�: "75% 18.181818% 75%+80 18.181818%-80%" (no need for 0�s)
+
+Relative to the middle of "Box 3": "81.25%-40 27.272727%+40 81.25%+40 27.272727%-40"
+
+Easy/Simple way: "480 80 560 160"
+
+'''Box 4'''
+
+Let�s hypothetically make this one expand horizontally, but be locked to 80 pixels in height.  I�m going to want my left and right edges relative, and my top and bottom absolute.  Here is how it looks:  "31.25% 240 68.75% 320"