[Home]	[About]
[Screenshots]	[Download]
[News]	[Community]
[Documentation]	[Manual]
[Bugs & Requests]	[Wiki]

/home/tetron/hack/vos/libs/vos/metaobjects/misc/avatar.hh

Go to the documentation of this file.

/* $Id: avatar.hh,v 1.7 2005/12/18 09:59:40 tetron Exp $ */

/* Copyright (C) 2002,2003,2004 Reed Hedges 

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

*/


#ifndef _AVATAR_HH_
#define _AVATAR_HH_

#include <vos/vos/vos.hh>
#include <vos/metaobjects/misc/hypercard.hh>


#include "miscdefs.hh"
namespace VOS {

/** @class Avatar avatar.hh vos/metaobjects/misc/avatar.hh
  * @ingroup libmetaobject_misc

    Indicates that this object represents a human or automated agent.
    It is the representative of the human user or automated agent.
    In a 3D environment, will usually be used with an A3DL::Object3D type
    (such as A3DL::Model)
    It will also often be used with a Talkative metaobject.
*/

class MISC_API Avatar : public MetaObject
{

public:

    /** @name Presence Codes
     *  This is a simple schema, that mirrors the four presence codes
     *  in the <a href="http://www.jabber.org">Jabber</a> IM system.
     *  In the future there may be more. If you think something should
     *  be added, <a href="http://interreality.org/lists">let us know</a>.
     */
    //@{
    static const unsigned short AVAILABLE;  ///< for "chat"
    static const unsigned short AWAY;       ///< for "away"
    static const unsigned short EXTENDEDAWAY;   ///< for "xa"
    static const unsigned short BUSY;   ///< for "dnd"
    //@}

    /** @internal */
    Avatar(VobjectBase* superobject);


    /** Return type string ("misc:avatar") */
    const std::string getVOSType();

    /** @internal */
    static MetaObject* new_Avatar(VobjectBase* s, const std::string& t);

    /** Get the value of avatar:nick property (A text string containing a short name that can be used to identify this avatar. If this property is omitted, the object's contextual name may be used.). */
    std::string getNick();

    /** Get Property object for nick. */
    VUtil::vRef<Property> getNickObj();

    /** Set Property object for nick */
    void setNickObj(Property* obj);

    /** Set misc:nick property.
        @param value The new value. Should be a short string of plain text.
    */
    void setNick(const std::string& value);

    /** Add a PropertyListener to the misc:nick property. */
    void addNickListener(PropertyListener* listener);

    /** Remove a PropertyListener from the misc:nick property. */
    void removeNickListener(PropertyListener* listener);

    /** Get the value of misc:fullname property (A text string containing the full name of the user or agent.). */
    std::string getFullname();

    /** Get the datatype of misc:fullname property. */
    std::string getFullnameDatatype();

    /** Set misc:fullname property.
        @param value The new value
        @param datatype The new datatype: if omitted, then the
        existing datatype will be preserved
    */
    void setFullname(const std::string& value, const std::string& datatype = "?");

    /** Get the fullname Property object */
    VUtil::vRef<Property> getFullnameObj();

    /** Set the fullname object */
    void setFullnameObj(Property* obj);

    /** Get the value of misc:info property.
     * This is for More information about the user or agent, for example a
     * <a href="http://www.foaf-project.org">FOAF document</a>, a picture, a
     * short biographical text, a URL to a web page or email address, or
     * whatever. (Use the datatype of the property to distinguish; I
     * recommend checking out FOAF)
     * @todo support multiple "info" properties.
     */
    std::string getInfo();

    /** Get the datatype of misc:info property. */
    std::string getInfoDatatype();

    /** Set misc:info property.
        @param value The new value
        @param datatype The new datatype: if omitted, then the existing datatype will be preserved. */
    void setInfo(const std::string& value, const std::string& datatype = "?");

    /** Get info Property object */
    VUtil::vRef<Property> getInfoObj();

    /** Set info Property object */
    void setInfoObj(Property* obj);

    /** Add PropertyListener to misc:info property */
    void addInfoListener(PropertyListener* listener);

    /** Remove a PropertyListener from misc:info property */
    void removeInfoListener(PropertyListener* listener);

    /** Set the user identifier (typically "user@host").
        This can be used
        by specialized applications to work with other external programs
        in a Unix or Unix-like network.  Basically not generally useful
        for much and will rarely be used.
    */
    void setUserId(const std::string& userid);

    /** Get the user identifier (typically "user@host")
        This can be used
        by specialized applications to work with other external programs
        in a Unix or Unix-like network.  Basically not generally useful
        for much and will rarely be used :)
     * @throws NoSuchObjectError No user-id property exitst
     * @throws bad_cast user-id subobject is not a Property. */
    std::string getUserId();

    /** Get a numeric code that represents the value of misc:presence_code property (A text std::string indicating the presence/status/availability of the user or agent.)  The returned value will match one of the constants Avatar::AVAILABLE Avatar::AWAY, Avatar::EXTENDEDAWAY, or Avatar::BUSY.  */
    unsigned short getPresence();

    /** Set misc:presence_code property according to the parameter code.
        @param code The new numeric code. See above for list of constants.
    */
    void setPresence(unsigned short code);

    /** Get info Property object */
    VUtil::vRef<Property> getPresenceObj();

    /** Set info Property object */
    void setPresenceObj(Property* obj);

    /** Add a PropertyListener to the misc:presence_code property. */
    void addPresenceListener(PropertyListener* listener);

    /** Remove a PropertyListener from the misc:presence_code property. */
    void removePresenceListener(PropertyListener* listener);

    /** Get the value of misc:presence_description property (Text describing the presence/status/availability of the user or agent in a more free-form manner (e.g. "Went to find more coffee. Back in a bit.")). */
    std::string getPresenceDescription();

    /** Get the datatype of misc:presence_description property. */
    std::string getPresenceDescriptionDatatype();

    /** Set misc:presence_description property.
        @param value The new value
        @param datatype The new datatype: if omitted, then the existing datatype will be preserved. */
    void setPresenceDescription(const std::string& value, const std::string& datatype = "?");

    /** Get info Property object */
    VUtil::vRef<Property> getPresenceDescriptionObj();

    /** Set info Property object */
    void setPresenceDescriptionObj(Property* obj);


    /** Set object currently "selected" by this avatar.
     *  This can be used as a pointer or indicator to an object of interest,
     *  which can therefore be used by other users or applications.
     *  @param obj The selected object. If  0, then any existing object is
     *      removed. Otherwise: If there is no "misc:selected-object" child,
     *      then a new Hypercard will be created linking to 'obj' and added.
     *      If such a child does  exist and is a hypercard, then its link will
     *      be replaced with obj.
     */
    void setSelectedObj(Vobject* obj);

    /** Get "selected" object.
        @see setSelectedObj
     */
    VUtil::vRef<Vobject> getSelectedObj();

    /** Get "selected" hypercard.
        @see setSelectedObj
     */
    VUtil::vRef<Hypercard> getSelectedHypercard();

    /** Set "selected" hypercard.
        @see setSelectedObj
    */
    void setSelectedHypercard(Hypercard* hc);

    /** Set this user's local timezone's offset from GMT (UTC). E.g.
        if you are in GMT use 0. If you are in US Eastern standard without
        daylight savings, use -5, etc.
     */
    void setLocalTimezone(int tz);

    /** Get this user's local timezone's offset from GMT (UTC).
        @see setLocalTimezone
     */
    int getLocalTimezone();


};

}   // namespace VOS


#ifndef MISC_EXPORTS
IMPORT_METAOBJECT_FACTORIES(Avatar)
#endif

#endif // #ifdef _AVATAR_HH_