ScrapWorks

textgraphics1 v0.0.4 Docs

Note: to install the textgraphics module, use the command ‘pip install -U textgraphics1‘ in your terminal or command prompt.

 

textgraphics1 is a module for generating text-based images and ASCII based graphics. It can currently generate rectangles, lines, text, and custom textures. textgraphics1 uses a string naming system to organize and identify objects and sprites generated with the library.

Prerequisites:

Defining Objects:

The system of identifying and modifying sprites in the text graphics engine are different from most libraries. With most functions there is a name parameter, the name parameter can be filled with any string. If multiple objects share the same name, then they will be interpreted as a group, and any function that is used with it will modify anything under that name. That is why that system is used, to help easily group and modify items using string naming.

Coordinate System:

The coordinate system used is similar to the tkinter module, the coordinate (0, 0) starts at the top left hand corner of the object. Assuming the window is 2 by 2, identifying the most far right and down coordinate would be (1, 1). The first coordinate on the grid is identifiable at (0, 0).

Extra Notes:

  • if an object is outside of the border, than the engine will not interpret the missing pixels as occupied, the only objects that are referenced as being occupied are those inside the grid

 

 

Initializing:

Assuming you have correctly installed the module, we recommend that you use the ‘from‘ method to import the module, as it makes the usage much easier and cleaner. The module for the graphics is titled text_graphics, unlike the actual package.

from textgraphics1 import *

or

from textgraphics1 import text_graphics

 

Once that is done, to create an instance of the engine, simply define it with a new variable. The __init__ function takes three arguments, width, height, and border.

win = text_graphics(width=20, height=10, border=True)

We recommend setting the width of the window to two times the height if you want a square window, as many fonts are taller than they are wider. Also, if you plan to use other fonts, make sure every character matches in dimensions so the image does not look warped or strange, we recommend Courier, as we like the look.

width will set the width of the canvas (int)

height will set the height of the canvas (int)

border will turn the border on or off (boolean)(True/False)

Once it is initialized, nothing will happen just yet.

Rendering:

Once an instance is defined, the image can be rendered. Rendering will not print the graphics, it will only prepare it to be printed or returned.

If you would like a newly created shape to appear and be recognized as part of the image, you must call the render function first.

win.render()

render‘ takes no arguments and will simply prepare the image to be displayed. This function will be used to “update” the image.

Printing:

If you would like the text to easily be printed with one line, the built-in print method can do it.

win.print(spacing=10)

spacing will set the number of newlines printed before the image, useful for a stop-motion style. (int)

The print function will only print what has been rendered last, and will not automatically render the next image.

Returning the render:

Assuming you don’t want to use the built-in print method, this can be used to just return the text as rendered.

win.return_text()

return_text’ takes no arguments.

The return text function will only return what has been rendered last, and will not automatically render the next image.

Creating a text element/object:

With this function, a text element will be added to the rendering list. Text objects insert text into the specified coordinates. Spaces are counted as “taking up space”, so anything behind them will be hidden, and newlines are ignored. If the name of an object already shares the name and type of that object, the package will simply modify the old object unless modify is set to False.

win.create_text(name, xpos=0, ypos=0, contents=’Text’, modify=True)

name will give the object a name that can be used to modify/reposition the object later. (string)

xpos will set its x position on the grid (int)

ypos will set its y position on the grid (int)

contents will set the contents of the element (its text) (string)

modify will enable or disable the ability to modify an object with the same name and type based on input (Boolean)(True/False)

Creating a rectangle element/object:

This function will add a rectangle to the rendering list. Rectangles are solid objects that take up all space within the two specified coordinates. If the name of an object already shares the name and type of that object, the package will simply modify the old object unless modify is set to False.

win.create_rectangle(name, xpos=0, ypos=0, x2pos=10, y2pos=5, fill_character=’0′, modify=True)

name will give the object a name that can be used to modify/reposition the object later. (string)

xpos will set the x position on the grid of the first coordinate (int)

ypos will set the y position on the grid of the first coordinate (int)

x2pos will set the x position on the grid of the second coordinate (int)

y2pos will set the y position on the grid of the second coordinate (int)

fill_character will set the character that will fill the occupied spaces of the rectangle

modify will enable or disable the ability to modify an object with the same name and type based on input (Boolean)(True/False)