Lack of api documentation. #27
Description
There is a clear lack of documentation for the key components of the api. This will be fully addressed in the March release. The next few weeks will be dedicated to fully documenting the majority of the api.
So far the rendering process has been documented. This includes, Window, Container, Overlay, and the individual overlay classes. The RenScene and Story has also been completely documented. Will be working on finishing the individual scenes and the other api classes.
Constructors and classes have been the main focus of documentation and providing code example inside of them. Important methods have also been documented but I'm hesitant to completely document every function. The framework is prone to changes and wasting time documenting functions that may be removed is pointless.
Examples
These are current examples of what has been documented.
/**
* The ButtonOverlay is a visual element that displays a button. A button can contain text or an image, and stylized borders and backgrounds.
* To handle a button use the generic {@link #onClick(IOverlayClick)} method.
* <p>
* <pre>
* {@code
* ButtonOverlay button = new ButtonOverlay("button-id", "Button", Color.BLACK);
* button.onClick(event -> {
* // Handle click action.
* System.out.println("Clicked on 'button-id'");
* });
* }
* </pre>
* <p>
* A button is also a {@link Region} which means it has a shape. The shape for an image is a box around the button. The specific can have a specified width and height. A bigger width and height will enlarge the button.
* <pre>
* {@code
* ButtonOverlay button = new ButtonOverlay("button-id", "Button");
* button.setWidth(width);
* button.setHeight(height);
* }
* </pre>
* <p>
* A button can display an {@link ImageOverlay} rather than text. The positioning and rendering of the image can also be modified. The {@link #isAlignGraphicToBox()} controls if the images should automatically align within the button.
* The {@link #getTopImage()} will track the last displayed image on the button.
* <pre>
* {@code
* ButtonOverlay button = new ButtonOverlay("button-id", new ImageOverlay("path/to/image.png");
*
* // You can also add mulitiple images to a button
* button.addImage(new ImageOverlay("path/to/image.png");
* }
* </pre>
*
* @see Overlay
* @see Region
* @see ImageOverlay
*/
public class ButtonOverlay extends Overlay implements Region {} /**
* Creates an ImageOverlay given the file path from the game directory.
* <p>
* <pre>
* Below is an example directory tree.
* MyGame
* Lgame
* Limages
* Limage.png
* Lsubdir
* Limage.png
* </pre>
* <p>
* The base path is assumed to be the 'images' folder. To load an image from the base path (game/images/image.png), pass "image.png".
* <pre>
* {@code
* ImageOverlay image = new ImageOverlay("image.png"); // The file location would be /game/images/image.png
* }
* </pre>
* <p>
* To load an image from a subdirectory you must declare the subdirectory (game/images/subdir/image.png), "subdir/image.png"
* <pre>
* {@code
* ImageOverlay image = new ImageOverlay("subdir/image.png"); // The file location would be /game/images/subdir/image.png
* }
* </pre>
* @param imagePath The path to the file from the game directory.
*/
public ImageOverlay(String imagePath) {} /**
* Sets the beginning {@link Transitions} for the scene. The transition is played and handled by the engine automatically.
*
* @param transition The transition to be played at the beginning the of scene.
* @return The modified RenScene.
*
* @see FadingTransition
* @see ImageFlashTransition
*/
public RenScene setBeginningTransition(Transitions transition) {}