Documentation for V1.1
XBOX SPECIFIC INFORMATION AT THE BOTTOM
For an intro on how to setup a basic project in either V1 or V1.1 see... BasicSetupV1V1.1
Version 1.1 is an addition to the X86 version of V1
All of the functionality in V1 is the same, I will list the additions in V1.1 here.
NOTE:
If you see a function whose name begins with xml do NOT use it. It is for XML serialization and deserialization ONLY.
AndrewsXnaHelpers.XML
New namespace that contains 2 classes to aid in XML serialization.
_XmlSerializer
This class contains gets and sets to access File paths and file names for both read and write operations.
Functions of interest are as follows.
NOTE:
Path and filename should look like the following.
@"C:\Users\Andrew Black\Desktop" or "C:\\Users\\Andrew Black\\Desktop" if you include the \ after desktop it will fail.
File names
"file1" NOT "file1.xml" the .xml is added automatically
File names have to comply with windows naming so do not add symbols such as * , ^ , % or anything windows wouldn't let you do.

public string Write_Path
Gets or sets the write path for the serializer
public string Write_FileName
Gets or sets the write file name for the serializer
public string Read_Path
Gets or sets the read path for the serializer
public string Read_FileName
Gets or sets the read file name for the serializer

public void Serializer<XmlType>(object objectToSerialize)
Serializes the object passed to the <XmlType> passed at the current write path and write file name.
public XmlType Deserialize<XmlType>()
Deserializes the XML file at the current read path and read file name and returns it as the Type specified by XmlType
Using the serializer
First you have to create a new instance of the XmlSerializer, the constructor takes 2 arguments, an initial file path and intial name. This is copied to both WritePath, WriteFileName, ReadPath, Read_FileName but they can be changed independently later.

So creating a new instance should look like
XmlSerializer mySerializer = new XmlSerializer(@"C:\Users\Andrew Black\Desktop", "testFile");

NOTE:
Serializing objects is not done automatically, if it is a class you created then you have to make sure it is setup to be serialized properly I will post tutorials on how to do is in the near future. Any class that you can use in this library however has been setup to be serializable.

To serialize an object that is setup to be serialized you would call
mySerializer.Serialize<MyClass>(myClassInstance);
It will then write that class to an Xml file at the current Write Path and Write File name

To deserialize an Xml file to an object all you have to do is
myClass = mySerializer.Deserialize<MyClass>();
It will read in the Xml file that is at the specified Read path and Read file name.
QuickSerializer
A static version of the _XmlSerializer with a few differences.
It does not store any paths or file names for you, you will have to manage those yourself.
This class is more useful for reading in things such as stat files or start options where the location is constant or known.

To use this all you do is
QuickSerializer.Serialize<XmlType>(string path, string filename, object obj)
Essentially the same as the _XmlSerializer only your supplying the path and filename.
QuickSerializer.Deserialize<XmlType>(string path, string filename)
Essentially the same as the _XmlSerializer only your supplying the path and filename.

Both of these functions work the same as their _XmlSerializer counterparts except these can be called anywhere without having to instantiate a class.

Personally I prefer the QuickSerializer and then write my own way of handling where to read and write from but both options are open. You could even use a combination of the two if you wanted.
AndrewsXnaHelpers.Helpers
4 new classes have been added to this namespace.
Box
BoxManager
Bar
BarManager

The Box class creates well as its name implies, a box.
The Bar class creates a bar with 2 rectangles, one for the background and the foreground.
This can be used for a health bar or any other UI item.
Both Bar and Box contain methods to modify the way they look and change their values.

The BarManager and BoxManager are non static classes that aid in creating multiple bars and boxes.
They work the same way only the data they hold is different.
NOTE:
The Bar, Box, BarManager, BoxManager class have all been setup to be serializable right off the bat
If you see any functions or methods with the xml prefix do NOT use them, they do not return the values implied by their names, many of them are converted to values that the Xml Serializer can serialize properly and then converted from that back to their original form.
Box
Methods and Functions
public string Name
Gets or sets the name of the Box
public Rectangle Rectangle
Gets or sets the current rectangle of the box
Constructors
There are numerous constructors for the Box class, I will lay out the basics as I have added a summary to them so the help will be shown by visual studios intellisense.
All of the constructors follow basic rules.
A name, a width, a height and then information that can be used during drawing such as a color to fill in the rectangle or a texture.
public Box(string name, int width, int height, Color color, Vector2 position)
this will create a new box with the specified name, width, height and filled with the specified color all at the passed position.

Now its time for the functions!
public void SetPosition(Vector2 position)
public void SetPosition(Point position)
public void SetPosition(int X, int Y)
All of these functions accomplish the same thing except they take different arguments.
For example, the first one sets the position of the X and Y to the X and Y values in the Vector2 the same goes for the others

public void ChangePosition(Vector2 position)
public void ChangePosition(Point point)
public void ChangePosition(int X, int Y)
All of these functions accomplish the same thing except they take different arguments.
What they do is they change the position of the Box by the specified amount. Say the Vector2 passed contains -5 and 1
The box will be moved to the left 5 pixels and down 1 pixel.

public void ChangeWidth(int amountToChange)
public void ChangeHeight(int amountToChange)
public void ChangeSize(Vector2 amountToChange)
These all accomplish a similar goal.
ChangeWidth this changes the width by the amount passed - so if its -5 the width is reduced by 5
ChangeHeight this changes the height by the amount passed - if its -5 its height is reduced by 5
ChangeSize changes both the width and the height by the amount in the vector2 - if it contains 5,2 its width will grow 5 and its height will grow 2.

public SetWidth(int newWidth)
public SetHeight(int newHeight)
public SetSize(Vector2 newSize)
Like the Change functions these work the same way.
Instead of changing the current size by the amount passed they are SET to the values passed.
If I pass 50 to the SetWidth it will be 50 pixels wide.
The same goes for ChangeHeight and ChangeSize

public void ChangeDrawMode(bool DrawAtOrigin)
this controls weather the box will be drawn at its origin or the upper left corner
By default this is false so pass true if you want it drawn at the origin and false if you dont

public void Enable()
public void Disable()
These control weather the box will draw
Fairly self explanatory Enable makes it draw, disable stops it from drawing.

public void Draw()
Draws the box using all the data set
BoxManager
Contains a list of Boxes and functions to add and draw multiple ones
DO NOT USE THE METHOD WITH THE xml PREFIX!

public Bar this[string name]
Lets you access it as a list.
Simply enter the name and it will return the box.
public Bar this[int index]
Again just like a list.
Simply enter the index and it will return the box.
NOTE:
public Bar this[int index] is faster than public Bar this[string name]

public void Add(Bar barToAdd)
Adds the bar passed to the list of bars.

public void Remove(string barName)
public void Remove(int index)
Removes the bar with either the name or at the specified index.

public void Clear()
Clears the list of bars

public void Draw()
Draws all of the boxes
Bar
Nearly identical to the Box class with a few differences.
public Rectangle BackgroundRectangle
public Rectangle ForegroundRectangle
Returns a rectangle of the background or foreground respectively.

Again do not use any of the methods with the xml prefix

Constructors
Identical to the Box classes constructors with a few differences but they follow the same rules.

public void SetPosition()
public void ChangePosition()
public void Enable()
public void Disable()
public void Draw()
All of these are identical to the ones in the Box class,even the arguments.
Bar specific functions

public void SetForeground(int width)
public void SetBackground(int width)
These set the foreground or the background respectively.

public void ChangeForeground(int amountToChange)
public void ChangeBackground(int amountToChange)
These change the foreground/background by the amount specified
Bar Manager
Identical to the Boxmanager class, except that it contains bars instead of boxes.
all of the methods, e.g. add, remove ect ect are all the same.

AndrewsXnaHelpers.Extenders
Many new functions added to both Texture2D extenders and Rectangle extenders.
Most notably are the DrawAtOrigin functions.
They are the same as the regular Draw functions except it is done at the origin.
The arguments are the same so its fairly straightforward.
Xbox 360 V1.1
Everything in the library is the same on the xbox 360 except the Xml serializer class.
Changes:
XmlSerialization tweaked to accomodate Xbox 360 file system
Setup changed to accomodate finding a appropriate hard drive to use
Couple changes to the gamepad class to make chatpads accessible.
ChatPad
Simply call InputHelper.UpdateGamePad() and the chatpads will be ready for use.
After that you can access them from calling InputHelper.GamePad.ChatPad then all of the methods are the same as the Keyboard class
New Setup
The new Variables.SetVariables method.

public static void SetVariables(string gameName, GraphicsDeviceManager, ContentManager, SpriteBatch)
The addition of a string that will represent where data is stored on the xbox 360 storage device.
Should be simple, just your games name, can name it TestGame or Monkey Island Adventure, it doesn't matter.
It WILL however show up in the Memory tab of the xbox 360 dashboard. think of it as the name of a folder for the xbox

In your update loop you should still be calling Variables.Update(gameTime) that is unchanged.

Before you can use anything that has to do with writing to the xbox storage device you have to make the user select what storage device they would like to use.
I've made this part very simple.
public static void GetStorageDevice()
simply have a condition for when the storage device will be selected then call the method listed above.
NOTE: You can NOT just throw this into your update loop as it will crash due to a "Guide already visible exception".

Your update loop should look like this.

if(InputHelper.GamePad.IsButtonPressed(PlayerIndex.One, Buttons.Start) && !Guide.IsVisible)
Variables.GetStorageDevice();

What you may also want to do is add a variable so that it knows it has already gotten the device, because this cannot be called more than once.

Now when using the XmlSerializer class the changes are very mild and actually make it easier to use.
All of the methods are the exact same way they were before, in both the QuickSerializer and _XmlSerializer classes.
Instead of supplying both a Path and filename it is now just a filename.
NOTE:
Files are saved as a .sav file not as a .xml file on the Xbox 360.

So for a simple serialization it would look something like...
QuickSerializer.Serialize<Bar>("BarFile",myBarManager);

Those are the changes for the Xbox version of V1.1
All of the other classes are exactly the same.

I will be making examples soon so keep an eye out and possibly a website of tutorials on things such as Xml Serialization along with some other programming tips.

Last edited Jun 9, 2010 at 3:57 PM by Destroyer229, version 16

Comments

No comments yet.