User:Jbob::Apps/sandbox

ZenFrame
An application framework for the Creative Zen Xfi2

Libraries included


 * Canvas        (A system of organization, separating different menus into 'screens')
 * Colors        (A list of colors that can be accessed)
 * Debugger      (Outputs current tasks only if enabled)
 * ErrorHandler  (Handles any errors caused by the framework)
 * Function      (An assortment of useful functions)
 * Graph         (Creates/Draws a graph)
 * Memory Handler (Automatically cleans memory as needed)
 * Resources     (Handles image/sound loading/unloading. Automatically unloads all resources when disposed.)
 * TexturePack   (Parse texture packs for the Resources library)
 * ZenFrame      (Loads/Disposes libraries used by the framework)

ZenFrame API
ZenFrame.initialize(libDir (string) ) Starts the framework, loading all libraries. The variable libDir points to ZenFrame's location, e.g. 'ZenFrame/'.

ZenFrame.dispose Unloads all libraries used by ZenFrame from ram. This should be called at when an application is exited.

Canvas API
Canvas.initialize(screenDir (string) ) Starts the canvas library. The argument screenDir should be the location where the screen files are store, e.g. 'screens/'.

Canvas.setScreen(screenName (string) ) Changes which screen Canvas displays. The argument screenName should be the filename of a screen, e.g. 'Menu' (ignore .lua)

Canvas.present(x (number) ,y (number) ) This function should be called every frame, because it updates the current screen. The arguments x and y are touch coordinates.

Canvas.dispose This function should not be called manually, instead ZenFrame.dispose should be called. This will partially unload the canvas library from ram. References to the module will still exists in the registry.

Colors API
All colors listed below are constants, so should be used.


 * Colors.black
 * Colors.blue
 * Colors.brown
 * Colors.gray
 * Colors.green
 * Colors.gold
 * Colors.gold
 * Colors.orange
 * Colors.pink
 * Colors.purple
 * Colors.red
 * Colors.white
 * Colors.yellow

Colors.dispose This function should not be called manually, instead ZenFrame.dispose should be called. This will partially unload the colors library from ram. References to the module will still exists in the registry.

Debugger API
The following are constants, so should not be used.
 * Debugger.isZen (Returns true if the code is executing on the Zen and not the simulator)

Debugger.enable Enables the debugger, allowing ZenFrame to output what it is currently doing.

Debugger.disable Disables the debugger, preventing ZenFrame from outputting what it is currently doing.

Debugger.log(message (string) ) Outputs the message to the output window in the simulator. If the debugger is  disabled, then nothing will print.

Debugger.logFPS Draws the frames-per-second on the top-right of the Zen. If used, it should be called every frame.

Debugger.time Returns the current time in a similar format on the Zen and the simulator.

Debugger.dispose This function should not be called manually, instead ZenFrame.dispose should be called. This will partially unload the debugger library from ram. References to the module will still exists in the registry.

ErrorHandler API
ErrorHandler.enable Enables the errorhandle, allowing ZenFrame to output any errors reported.

ErrorHandler.disable Disables the errorhandle, preventing ZenFrame from outputting any errors reported.

ErrorHandler.logEroror(errorFile (string) ,errorFunction (string) ,errorReason (string) ) Outputs an error to the output window on the simulator. The argument errorFile is the file which the error is from, errorFunction is the function which caused the error, and errorReason is the reason why an error occurred.

ErrorHandler.dispose This function should not be called manually, instead ZenFrame.dispose should be called. This will partially unload the errorhandler library from ram. References to the module will still exists in the registry.

Functions API
Functions.pointInRectangle(x (number) ,y (number), rX (number) ,rY (number) ,rW (number) ,rH (number) ) Checks if x and y are within the rectangle of rX,rY,rW,rY. If they are, then it returns true, if not then false is returned.

Functions.deepCopy(object (any variable) ) Returns an exact copy of object. This function should be used to copy a table, in order to  separate the metatables of the copy from the original.

Functions.unrequire(libName (string) ) Removes references of the library from the registry. The argument libName should be the path used to require the library.

Graph API
Graph.initialize(rows (number) ,columns (number) ) Creates a graph that with a specified number of rows and columns. The number of rows and columns must both be even, if not they will automatically increased by 1.

Graph.setEquations(equations (table) ) Updates the equations that will be graphed. The table should be multidimensional. So the first sub table index (equations[#][1]) should be the equation (no equals sign), and the second sub table index (equations[#][2]) should be the color of the equations (e.g. Colors.blue). Graph.getEquations Returns the current equations in a multidimensional table. See Graph.setEquations for documentation on  the table layout.

Graph.parseEquations Returns a user-friendly version of the equation table. API references, such as math.sin, are turned into normal math terms.

Graph.setSize(rows (number) ,columns (number)) Changes the graph size to the specified number of rows and columns. The number of rows and columns must both be even, if not they will automatically increased by 1.

Graph.draw Draws the graph. Any equation that is empty will be skipped.

Graph.dispose This function should not be called manually, instead ZenFrame.dispose should be called. This will partially unload the graph library from ram. References to the module will still exists in the registry.

MemoryHandler API
MemoryHandler.monitor Allows the memoryhandler to preform garbage collection once the memory limit is reached.

MemoryHandler.stopMonitoring Prevents the memoryhandler form preforming garbage collection once the memory limit is reached.

MemoryHandler.setMemLimit(memoryLimit (number) ) Sets the memory limit, which is the amount of ram that can be used. If this amount is exceeded, then the ram will be cleared.

MemoryHandler.clean Clears the screen buffer and preforms a  garbage collection.

MemoryHandler.update If monitoring is allowed, then this will automatically clean the ram when the memory limit is reached. This function should be called every frame.

MemoryHandler.dispose This function should not be called manually, instead ZenFrame.dispose should be called. This will partially unload the memoryhandler library from ram. References to the module will still exists in the registry.

Resources API
Resources.initialize(gfxDir (string) ,sfxDir (string) ) Starts the Resources library, setting the location of images to gfxDir, and sound to sfxDir.

Resources.loadPack(id (string) ,packName (string) ) Loads a texture pack. The argument id is the name of the id used to identify the regions in the texture pack. If the texture pack contains more than one image-atlas, the id will change for each image-atlas. The first image-atlas will simply have the id of the argument id, the second image-atlas will have the id, id_1, the third image-atlas will have the id, id_2, and so on. The argument packName should be the filename of the texture-pack config file, e.g. ui.pack.

Resources.loadImage(id (string) ,imageName (string) ) Loads an image with the name of the imageName argument, and assigns it the id of the id argument.

Resources.createImageRegion(imageID (string) ,id (string) ,x (number) ,y (number) ,width (number) ,height (number) ) Creates a region, with the id of the id argument, in the image with the assigned id of the argument imageId. The arguments x,y,width,height are the location of the region on the image, essentially x,y are where to start 'cropping', and width,height are how far over to 'crop' the image.

Resources.loadSound(id (string) ,soundName (string) ) Loads a sound with the name of the soundName argument, and assigns it the id of the id argument.

Resources.unloadImage(id (string)) Unloads the image with the id of the id argument, and unloads all regions associated with the image.

Resources.removeImageRegion(imageID (string) ,id (string)) Unloads the region, with the id of the id argument, that is associated with the image that has the id of the imageId argument.

Resources.unloadSound(id (string)) Unloads the sound with the id of the argument id.

Resources.getSound(id (string)) Returns the sound with the same id as the id argument.

Resources.getImage(id (string)) Returns the image with the same id as the id argument.

Resources.getImageRegion(imageID (string) ,id (string)) Returns the region with the same id as the id argument. The region returned will be from the image that has the same id as imageId.

Resources.drawImageRegion(imageID (string), id (string) ,x (number) ,y (number) ) Draws the region with the id of the id argument, at x,y. The imageId argument is the id of the image from which the region is from.

Resources.dispose This function should not be called manually, instead ZenFrame.dispose should be called. This will partially unload the resources library from ram, and unload all images,region, and sounds. References to the module will still exists in the registry.

TexturePack API
TexturePack.parse(id (string) ,file (string)) Parses a texture-pack that is stored at the argument file. All image's and region's ids will be based off of the id argument. This function should not be called, but rather Resources.loadPack