Building an API

I'm creating the Display API for ComputerCraft; a really simple and easy to use API to make your programs look prettier.

Additions so far:

centerPrint(text,y)
Prints your text directly in the center of the screen, and drops down a line.

centerWrite(text,y)
Prints your text directly in the center of the screen, however cursor is placed right after last character in string (similar to "term.write")

rightPrint(text,y)
Aligns your text to the right side of the screen, and drops down a line.

rightWrite(text,y)
Aligns your text to the right side of the screen, and places cursor after final character.

cls()
Shorthand for "term.clear() term.setCursorPos(1,1)"

text(color)
Shorthand for "term.setTextColor(color)"

bg(color)
Shorthand for "term.setBackgroundColor(color)"

setColor(mode,color) –suggested by TheOddByte
Sets the <mode> color to <color>

imageFromFile(filepath,x,y)
Instead of having two lines of paintutils, this function prints the image in the designated xy location right from the file.


What I want to know is… what would you like in this api? Let me know!

newTheme(name, textc, backgroundc)
creates a new theme with name "name" textcolor "textc" and backgroundcolor "backgroundc"

setTheme(name)
sets the background- and textcolor of theme with name "name"

ardera, on 26 January 2015 - 03:17 PM said:

newTheme(name, textc, backgroundc)
creates a new theme with name "name" textcolor "textc" and backgroundcolor "backgroundc"

setTheme(name)
sets the background- and textcolor of theme with name "name"

Would said themes be saved as a file? I like this idea. :)/>

edit: added!

Display APIs should also handle some more advanced graphics features. Here is a little list of what I would add in that is relatively easy to do.

• drawBox( x, y, w, h, bc, tc, char )
• drawFilledBox( x, y, w, h, bc, tc, char )
• drawLine( x, y, x2, y2, bc, tc, char )
• drawCircle( x, y, r, bc, tc, char )
• drawFilledCircle( x, y, r, bc, tc, char )
• drawImage( image, x, y )
• drawImageFromFile( path, x, y )
• drawWrappedText( x, y, w, h, bc, tc, text [, alignment] ) – alignment can be like "top, left" "bottom, right" or "centre, centre" for example

If you add more to this, it could be quite useful.

Talk about reinventing the wheel…

drawTriangle(x, y, z) – X is bottom-left, y is bottom-right, z is top point. GL and GG.

Yeah, that's not the easiest thing to do, otherwise it would've been on my list. If you're going to add a drawTriangle() function, don't bother, just make a drawPolygon() function as they both use the same method for rendering, and being able to draw polygons is a vast improvement over just triangles.

If you need any help with any of them, I've written my own (probably inefficient) versions, including a drawPolygon() and drawFilledPolygon().

In an "OS" (I use the quotes because it's the derpiest piece of software ever) I'm making I've turned term.setCursorPos into cursor(x,y).

I also have a different function for every color, such as:

lightBlue() – Sets the text color to light blue
red() – Same thing but for red

bgLightBlue() – Sets the background color to light blue
bgRed() – You get the picture now?

As you can see, I'm very lazy.

awsumben13, on 26 January 2015 - 06:21 PM said:

Display APIs should also handle some more advanced graphics features. Here is a little list of what I would add in that is relatively easy to do.

• drawBox( x, y, w, h, bc, tc, char )
• drawFilledBox( x, y, w, h, bc, tc, char )
• drawLine( x, y, x2, y2, bc, tc, char )
• drawCircle( x, y, r, bc, tc, char )
• drawFilledCircle( x, y, r, bc, tc, char )
• drawImage( image, x, y )
• drawImageFromFile( path, x, y )
• drawWrappedText( x, y, w, h, bc, tc, text [, alignment] ) – alignment can be like "top, left" "bottom, right" or "centre, centre" for example

If you add more to this, it could be quite useful.

Thank you for the suggestions! I really like the input
I do have "drawImage" actually implemented already, I neglected to add it to the list.
Same with DrawLine. I have it actually drawing "-" across the screen on the Y axis you choose. I most likely will upgrade it to the way you said.

From this list, I will most likely take

• drawBox()
• drawFilledBox()
• drawImageFromFile()
• drawWrappedText() –if I can

Circles are too advanced for my knowledge right now, but I'm sure they'll find their way into it. :)/>
Thanks so much, again!

I can help with the math of circles, and if you have drawImage() you may as well add drawImageFromFile() as it's effectively the same thing.

For drawing a filled circle, you want to check each point within the area you're drawing to is within the radius of the circle.
You loop from x-r to x+r for the x coordinate, and y-r to y+r for the y coordinate, then check if math.sqrt( (ix-x)^2 + (iy-y)^2 ) is smaller than (or equal to, depending on your implementation) the radius of the circle. You can also optimise this and take out the sqrt by using r^2 (this can be done once outside the loop, making it a lot quicker).

For drawing an outline of a circle, you want to go around the circumference of the circle (pi * diameter), then use trigonometry to calculate the x and y values for the point. You can also optimise this by going round 1/8 of the circumference, because if you mirror a 45 degree segment of a circle on the line y=x, then mirror those 2 segments on the line y=0, then mirror those 4 segments on the line x=0, you get a full circle. This can be done in code by switching the x and y values and using all combinations of the positive and negative versions of x and y.

So, I was going to add my own box function, but I guess it already exists. Ill adapt it for my API, but it's already there.

I don't really know what I should suggest because most of the important stuff have already been suggested.
Maybe this?

setColor( "white" )
setColour( "black" )
setBackgroundColor( "black" )
setBackgroundColour( "white" )

You can access the colors by doing something like this

local name = "white"
term.setTextColor( colors[name] )

Oh, and another thing you could add, a function that would center text between two points

midpoint( text, x1, x2, y )

You can have a look at my draw API i have on my pastebin if that's any help.
Draw API

Thanks for the suggestions, OddByte. The color thing will definitely be added. :)/>

bumping, as I am doing more work on this and would like some more ideas.

drawProgressBar(size, y, bgColor, fgColor, fillUpRate)
Draws a progress bar with given size on given y position with bgColor as background color and fgColor as fill-up color. Fills up on fillUpRate percents per second.

drawDialog(minX1, maxX1, minX2, maxX2, yPos, keyYes, keyNo, txtYes, txtNo)
Draws a dialog box with 2 buttons on given y position, one of them with text as txtYes, left x position as minX1 and right x position as maxX. Same for second button, only with txtNo, minX2 and maxX2. Instead of clicking on a button, you can press keyYes to "click left button" or keyNo to"click right button".