akfavatar-graphic(3)                                      akfavatar-graphic(3)



NNAAMMEE
       akfavatar-graphic - module to display graphics in Lua-AKFAvatar

SSYYNNOOPPSSIISS
       local graphic = require "akfavatar-graphic"

DDEESSCCRRIIPPTTIIOONN
       Module for Lua-AKFAvatar to display graphics.

       NNootteess:

       – Coordinates start with 1, 1 in the upper left corner.

       – It can also be used in the style of turtle graphic.

       – The  pen  size, position, heading, pen color and background color are
         set for each graphic.

       – The code is not optimized for speed.  You can do animations, but they
         won't be smooth.

   FFuunnccttiioonnss // MMeetthhooddss
       ggrraapphhiicc..nneeww((_[_w_i_d_t_h_, _h_e_i_g_h_t_] _[_, _b_a_c_k_g_r_o_u_n_d_-_c_o_l_o_r_]))
              Creates a new graphic (a canvas).

              When  _w_i_d_t_h  and  _h_e_i_g_h_t  are  not  given it uses the whole win‐
              dow/screen.
              A thin black pen is chosen and the position is centered, heading
              to the top.
              If  the _b_a_c_k_g_r_o_u_n_d_-_c_o_l_o_r is not given, it is imported from AKFA‐
              vatar.

              Retuns the graphic, the width and the height (ie. three values).

              Use it like this:
              local gr, width, height = graphic.new()

       ggrraapphhiicc..ffuullllssiizzee(())
              Returns the width and height for a graphic so that it fills  the
              whole window.

       ggrraapphhiicc..sseett__rreessiizzee__kkeeyy((_k_e_y))
              Sets  a  key-code  (as number) which should be returned when the
              window gets resized.  Returns the previous key-code.

              HHiinntt:: Use something between 0xE000 and 0xE9FF to avoid conflict‐
              ing with real key-codes.

       ggrraapphhiicc..sseett__ppooiinntteerr__bbuuttttoonnss__kkeeyy((_k_e_y))
              Sets  a  key-code  (as number) which should be returned when any
              mouse button is pressed.  Returns the previous key-code.

              HHiinntt:: Use something between 0xE000 and 0xE9FF to avoid conflict‐
              ing with real key-codes.

       ggrraapphhiicc..sseett__ppooiinntteerr__mmoottiioonn__kkeeyy((_k_e_y))
              Sets  a  key-code  (as number) which should be returned when the
              mouse is moved.  Returns the previous key-code.

       ggrraapphhiicc..ggeett__ppooiinntteerr__ppoossiittiioonn(())
              Returns the x and y coordinates of the current  mouse  position,
              relative to the last shown graphic.

       _g_r::sshhooww(())
              Shows the graphic as image after drawing.

              HHiinntt: You can show intermediate images, continue drawing, wait a
              while and then show the next step and so on.  This makes a  nice
              animation.   But  don't  make the steps too small, or it will be
              painful on slow devices.

       _g_r::ssiizzee(())
              Returns the width and the height of the graphic _g_r.

       _g_r::wwiiddtthh(())
              Returns the width of the graphic _g_r.

       _g_r::hheeiigghhtt(())
              Returns the height of the graphic _g_r.

       _g_r::ccoolloorr((_c_o_l_o_r))
              Sets the drawing _c_o_l_o_r.
              The color can be either a defined color name, or  a  hexadecimal
              representation, like for example _0_x_F_F_F_F_0_0 or _"_#_F_F_F_F_0_0_".

       _g_r::rrggbb((_r_e_d_, _g_r_e_e_n_, _b_l_u_e))
              Sets the drawing color from RGB values.
              The values must be in the range from 0 to 255 inclusive.
              This method is faster than using ggrr::ccoolloorr(()).

       _g_r::eerraasseerr(())
              Sets the drawing color to the background color.

       _g_r::tthhiicckknneessss((_v_a_l_u_e))
              Sets the thickness of the pen.
              The _v_a_l_u_e 1 is the thinnest.

       _g_r::cclleeaarr((_[_c_o_l_o_r_]))
              Clears the graphic.
              If a _c_o_l_o_r is given, then that becomes the new background color.
              The pen position is not changed.

       _g_r::bboorrddeerr33dd((_[_p_r_e_s_s_e_d_]))
              Draws  3d  border around the graphic.  The color is based on the
              background color.  The setting for thickness is ignored,  it  is
              always the 3 pixels.

              if _p_r_e_s_s_e_d is ttrruuee the border is presented as being pressed.

              The pen position is not changed.

       _g_r::ppuuttppiixxeell((_[_x_, _y_]))
              Puts  a  pixel  at  the  given coordinates or at the current pen
              position.
              The pen position is not changed.

       _g_r::ggeettppiixxeell((_[_x_, _y_]))
              Gets the pixel color at the given coordinates or at the  current
              pen position.
              The color is returned as string in the hexadecimal RGB notation.
              On error it returns _n_i_l and an error message.
              The pen position is not changed.

       _g_r::ggeettppiixxeellrrggbb((_[_x_, _y_]))
              Gets  the pixel color at the given coordinates or at the current
              pen position.
              Returns three integers for red, green and blue, in the range  of
              0-255.
              On error it returns _n_i_l and an error message.
              The pen position is not changed.

       _g_r::ppuuttddoott((_[_x_, _y_]))
              Puts  a dot at the given coordinates or at the current pen posi‐
              tion.
              If the pen is thin, it's the same as ggrr::ppuuttppiixxeell.
              The pen position is not changed.

       _g_r::ppeenn__ppoossiittiioonn(())
              Returns the x and y position of the pen (ie.  returns  two  val‐
              ues).

       _g_r::cceenntteerr(())
       _g_r::hhoommee(())
              Sets the pen to the center of the graphic, heading to the top.

       _g_r::mmoovveettoo((_x_, _y))
              Move the pen to _x_, _y without drawing.

       _g_r::mmoovveerreell((_x_, _y))
              Move the pen without drawing relative to its current position.
              A positive _x value moves it to the right,
              a negative _x value moves it to the left.
              A positive _y value moves it down,
              a negative _y value moves it up.

       _g_r::lliinneettoo((_x_, _y))
              Draws  a  line  from  the current pen position to these absolute
              coordinates.
              The pen is moved to the new coordinates.

       _g_r::lliinneerreell((_x_, _y))
              Draws a line relative to its current pen position.
              A positive _x value draws to the right,
              a negative _x value draws to the left.
              A positive _y value draws down,
              a negative _y value draws up.
              The pen is moved to the new position.

       _g_r::lliinnee((_x_1_, _y_1_, _x_2_, _y_2))
              Draws a line from _x_1_, _y_1 to _x_2_, _y_2.
              The pen is set to _x_2_, _y_2.

       _g_r::bbaarr((_x_1_, _y_1_, _x_2_, _y_2))
              Draws a solid bar with _x_1_, _y_1 as the upper left corner  and  _x_2_,
              _y_2 as the lower right corner.
              The pen position is not changed.

       _g_r::rreeccttaannggllee((_x_1_, _y_1_, _x_2_, _y_2))
              Draws  rectangle with _x_1_, _y_1 as the upper left corner and _x_2_, _y_2
              as the lower right corner.
              The pen position is not changed.

       _g_r::aarrcc((_r_a_d_i_u_s _[_, _a_n_g_l_e_1_] _[_, _a_n_g_l_e_2_]))
       _g_r::cciirrccllee((_r_a_d_i_u_s _[_, _a_n_g_l_e_1_] _[_, _a_n_g_l_e_2_]))
              Draws a circle or an arc with the given _r_a_d_i_u_s.
              The pen position is the center.

              You can draw a part of the circle (an arc) by giving one or  two
              angles in degree.  If two angles are given, then it draws clock‐
              wise from the first angle to the second.  If just one  angle  is
              given,  it uses the heading as start-angle (see below under ttuurr‐‐
              ttllee ggrraapphhiiccss).

       _g_r::ddiisscc((_r_a_d_i_u_s _[_, _x_, _y_]))
              Draws a disc, ie. a filled circle with the given _r_a_d_i_u_s with the
              given  coordinates  as center.  If no coordinates are given, the
              current pen position is used as center.
              The pen position is not changed.

       _g_r::tteexxtt((_t_e_x_t _[_, _x_, _y_]))
              Prints a text aligned to the given position or the pen position.

              By default the text is centered to the position.   But  you  can
              change this with ggrr::tteexxttaalliiggnn(()).

              The  encoding  is  used from the AKFAvatar settings.  However no
              other of those settings are taken into account.   The  color  is
              the  drawing  color for the graphic.  There is currently no easy
              way to make boldface, underlined or inverted text.

              You can use all printable characters, but control characters are
              not supported, not even a newline.
              The pen position is not changed.

       _g_r::tteexxttaalliiggnn((_[_h_o_r_i_z_o_n_t_a_l_] _[_, _v_e_r_t_i_c_a_l_]))
              Sets the textalignment for ggrr::tteexxtt(()).

              The  horizontal  alignment  can  be  one  of "left", "center" or
              "right".  The default is "center".

              The vertical alignment can be one of "top",  "center"  or  "bot‐
              tom".  The default is "center".

              The alignment means, where the given point is, eg. when you tell
              it to be "left"-aligned, the fixed point is on the left, but the
              text runs to the right.

       ggrraapphhiicc..ffoonntt__ssiizzee(())
       _g_r::ffoonntt__ssiizzee(())
              Returns  the width, height and the baseline of the font, ie. one
              character.  It is a fixed-width font,  each  character  has  the
              same width.

       _g_r::ppuutt((_g_r_a_p_h_i_c _[_, _x_, _y_]))
              Puts a graphic onto graphic _g_r at the given position (upper-left
              corner).  If no position is given it puts it at  the  upper-left
              corner.   The  previous  content is overwritten (no transparency
              supported).

              Copying a graphic with the same size and no position  is  highly
              efficient.   The  same is true for a graphic with the same width
              and _x set to 1.

       _g_r::ppuutt__ttrraannssppaarreennccyy((_g_r_a_p_h_i_c _[_, _x_, _y_]))
              Puts a graphic onto graphic _g_r at the given position (upper-left
              corner).
              If no position is given it puts it at the upper-left corner.
              Pixels with the background color are not copied, they are trans‐
              parent.
              This is much slower than ggrr::ppuutt(()).

       _g_r::ppuutt__ffiillee((_f_i_l_e_n_a_m_e _[_, _x_, _y_]))
              Puts a graphic from a file onto graphic _g_r at the given position
              (upper-left corner).
              If no position is given it puts it at the upper-left corner.

       _g_r::ppuutt__iimmaaggee((_d_a_t_a _[_, _x_, _y_]))
              Puts  a  graphic from _d_a_t_a onto graphic _g_r at the given position
              (upper-left corner).  The _d_a_t_a can be a string  with  image-data
              or a table with strings from XPM data.
              If no position is given it puts it at the upper-left corner.

       _g_r::ggeett((_x_1_, _y_1_, _x_2_, _y_2))
              Returns an area of the graphic _g_r as a new graphic.
              Most settings are copied, except the size and the pen settings.
              The pen is put in the center, heading to the top.
              All values must be in range.

       _g_r::dduupplliiccaattee(())
              Returns an exact duplicate (a copy) of the graphic _g_r.
              The graphic-specific settings are copied, too.
              This is faster than using ggrr::ggeett(()).

              You  can  use  this for example to create a fixed background and
              then make a duplicate and draw the foreground on it.   Then  you
              can  ggrr::ppuutt(())  the  background graphic back to the duplicate and
              draw another foreground.

       _g_r::sshhiifftt__vveerrttiiccaallllyy((_l_i_n_e_s))
              Shifts the graphic vertically.
              A positive value for _l_i_n_e_s shifts it down.
              A negative value for _l_i_n_e_s shifts it up.
              The pen gets also moved.

       _g_r::sshhiifftt__hhoorriizzoonnttaallllyy((_c_o_l_u_m_n_s))
              Shifts the graphic horizontally.
              A positive value for _c_o_l_u_m_n_s shifts it right.
              A negative value for _c_o_l_u_m_n_s shifts it left.
              The pen gets also moved.

       _g_r::eexxppoorrtt__ppppmm((_f_i_l_e_n_a_m_e))
              Exports the graphic as Portable Pixmap (PPM) file.

              The PPM format is simple to implement, but not  very  efficient.
              You  might  want  to  use the "netpbm" tools or "ImageMagick" to
              convert it to another format.

              The following example shows how to do this:

              function export(graphic, name)
                graphic:export_ppm(name..".ppm")
                if os.execute("pnmtopng "..name..".ppm > "..name..".png")
                   or os.execute("convert "..name..".ppm "..name..".png") then
                  os.remove(name..".ppm")
                end
              end

              First it exports the graphic in the PPM format.  Then  it  tries
              to  convert  it to the PNG format.  If that succeeds, it deletes
              the PPM file.  If the user doesn't have "netpbm"  or  "ImageMag‐
              ick" installed, he still ends up with the PPM file.

   TTuurrttllee ggrraapphhiiccss
       To  understand  turtle  graphics  think of a turtle that carries a pen.
       You can control the turtle by telling her in which  direction  to  turn
       and how far to move.

       _g_r::hheeaaddiinngg((_h_e_a_d_i_n_g))
              Sets  the  heading  for  the turtle.  The value must be given in
              degree and the turtle turns clockwise.  The value 0 means,  it's
              heading to the top, 90 means it heads to the right.

       _g_r::ggeett__hheeaaddiinngg(())
              Returns the heading of the turtle (see ggrr::hheeaaddiinngg(())).

       _g_r::rriigghhtt((_a_n_g_l_e))
              Turn the turtle clockwise by the specified _a_n_g_l_e in degree.

       _g_r::lleefftt((_a_n_g_l_e))
              Turn  the  turtle  counterclockwise  by  the  specified _a_n_g_l_e in
              degree.

       _g_r::ddrraaww((_s_t_e_p_s))
              Draw a line in the direction the turtle is heading.

       _g_r::mmoovvee((_s_t_e_p_s))
              Move the turtle in the direction it is heading without drawing.

       _g_r::hhoommee(())
              Sets the pen to the center of the graphic, heading to the top.

SSEEEE AALLSSOO
       lluuaa--aakkffaavvaattaarr(1) lluuaa(1)  lluuaa--aakkffaavvaattaarr--rreeff(3)  aakkffaavvaattaarr--tteerrmm(3)  aakkffaa‐‐
       vvaattaarr..uuttff88(3)



AKFAvatar                         2013-08-09              akfavatar-graphic(3)
