Lua-AKFAvatar reference(3)                          Lua-AKFAvatar reference(3)



NNAAMMEE
       Lua-AKFAvatar reference - AKFAvatar specific functions for Lua

DDEESSCCRRIIPPTTIIOONN
       This  is  a  reference  for the Lua-bindings to AKFAvatar.  It does not
       describe the language Lua.  The reference manual for the  language  Lua
       can be found on the Internet on hhttttpp::////wwwwww..lluuaa..oorrgg//mmaannuuaall//55..22//.

       Don't  worry,  you  don't  need to understand or even learn everything.
       You can do lots of things with very few commands.  Just pick the  parts
       you  are  interested in and experiment with that.  There are many parts
       of Lua or AKFAvatar which you will most probably never need.

   FFiillee ffoorrmmaattss
       For images the formats XXPPMM, XXBBMM and uncompressed BBMMPP  are  always  sup‐
       ported.   More  formats  may  be  supported  if  SSDDLL__iimmaaggee  and further
       libraries are installed.

       For audio the formats AAUU and WWAAVV are supported.  Files may  be  encoded
       as  PCM,  μ-law  or A-law.  There is also a Lua module named aakkffaavvaattaarr--
       vvoorrbbiiss, which adds support for Ogg Vorbis audio files.

   BBaassiicc ffuunnccttiioonnaalliittyy
       llooccaall aavvtt == rreeqquuiirree ""lluuaa--aakkffaavvaattaarr""
              Before you can use the AKFAvatar binding, you have  to  load  it
              with  this  function.   This gives you the table _a_v_t, with which
              you can access the following functions.

       aavvtt..eennccooddiinngg((_e_n_c_o_d_i_n_g))
              Set the used text encoding.  If this function is not used,  only
              "ASCII" is supported.

              Supported encodings are:
              ASCII, UTF-8,
              ISO-8859-1, -2, -3, -4, -5, -7, -8, -9, -10, -11, -13, -14, -15,
              -16,
              KOI8-R, KOI8-U,
              IBM437 (PC-8), IBM850 (DOS-Latin-1),
              WINDOWS-1250, WINDOWS-1251, WINDOWS-1252
              SYSTEM

       aavvtt..ggeett__eennccooddiinngg(())
              Gets the current text encoding.

       aavvtt..ttiittllee((_t_i_t_l_e _[_,_s_h_o_r_t_n_a_m_e_]))
       aavvtt..sseett__ttiittllee((_t_i_t_l_e _[_,_s_h_o_r_t_n_a_m_e_]))
              Sets the title and the shortname.

       aavvtt..ssttaarrtt((_[_m_o_d_e_]))
              This function opens the graphical window or  switches  into  the
              graphical  mode.   If  it  was  already started it resets almost
              everything.

              _m_o_d_e Is one of "auto", "window", "fullscreen", or "fullscreen no
              switch".   The  default is "auto" which uses a sensible default,
              or leaves the mode unchanged, if it already was started.

              If you want to set the encoding, the title  and  the  background
              color,  you should do it before you call aavvtt..ssttaarrtt(()).  All other
              functions should be used after it.

              EExxaammppllee::
              local avt = require "lua-akfavatar"
              avt.encoding("ISO-8859-1")
              avt.title("my program")
              avt.set_background_color("sky blue")
              avt.start()
              avt.start_audio()
              avt.avatar_image("default")
              avt.tell("hello world")
              avt.wait_button()

              Many of the following functions implicitly call aavvtt..ssttaarrtt(()) when
              it is not started yet.

       aavvtt..ssttaarrtteedd(())
              Returns  _t_r_u_e  if  AKFAvatar  it  is started, or else it returns
              _f_a_l_s_e.

       aavvtt..aavvaattaarr__iimmaaggee((_d_a_t_a))
              Loads the avatar image from the _d_a_t_a.  The _d_a_t_a can be "default"
              or  "none"  or  a string with image-data or a table with strings
              from XPM data.  On error it returns _n_i_l and an error message.

       aavvtt..aavvaattaarr__iimmaaggee__ffiillee((_f_i_l_e_n_a_m_e))
              Loads the avatar image from a file.  The  strings  "default"  or
              "none"  are also accepted.  On error it returns _n_i_l and an error
              message.

       aavvtt..sseett__aavvaattaarr__nnaammee((_[_n_a_m_e_]))
              Set  the  name  of  the  avatar.   This  must  be   used   after
              aavvtt..cchhaannggee__aavvaattaarr__iimmaaggee(()).

       aavvtt..sseett__aavvaattaarr__mmooddee((_m_o_d_e))
              Set  the  avatar  mode.   The _m_o_d_e can be one of "say", "think",
              "header" or "footer".  The avatar mode is only used, when  there
              is an avatar image.

       aavvtt..ssaayy((_._._.))
       aavvtt..wwrriittee((_._._.))
              Prints text in the balloon.

              You  can use strings or numbers. It works similar to iioo..wwrriittee(()),
              but it writes into the balloon instead of the standard output.

              EExxaammppllee::
              avt.say("Three apples cost ", 3 * appleprice, " Euros.\n").

       aavvtt..pprriinntt((_._._.))
              Prints text in the balloon.  It works similar to pprriinntt,  but  it
              writes into the balloon instead of the standard output.

              The difference to aavvtt..ssaayy(()) is, that the values are separated by
              tabulators in the output and each value  is  automatically  con‐
              verted with ttoossttrriinngg(()) and at the end a new line is started.

              You  can  simply  replace  the  print command with this one with
              pprriinntt  ==  aavvtt..pprriinntt.   (The  script  `interactive_lua.lua'  does
              this.)

              The function aavvtt..ssaayy(()) is better suited for programs, while this
              function is better suited for interactive use or debugging.

       aavvtt..tteellll((_._._.))
              Prints text in the balloon, but before that the size of the bal‐
              loon is adjusted so that the text exactly fits.

              EExxaammppllee::
              avt.tell("Three apples cost ", 3 * appleprice, " Euros.").

              AAtttteennttiioonn:: This function still has problems with tabs ("\t").

       aavvtt..nneewwlliinnee(())
              Start  a  new  line.  It  is  the same as "\n" in aavvtt..ssaayy(()), but
              faster.

       aavvtt..sseett__tteexxtt__ddeellaayy((_[_d_e_l_a_y_]))
              Activate the slow-print mode. With no value for _d_e_l_a_y it uses  a
              default delay.  To deactivate the slow-print mode, use the value
              0 for _d_e_l_a_y.

       aavvtt..cclleeaarr(())
              Clears the textfield or viewport.  If there is no balloon
              yet, it is drawn.

       aavvtt..fflliipp__ppaaggee(())
              Waits a while and then clears the textfield; same as "\f"
              in aavvtt..ssaayy(()).  See also aavvtt..sseett__fflliipp__ddeellaayy((ddeellaayy)).

       aavvtt..mmoovvee__iinn(())
              Moves the avatar in.

       aavvtt..mmoovvee__oouutt(())
              Moves the avatar out.

       aavvtt..ppaaggeerr((_t_e_x_t _[_,_s_t_a_r_t_l_i_n_e_]))
              Show a longer text with a text-viewer application.

              If the _s_t_a_r_t_l_i_n_e is given and it is greater than 1,  then
              it  starts  in  that line.  But you still can scroll back
              from there.

       aavvtt..wwaaiitt((_[_s_e_c_o_n_d_s_]))
              Waits a given amount of seconds (may be a fraction).

              If no value is given, it waits "a while".

       aavvtt..ttiicckkss(())
              Returns a value, which  is  increased  each  millisecond.
              This can be used for timing.

       aavvtt..sshhooww__aavvaattaarr(())
              Shows only the avatar without any balloon.

       aavvtt..bbeellll(())
              Makes  a  sound  or  flashes  the display if audio is not
              started.

       aavvtt..ffllaasshh(())
              Flashes the display.

       aavvtt..sshhooww__iimmaaggee((_d_a_t_a))
              Shows an image.  The _d_a_t_a can be a string with image-data
              or  a  table with strings from XPM data.  It returns _t_r_u_e
              on success, or _f_a_l_s_e on error.  If it succeeds you should
              call aavvtt..wwaaiitt(()) or aavvtt..wwaaiitt__bbuuttttoonn(()) or aavvtt..ggeett__kkeeyy(()).

       aavvtt..sshhooww__iimmaaggee__ffiillee((_f_i_l_e_n_a_m_e))
              Load  an  image and show it.  It returns _t_r_u_e on success,
              or _f_a_l_s_e on error.  You can  search  for  the  file  with
              _a_v_t_._s_e_a_r_c_h_(_).   If it succeeds you should call aavvtt..wwaaiitt(())
              or aavvtt..wwaaiitt__bbuuttttoonn(()) or aavvtt..ggeett__kkeeyy(()).

       aavvtt..ssuubbpprrooggrraamm((_f_u_n_c_t_i_o_n_, _[_a_r_g_1_, _._._._]))
              Call the function as a subprogram.

              On a quit-request (pressing the <ESC>-key  or  the  close
              button  of  the  window) it just returns to the main pro‐
              gram.

              On success it returns the results of the function,  on  a
              quit-request it returns nothing.  Errors are treated nor‐
              mally.

              To call a subprogram from a separate file, use ddooffiillee:
              avt.subprogram(dofile, "subprogram.lua")

       aavvtt..ooppttiioonnaall((_m_o_d_n_a_m_e))
              Loads a module  like  rreeqquuiirree,  but  the  module  is  not
              required,  but optional.  That means, it is not an error,
              when it cannot be loaded.

              Lua-AKFAvatar need not be initialized to use  this  func‐
              tion.

   UUnniiccooddee
       aavvtt..ssaayy__uunniiccooddee((_._._.))
              Prints  text in the balloon with special support for Uni‐
              code characters.

              This command is very similar to aavvtt..ssaayy(()).   Strings  are
              handled in the same way, depending on the selected encod‐
              ing, but numbers are interpreted as  Unicode  codepoints,
              independent from the selected encoding.

              This  can  be  used  to  insert characters, which are not
              available in the current string encoding.   Sometimes  it
              is also just easier to use.

              EExxaammppllee::
              avt.say_unicode("Three apples cost ",
                              tostring(3 * appleprice), 0x20AC,
                              ".\n").

              As  you can see, you have to use ttoossttrriinngg(()) when nummeri‐
              cal expressions are to be shown as numbers.   The  number
              _0_x_2_0_A_C  however  represents the Euro currency sign.  (The
              `0x' introduces hexadecimal numbers.)

              By the way, a bunch of unicode numbers are  handled  much
              more efficiently than strings.

       aavvtt..pprriinnttaabbllee((_c_o_d_e_p_o_i_n_t))
              Checks whether the given _c_o_d_e_p_o_i_n_t represents a printable
              Unicode character.  It returns _t_r_u_e when this is the case
              or  _f_a_l_s_e  if the font doesn't have a printable glyph for
              it (it may be a supported control character).  This func‐
              tion  is independent from the chosen encoding.  It can be
              used together with aavvtt..ssaayy__uunniiccooddee((......)).

       aavvtt..ccoommbbiinniinngg((_c_o_d_e_p_o_i_n_t))
              Checks whether the given _c_o_d_e_p_o_i_n_t represents a combining
              Unicode  character  and  is  treated as such.  It returns
              _t_r_u_e when this is the case or _f_a_l_s_e if not.  It  is  only
              really applicable for supported characters.

       aavvtt..ddeetteecctt__uuttff88((_s_t_r_i_n_g _[_, _m_a_x_l_e_n_g_t_h_]))
              Detect if _s_t_r_i_n_g is valid UTF-8 (or ASCII).

              Checks up to _m_a_x_l_e_n_g_t_h bytes, but it finishes to check an
              incomplete sequence.

       aavvtt..ttoouuttff88((_c_o_d_e_p_o_i_n_t _[_, _._._._]))
              Takes one or more Unicode _c_o_d_e_p_o_i_n_t_s and returns an UTF-8
              encoded string for that.

       aavvtt..uuttff88ccooddeeppooiinnttss((_s_t_r))
              This  can  be  used to get all Unicode codepoints from an
              UTF-8 encoded string as numbers.

              Example:
                for c in avt.utf8codepoints(s) do
                  avt.say_unicode(c)
                  avt.say(string.format(" = U+%04X", c))
                  avt.newline()
                end

   SSiizzeess aanndd ppoossiittiioonnss
       aavvtt..sseett__bbaalllloooonn__ssiizzee((_[_h_e_i_g_h_t_] _[_, _w_i_d_t_h_]))
              Sets the size of the balloon. No values or  values  of  0
              set the maximum size.

       aavvtt..sseett__bbaalllloooonn__wwiiddtthh((_[_w_i_d_t_h_]))
              Sets  the  width  of  the balloon. No value or 0 sets the
              maximum.

       aavvtt..sseett__bbaalllloooonn__hheeiigghhtt((_[_h_e_i_g_h_t_]))
              Sets the height of the balloon. No value or  0  sets  the
              maximum.

       aavvtt..ggeett__mmaaxx__xx(())
              Get  the  maximum x position of the cursor in the balloon
              (ie. the width).

       aavvtt..ggeett__mmaaxx__yy(())
              Get the maximum y position of the cursor in  the  balloon
              (ie. the height).

       aavvtt..wwhheerree__xx(())
              Get the x position of the cursor in the balloon.

       aavvtt..wwhheerree__yy(())
              Get the y position of the cursor in the balloon.

       aavvtt..hhoommee__ppoossiittiioonn(())
              Returns  _t_r_u_e  if  the  cursor is in the home position or
              _f_a_l_s_e otherwise.   (This  also  works  for  right-to-left
              writing.)

       aavvtt..mmoovvee__xx((_x))
              Moves the cursor to the given _x position.

       aavvtt..mmoovvee__yy((_y))
              Moves the cursor to the given _y position.

       aavvtt..mmoovvee__xxyy((_x_, _y))
              Moves the cursor to the given _x and _y position.

       aavvtt..ssaavvee__ppoossiittiioonn(())
              Save the current cursor position.

       aavvtt..rreessttoorree__ppoossiittiioonn(())
              Restore the last saved cursor position.

       aavvtt..nneexxtt__ttaabb(())
              Moves the cursor to the next tabulator position.

       aavvtt..llaasstt__ttaabb(())
              Moves the cursor to the previous tabulator position.

       aavvtt..rreesseett__ttaabb__ssttooppss(())
              Reset tab stops to every eigth column.

       aavvtt..cclleeaarr__ttaabb__ssttooppss(())
              Clears all tab stops.

       aavvtt..sseett__ttaabb((_x_, _t_r_u_e||_f_a_l_s_e))
              Set or clear tab in position _x.

       aavvtt..ddeelleettee__lliinneess((_l_i_n_e_, _n_u_m_b_e_r))
              Deletes  given  _n_u_m_b_e_r  of lines, starting from _l_i_n_e; the
              rest is scrolled up.

       aavvtt..iinnsseerrtt__lliinneess((_l_i_n_e_, _n_u_m_b_e_r))
              Inserts given _n_u_m_b_e_r of lines, starting at _l_i_n_e; the rest
              is scrolled down.

       aavvtt..iinnsseerrtt__ssppaacceess((_n_u_m_b_e_r))
              Insert _n_u_m_b_e_r spaces at the current cursor position.  The
              rest of the line is moved.

       aavvtt..ddeelleettee__cchhaarraacctteerrss((_n_u_m_b_e_r))
              Delete _n_u_m_b_e_r characters at the current cursor  position.
              The rest of the line is moved.

       aavvtt..eerraassee__cchhaarraacctteerrss((_n_u_m_b_e_r))
              Erase _n_u_m_b_e_r of characters.  The characters are overwrit‐
              ten with spaces.

       aavvtt..bbaacckkssppaaccee(())
              Go back one character.  Does nothing if the cursor is  at
              the beginning of the line.

   TTeexxtt ssttyyllee
       aavvtt..mmaarrkkuupp((_t_r_u_e||_f_a_l_s_e))
              Set the markup mode. In the markup mode the character "_"
              toggles the underlined mode on or off and  the  character
              "*" toggles the bold mode on or off.  Both characters are
              never displayed in markup mode!

              You  can  always  use  the  overstrike  technique,  which
              doesn't reserve any characters, but is harder to use.

       aavvtt..uunnddeerrlliinneedd((_t_r_u_e||_f_a_l_s_e))
              Set the underlined mode.

       aavvtt..ggeett__uunnddeerrlliinneedd(())
              Returns  _t_r_u_e  if  the underlined mode is active or _f_a_l_s_e
              otherwise.

       aavvtt..bboolldd((_t_r_u_e||_f_a_l_s_e))
              Set the bold mode.

       aavvtt..ggeett__bboolldd(())
              Returns _t_r_u_e if the bold mode is active or  _f_a_l_s_e  other‐
              wise.

       aavvtt..iinnvveerrssee((_t_r_u_e||_f_a_l_s_e))
              Set the inverse mode.

       aavvtt..ggeett__iinnvveerrssee(())
              Returns  _t_r_u_e if the inverse mode is active or _f_a_l_s_e oth‐
              erwise.

       aavvtt..nnoorrmmaall__tteexxtt(())
              Resets the text to normal settings.

   CCoolloorrss
       aavvtt..sseett__bbaacckkggrroouunndd__ccoolloorr((_c_o_l_o_r))
              Sets the background color of the window.

              Colors can either be given as English  names  or  as  RGB
              value with 6 hexadicimal digits.

              EExxaammpplleess
              avt.set_background_color("sky blue")
              avt.set_background_color(0x8B4513)
              avt.set_background_color("#8B4513") --> deprecated
              avt.set_background_color("#555") --> deprecated

       aavvtt..sseett__bbaalllloooonn__ccoolloorr((_c_o_l_o_r))
              Sets the color of the balloon.

       aavvtt..sseett__tteexxtt__ccoolloorr((_c_o_l_o_r))
              Sets the text color.

       aavvtt..sseett__tteexxtt__bbaacckkggrroouunndd__ccoolloorr((_c_o_l_o_r))
              Sets the text background color.

       aavvtt..sseett__tteexxtt__bbaacckkggrroouunndd__bbaalllloooonnccoolloorr(())
              Sets  the  text background color to the color of the bal‐
              loon.

       aavvtt..sseett__bbiittmmaapp__ccoolloorr((_c_o_l_o_r))
              Sets the foregroud color for bitmaps.  The background  is
              always transparent.

       aavvtt..ggeett__ccoolloorr((_c_o_l_o_r___n_u_m_b_e_r))
              Get a color for a given integer value.

              AKFAvatar  has  an  internal  palette with color names to
              use.  With this function you can scan through that  list.
              It  returns  the  name  and  RGB  value as strings, or it
              returns nothing on error.

       aavvtt..ccoolloorrss(())
              Iterator for internal color names.

              AKFAvatar has an internal palette  with  color  names  to
              use.   With  this function you can scan through that list
              with a generic ffoorr loop.

              require "lua-akfavatar"
              for nr, name, rgb in avt.colors() do
                avt.normal_text()
                avt.newline()
                avt.say(string.format("%3d) %5s, %-25s", nr, rgb, name))
                avt.set_text_background_color(name) -- either name or rgb
                avt.clear_eol()
                avt.wait(0.7)
              end
              avt.wait_button()

              If you don't need the _r_g_b value, you can leave that vari‐
              able away.

   IInntteerraaccttiioonn
       aavvtt..wwaaiitt__bbuuttttoonn(())
              Waits until a button is pressed.

       aavvtt..ddeecciiddee(())
              Ask  the  user  to  make a positive or negative decision.
              Returns _t_r_u_e or _f_a_l_s_e.

       aavvtt..aasskk((_[_q_u_e_s_t_i_o_n_]))
              Shows the _q_u_e_s_t_i_o_n, if given, and waits for the  user  to
              enter something.  Returns the result as string.

              The  following  example shows how to force the input of a
              number:

              require "lua-akfavatar"
              avt.save_position()
              repeat
                avt.restore_position()
                number = tonumber(avt.ask("Enter a number: "))
              until number
              avt.say("The number is ", number)
              avt.wait_button()

       aavvtt..ffiillee__sseelleeccttiioonn((_[_f_i_l_t_e_r_]))
              Start a file-chooser in the balloon.  It  starts  in  the
              current working directory.  When a directory is chosen it
              changes the working directory to that one.  At the end it
              returns  the selected filename (which is in the then cur‐
              rent working directory) or _n_i_l on error.

              The _f_i_l_t_e_r, if given, should be a function.   It  gets  a
              filename as parameter.  The file is always in the current
              working directory.  If the filter function returns  _f_a_l_s_e
              or  _n_i_l or nothing then the filename is not shown, other‐
              wise it is shown.

              EExxaammppllee::
               textfile = avt.file_selection(
                  function(n)
                    return string.find(n,"%.te?xt$")
                  end)

              Of course _f_i_l_t_e_r can also be the  name  of  a  previously
              defined function.

       aavvtt..ccoolloorr__sseelleeccttiioonn(())
              Start  a  color-chooser  in  the  balloon. It returns two
              strings: first the English name for the color and  second
              the  hexadicimal RGB definition.  Both values can be used
              for selecting colors.

       aavvtt..ggeett__kkeeyy(())
              Waits for a key to be pressed  and  returns  the  unicode
              codepoint  of  the  character.  For some function keys it
              yields a number from the unicode private use section.

       aavvtt..kkeeyy__pprreesssseedd(())
              Checks whether a key was pressed.  To  get  the  key  use
              aavvtt..ggeett__kkeeyy(()).

       aavvtt..cclleeaarr__kkeeyyss(())
              Clears the key buffer

       aavvtt..ppuusshh__kkeeyy((_c_o_d_e_p_o_i_n_t))
              Simulates a pressed key.

       aavvtt..nnaavviiggaattee((_b_u_t_t_o_n_s))
              Shows a navigation bar with the given buttons.

              For buttons use a string with the following characters:

              l:     left

              r:     right (play)

              d:     down

              u:     up

              x:     cancel

              f:     (fast)forward

              b:     (fast)backward

              p:     pause

              s:     stop

              e:     eject

              *:     circle (record)

              +:     plus (add)

              -:     minus (remove)

              ?:     help

              ' ':   spacer (no button)

              Pressing  a  key with one of those characters selects it.
              For the directions you can also use the arrow keys.   The
              <Pause>  key  returns "p".  The <Help> key or <F1> return
              "?".

              It returns the approriete character or a number.

              If audio output ends while this function  is  active,  it
              automatically  pushes either 'f' (forward) or 's' (stop).
              If both are given, 'f' (forward) has precedence.

       aavvtt..mmeennuu((_i_t_e_m_s))
       aavvtt..lloonngg__mmeennuu((_i_t_e_m_s))
              Shows a menu with the _i_t_e_m_s.  The _i_t_e_m_s can be either  an
              array  with  strings.   Then It returns the number of the
              selected item.

              Or _i_t_e_m_s can be again arrays starting with a string, fol‐
              lowed  by one or more results.  The results can be of any
              valid Lua type, including functions.

              The menu starts in the line of the current  cursor  posi‐
              tion.  So you could put a headline before the menu.

              avt.clear()
              avt.say("Please select your favourite food:\n")
              local item = avt.long_menu {
                "Chicken",
                "Chips",
                "Pizza",
                "Spinach"}

       aavvtt..cchhooiiccee((_s_t_a_r_t___l_i_n_e_, _i_t_e_m_s _[_, _k_e_y_] _[_, _b_a_c_k_] _[_,_f_o_r_w_a_r_d_]))
              This  can be used for menus.  It is a more basic function
              than aavvtt..mmeennuu(()).  It returns the number of  the  selected
              item.

              _s_t_a_r_t___l_i_n_e:
                     line, where choice begins

              _i_t_e_m_s: number of items/lines

              _k_e_y:   first key, like "1" or "a", 0 for no keys

              _b_a_c_k:  set  to _t_r_u_e, when the first entry is a back func‐
                     tion

              _f_o_r_w_a_r_d:
                     set to _t_r_u_e, when the  last  entry  is  a  forward
                     function

   AAuuddiioo OOuuttppuutt
       aavvtt..ssttaarrtt__aauuddiioo(())
              Starts the audio subsystem.

              On  success  it returns _t_r_u_e, on error it returns _n_i_l and
              an error message.

       aavvtt..llooaadd__aauuddiioo__ffiillee((_[_f_i_l_e_n_a_m_e _[_,_p_l_a_y_m_o_d_e_]_]))
       aavvtt..llooaadd__bbaassee__aauuddiioo__ffiillee((_[_f_i_l_e_n_a_m_e _[_,_p_l_a_y_m_o_d_e_]_]))
              Reads audio data from a file.  You  can  search  for  the
              file with aavvtt..sseeaarrcchh(()).

              Lua  modules  may  add  support for more audio formats to
              aavvtt..llooaadd__aauuddiioo__ffiillee(()) (for example the module  aakkffaavvaattaarr--
              vvoorrbbiiss).

              When  no  _f_i_l_e_n_a_m_e is given, or the _f_i_l_e_n_a_m_e is _n_i_l or an
              empty string, it returns a silent audio element, ie.  you
              can call its methods, it just doesn't play anything.

              The _p_l_a_y_m_o_d_e can be one of "load", "play" or "loop".

              On  error it returns _n_i_l and an error message.  (Note: in
              version 0.19.0 it also returned a  silent  audio  element
              then.)

       aavvtt..llooaadd__aauuddiioo__ssttrreeaamm((_f_i_l_e _h_a_n_d_l_e _[_,_s_i_z_e _[_,_p_l_a_y_m_o_d_e_]_]))
       aavvtt..llooaadd__bbaassee__aauuddiioo__ssttrreeaamm((_f_i_l_e _h_a_n_d_l_e _[_,_s_i_z_e _[_,_p_l_a_y_m_o_d_e_]_]))
              Reads audio data from an open file handle.  The file must
              be searchable.

              Lua modules may add support for  more  audio  formats  to
              aavvtt..llooaadd__aauuddiioo__ssttrreeaamm(())  (for  example  the  module aakkffaa‐‐
              vvaattaarr--vvoorrbbiiss).

              If size is 0 or not given, it assumes the  audio  is  the
              rest of the file.

              The _p_l_a_y_m_o_d_e can be one of "load", "play" or "loop".

              On error it returns _n_i_l and an error message.

       aavvtt..llooaadd__aauuddiioo((_[_a_u_d_i_o___d_a_t_a _[_,_p_l_a_y_m_o_d_e_]_]))
       aavvtt..llooaadd__bbaassee__aauuddiioo((_[_a_u_d_i_o___d_a_t_a _[_,_p_l_a_y_m_o_d_e_]_]))
              Reads  audio  data  from a string.  Otherwise the same as
              aavvtt..llooaadd__aauuddiioo__ffiillee(()).

              Lua modules may add support for  more  audio  formats  to
              aavvtt..llooaadd__aauuddiioo(())  (for  example the module aakkffaavvaattaarr--vvoorr‐‐
              bbiiss).

              When no _a_u_d_i_o___d_a_t_a is given, or the _a_u_d_i_o___d_a_t_a is _n_i_l  or
              an  empty  string, it returns a silent audio element, ie.
              you can call its methods, it just doesn't play anything.

              The _p_l_a_y_m_o_d_e can be one of "load", "play" or "loop".

              On error it returns _n_i_l and an error message.  (Note:  in
              version  0.19.0  it  also returned a silent audio element
              then.)

       aavvtt..ssiilleenntt(())
              Returns a silent audio element,  ie.  you  can  call  its
              methods, it just doesn't play anything.

              EExxaammppllee::
              audio = avt.load_audio_file(filename) or avt.silent()

              In  this  example  you  get  a silent sound when the file
              could not be read.

       aavvtt..aalleerrtt(())
              Returns a pseudo audio  element,  that  calls  aavvtt..bbeellll(())
              when you play it.

       aavvtt..aauuddiioo__ppllaayyiinngg((_[_a_u_d_i_o___d_a_t_a_]))
              Checks  if the audio is currently playing.  If _a_u_d_i_o___d_a_t_a
              is given and is not _n_i_l then it checks, if the  specified
              audio   is  playing.   This  can  also  be  checked  with
              _a_u_d_i_o::ppllaayyiinngg(())_.

       aavvtt..wwaaiitt__aauuddiioo__eenndd(())
              Waits until the audio output ends.

              This also ends an audio-loop, but still plays to the  end
              of the current sound.

       aavvtt..ssttoopp__aauuddiioo(())
              Stops the audio output immediately.

       aavvtt..ppaauussee__aauuddiioo((_t_r_u_e||_f_a_l_s_e))
              pause (_t_r_u_e) or resume (_f_a_l_s_e) the audio output

       _a_u_d_i_o::ppllaayy(())
       _a_u_d_i_o(())
              Plays the _a_u_d_i_o data.  The _a_u_d_i_o must have been loaded by
              aavvtt..llooaadd__aauuddiioo__ffiillee(()) or aavvtt..llooaadd__aauuddiioo__ssttrriinngg(()).

              Only one sound can be played at the same time.  When  you
              play  another  sound  the  previous  one is stopped.  Use
              aavvtt..wwaaiitt__aauuddiioo__eenndd(()) to play sounds in a sequence.

              The audio can also be played by calling the  audio  vari‐
              ables like a function.

              play_audio_file = function (filename)
                local sound = avt.load_audio_file(avt.search(filename))
                if sound then sound:play() end
              end

       _a_u_d_i_o::lloooopp(())
              Plays  _a_u_d_i_o  data  in  a loop.  The _a_u_d_i_o must have been
              loaded        by         aavvtt..llooaadd__aauuddiioo__ffiillee(())         or
              aavvtt..llooaadd__aauuddiioo__ssttrriinngg(()).

              This is for example useful for short pieces of music.

              You  can stop the audio loop with aavvtt..wwaaiitt__aauuddiioo__eenndd(()) or
              aavvtt..ssttoopp__aauuddiioo(()).

       _a_u_d_i_o::ppllaayyiinngg(())
              Checks if this _a_u_d_i_o  data  is  currently  playing.   The
              _a_u_d_i_o  must  have been loaded by aavvtt..llooaadd__aauuddiioo__ffiillee(()) or
              aavvtt..llooaadd__aauuddiioo__ssttrriinngg(()).

              This is the same as aavvtt..aauuddiioo__ppllaayyiinngg((aauuddiioo)).

       _a_u_d_i_o::ffrreeee(())
              Frees the _a_u_d_i_o data.  If this _a_u_d_i_o is  currently  play‐
              ing, it is stopped.

              Audio data is also freed by the garbage collector.

       aavvtt..sseett__aauuddiioo__eenndd__kkeeyy ((_k_e_y))
              Define  a  key  that should automatically be pressed when
              audio ends.  The _k_e_y should be given as a number for  the
              Unicode codepoint.  Use _0 to deactivate it.

              The function returns the value that was previously set.

       aavvtt..qquuiitt__aauuddiioo(())
              Quit the audio subsystem.

              This is not needed in normal programs.  Only use this, if
              you are sure you need it.

   FFiillee--SSyysstteemm
       aavvtt..ddiirrsseepp
              This variable contains the systems  directory  separator;
              either "/" or "\".

       aavvtt..ddaattaappaatthh
              This  variable  contains  the  default searchpath for the
              function aavvtt..sseeaarrcchh(()) (see below).  Directories are sepa‐
              rated  by  semicolons.  There are no patterns like in the
              paths for Lua modules, just directories.   This  variable
              is initialized by the environment variable _A_V_T_D_A_T_A_P_A_T_H or
              it gets a system-specific default.

       aavvtt..sseeaarrcchh((_f_i_l_e_n_a_m_e _[_,_p_a_t_h_]))
              Searches for a file with the given _f_i_l_e_n_a_m_e in the  given
              _p_a_t_h.   If  no  _p_a_t_h  is  given,  it  uses  the  variable
              _a_v_t_._d_a_t_a_p_a_t_h as default.

              On success it returns the full path to the file,  if  the
              file is not found, it returns _n_i_l and an error message.

       aavvtt..ggeett__ddiirreeccttoorryy(())
       aavvtt..ggeettccwwdd(())
              Returns  the  current  working  directory.   On  error it
              returns _n_i_l and an error message.

       aavvtt..sseett__ddiirreeccttoorryy((_d_i_r_e_c_t_o_r_y))
       aavvtt..cchhddiirr((_d_i_r_e_c_t_o_r_y))
              Sets the working directory to _d_i_r_e_c_t_o_r_y.  If _d_i_r_e_c_t_o_r_y is
              _n_i_l, nothing or an empty string, it does nothing.

              Returns _t_r_u_e on success or on error _n_i_l and an error mes‐
              sage.

              EExxaammppllee::
              avt.set_directory(os.getenv("HOME") or os.getenv("USERPROFILE"))

       aavvtt..ddiirreeccttoorryy__eennttrriieess((_[_d_i_r_e_c_t_o_r_y_]))
              Get a list of directory entries of the given _d_i_r_e_c_t_o_r_y or
              the current directory if none is given.

              On  success  it returns a table (an array) and the number
              of entries.  On error it returns _n_i_l and  an  error  mes‐
              sage.

              The  list  contains normal files, including hidden files,
              subdirectories and any other type of entry.  It does  not
              contain "." or "..".

              Note:  the  names  are in a system specific encoding.  To
              display the names you either have to change the  encoding
              of the display with aavvtt..eennccooddiinngg((""SSYYSSTTEEMM"")) or convert the
              names like this: aavvtt..ssaayy((aavvtt..rreeccooddee((nnaammee,, ""SSYYSSTTEEMM"")))).

       aavvtt..eennttrryy__ttyyppee((_e_n_t_r_y))
              Get the type of a directory entry and its size.

              On success it returns the type of the directory entry  as
              string  and  the  size as number.  The type can be one of
              "file", "directory", "character device", "block  device",
              "fifo", "socket" or "unknown".

              On error it returns _n_i_l and an error message.

              Symbolic  links  are  followed.   That means, you get the
              type of the resulting entry.  Broken  links  are  treated
              like not existing entries.

   MMiisscceellllaanneeoouuss
       aavvtt..llaanngguuaaggee
              This  variable contains a language code for messages.  It
              should be a two-letter code conforming to ISO 639-1.  The
              variable  is  not  set,  when  the  language could not be
              detected.

       aavvtt..ttrraannssllaattee((_t_e_x_t))
              Translate the _t_e_x_t, if possible.

              See section TTrraannssllaattiioonnss for how to provide translations.

       aavvtt..rreeccooddee((_s_t_r_i_n_g_, _f_r_o_m_c_o_d_e _[_,_t_o_c_o_d_e_]))
              Recode the given _s_t_r_i_n_g, which is encoded as _f_r_o_m_c_o_d_e  to
              a  string  encoded  as  _t_o_c_o_d_e.   When  you give just one
              encoding, it encodes into the currently set  text  encod‐
              ing.   If you want to encode from the current encoding to
              something else, then use _n_i_l for _f_r_o_m_c_o_d_e.

              To encode to or from the systems  default  encoding  (for
              example for filenames) use an empty string (""""), or ""SSYYSS‐‐
              TTEEMM"".

              Returns the recoded string or _n_i_l on error.

              AAtttteennttiioonn:: Converting to UTF-8 is always possible.   Con‐
              verting  to other encodings however can fail.  Characters
              which cannot be converted are replaced with  the  control
              character  _S_U_B  (_"_\_x_1_A_").  So to make sure that everyting
              worked well, you can search for  that  character  in  the
              resulting  string.   If  it is there, something went most
              probably wrong.

       aavvtt..rriigghhtt__ttoo__lleefftt((_t_r_u_e||_f_a_l_s_e))
              Activate or deactivate the right to left writing mode.

              AAtttteennttiioonn:: This is an experimental  feature,  that  might
              not always work.

       aavvtt..sseett__fflliipp__ppaaggee__ddeellaayy((_[_d_e_l_a_y_]))
              Set  the delay for aavvtt..fflliipp__ppaaggee(()) or "\f".  Use no value
              for the default delay, or 0 to set no delay.

       aavvtt..aaccttiivvaattee__ccuurrssoorr((_t_r_u_e||_f_a_l_s_e))
              Show the cursor.

       aavvtt..cclleeaarr__ssccrreeeenn(())
              Clears the whole screen or  window  (not  just  the  bal‐
              loon!).

       aavvtt..cclleeaarr__ddoowwnn(())
              Clears  from cursor position down the viewport.  If there
              is no balloon yet, it is drawn.

       aavvtt..cclleeaarr__eeooll(())
              Clear the end of line (depending on text direction).

       aavvtt..cclleeaarr__bbooll(())
              Clears the beginning  of  the  line  (depending  on  text
              direction).

       aavvtt..cclleeaarr__lliinnee(())
              Clears the line.

       aavvtt..cclleeaarr__uupp(())
              Clears from cursor position up the viewport.  If there is
              no balloon yet, it is drawn.

       aavvtt..rreesseerrvvee__ssiinnggllee__kkeeyyss((_t_r_u_e||_f_a_l_s_e))
              Reserves single keys, such as <ESC> or <F11>.

       aavvtt..sswwiittcchh__mmooddee((_m_o_d_e))
              Switches the window mode.  Use  either  of  _"_w_i_n_d_o_w_",  or
              _"_f_u_l_l_s_c_r_e_e_n_".

              (The  modes _"_a_u_t_o_" and  _"_f_u_l_l_s_c_r_e_e_n _n_o _s_w_i_t_c_h_" don't work
              here.)

       aavvtt..ggeett__mmooddee(())
              Returns the window mode (see aavvtt..sswwiittcchh__mmooddee ((mmooddee))).

       aavvtt..ttooggggllee__ffuullllssccrreeeenn(())
              Toggles the fullscreen mode on or off.

       aavvtt..uuppddaattee(())
              Update everything and take care of events.   This  should
              be  used  in  a loop, when the program is doing something
              else.

       aavvtt..ccrreeddiittss((_t_e_x_t_, _c_e_n_t_e_r_e_d))
              Shows final credits.

              If the second parameter is _t_r_u_e, every line is centered.

       aavvtt..vviieewwppoorrtt((_x_, _y_, _w_i_d_t_h_, _h_e_i_g_h_t))
              Sets a viewport (sub-area of the  textarea).   The  upper
              left corner is at 1, 1.

       aavvtt..sseett__ssccrroollll__mmooddee((_m_o_d_e))
              Sets the scroll mode, ie. how it reacts when trying to go
              beyond the last line.  The _m_o_d_e  is  either  -1  for  "do
              nothing" or 0 for page-fipping or 1 for scrolling.

       aavvtt..ggeett__ssccrroollll__mmooddee(())
              Gets the scroll mode (see aavvtt..sseett__ssccrroollll__mmooddee(())).

       aavvtt..nneewwlliinnee__mmooddee((_t_r_u_e||_f_a_l_s_e))
              When  the  newline_mode  is activated (default) a newline
              character sets the cursor at the beginning of a new line.
              When  it  is  off  the cursor goes into the next line but
              stays in the same horizontal position.

       aavvtt..sseett__aauuttoo__mmaarrggiinn((_t_r_u_e||_f_a_l_s_e))
              Sets the automargin mode, ie. whether to start a new line
              automatically when the text doesn't fit in a line.

       aavvtt..ggeett__aauuttoo__mmaarrggiinn(())
              Gets the automargin mode.

       aavvtt..sseett__oorriiggiinn__mmooddee((_t_r_u_e||_f_a_l_s_e))
              Sets  the  origin  mode.  When the origin mode is on, the
              coordinates 1, 1 are always in the top left of  the  bal‐
              loon,  even  when the viewport does not start there. When
              the origin mode is off, the coorinates 1, 1 are  the  top
              left of the viewport.

       aavvtt..ggeett__oorriiggiinn__mmooddee(())
              Gets the origin mode (see aavvtt..sseett__oorriiggiinn__mmooddee).

       aavvtt..sseett__mmoouussee__vviissiibbllee((_t_r_u_e||_f_a_l_s_e))
              Sets whether the mouse pointer is visible or not.

              NNoottee::  In  windowing systems this has only an affect when
              the mouse pointer is inside of the window.

       aavvtt..lloocckk__uuppddaatteess((_t_r_u_e||_f_a_l_s_e))
              Sets a lock on updates inside of the balloon.   This  can
              be used for speedups.

       aavvtt..vveerrssiioonn(())
              Returns the version of AKFAvatar as string.

       aavvtt..ccooppyyrriigghhtt(())
              Returns the copyright notice for AKFAvatar as string.

       aavvtt..lliicceennssee(())
               Returns the license notice for AKFAvatar as string.

       aavvtt..qquuiitt(())
              Quit  the  avatar subsystem (closes the window).  It also
              quits the audio subsystem.

              This function is not needed for  normal  programs.   Only
              use it, if your program should continue working without a
              visible window.

       aavvtt..llaauunncchh((_p_r_o_g_r_a_m _[_,_a_r_g_u_m_e_n_t_s _._._._]))
              Quit AKFAvatar and launch the given _p_r_o_g_r_a_m.  This  func‐
              tion  never returns.  Either the _p_r_o_g_r_a_m runs, or a fatal
              error is shown.

              If you want to catch the error with ppccaallll,  you  have  to
              initialize AKFAvatar again...

TTrraannssllaattiioonnss
       How to translate Lua-AKFAvatar scripts.

       To  make  translations  for your Lua-AKFAvatar script, you first
       have to define the variable aavvtt..ttrraannssllaattiioonnss.  This is a stacked
       table.   Well, it's not easy to describe, but have a look at the
       example.

       The language is determined by the variable  aavvtt..llaanngguuaaggee.   This
       variable  should  be automatically initialized by Lua-AKFAvatar,
       but it can be changed by the script.  It contains  a  two-letter
       language code conforming to ISO 639-1.

       The  function  aavvtt..ttrraannssllaattee((_t_e_x_t)) then translates the _t_e_x_t.  If
       the translation is not  available,  then  it  retruns  the  _t_e_x_t
       unmodified.

       It is useful to define a local alias for aavvtt..ttrraannssllaattee named LL:
         local L = avt.translate
       Then you can simply prepend your string literals with LL.

       EExxaammppllee:
       local avt = require "lua-akfavatar"

       avt.encoding("UTF-8")

       avt.translations = {

         ["Hello world!"] = {
           es="Â¡Hola mundo!",
           fr="Bonjour le monde!",
           de="Hallo Welt!",
           sv="Hej VÃ¤rlden!",
           },

         ["That's live!"] = {
           de="So ist das Leben!",
           fr="C'est la vie!" },
       }

       local L = avt.translate

       -- avt.language = "de"

       avt.start()
       avt.avatar_image("default")
       avt.tell(L"Hello world!", "\n", L"That's live!");
       avt.wait_button ()

       HHiinnttss:

       – Although it is not required, but you should use English as the
         default language.

       – If you have text with variables  in  it,  it  is  not  a  good
         approach to split the text into parts.  It is better to define
         a format string for ssttrriinngg..ffoorrmmaatt(()).

       – The string in  the  translations  table  must  match  exactly.
         Please  keep  in  mind that when you change the strings in the
         program you also have to change the table!

       – The string could also be a filename for a textfile or a speech
         recording.

       By the way, this implementation was inspired by GNU gettext.

SSEEEE AALLSSOO
       lluuaa--aakkffaavvaattaarr(1)  lluuaa(1)  aakkffaavvaattaarr--ggrraapphhiicc(3) aakkffaavvaattaarr--tteerrmm(3)
       aakkffaavvaattaarr..uuttff88(3)
       hhttttpp::////wwwwww..lluuaa..oorrgg//mmaannuuaall//55..22//
       hhttttpp::////aakkffaavvaattaarr..nnoonnggnnuu..oorrgg//mmaannuuaall//



AKFAvatar                         2013-07-09        Lua-AKFAvatar reference(3)
