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.

              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..ffrreeqquueennccyy((_f_r_e_q_u_e_n_c_y _[_, _v_o_l_u_m_e_]))
              Generates an audio element with a short tone of the given
              _f_r_e_q_u_e_n_c_y (in hertz (Hz), rounded to an integer) with the
              given _v_o_l_u_m_e (0-100, default 75).  This audio element can
              be played cleanly as an audio loop.

              EExxaammppllee::
              avt.frequency(440):loop()

       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.

              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.

              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-10-02        Lua-AKFAvatar reference(3)
