vos/gui/gui/select_list.hh

Go to the documentation of this file.

/* $Id: select_list.hh,v 1.12 2003/07/24 05:18:26 tetron Exp $ */


/** @file select.boolean.hh Defines MetaObject class for select.boolean type (revision 0).

    Copyright (C) 2002 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 _GUI_SELECT_LIST_HH_
#define _GUI_SELECT_LIST_HH_

#if defined(_WIN32) && defined(_MSC_VER)
# ifdef VOSGUI_EXPORTS
#  define VOSGUI_API __declspec(dllexport)
# else
#  define VOSGUI_API __declspec(dllimport)
# endif
#else
# define VOSGUI_API
#endif

#include <vos/corelibs/vos/vos.hh>
#include <vos/metaobjects/property/property.hh>
#include <vos/gui/gui/select.hh>

namespace VOSGUI {

/** MetaObject implementing SelectList Object Type. 
 *  This control presents a list of objects. One or more may be selected,
 *  in which case they are added to the "selected" group.
 *
 *  @todo add subobjects representing columns, containing properties with
 *   text or images to be used in each column. support multiple view types.
 *   icons.
 *
 * @todo add property specifying order to try determining what text to display
 *  in list (e.g. "subobj(misc:title),property-contents,context-name"). or use
 *  a list of properties.  Or change the choices group to contain small structure 
 *  objects (linking to label and the actual object)
 *
 *  @warning You must call initialize() for this object to work correctly.
*/
class VOSGUI_API SelectList : public virtual Select
{

protected:
    vRef<Vobject>   choices;
    vRef<Vobject>   selected;


public:

    /** Constructor */
    SelectList(MetaObject* superobject);

    /** Destructor */
    virtual ~SelectList();

    /** Return type string ("gui:widget.select.list") */
    virtual const string getType();

    /** Register Extenders */
    static void registerExtenders();

    /** Get the selected objects  */
    deque<Vobject*> getSelected();

    /** Get the first selected object. This is convenient for use when
        multiple selection is off. (But does not make much sense when
        it is on).
        Returns 0 if there are no object selected.
    */
    Vobject* getFirstSelected();



    /** Add an object to list 
     * @param obj   The object to add.
     * @param title  Text to put in the list. 
     * @param pos   Position to add it at. See Vobject::insertChild() for
     *              the meaning of negative positions. If not specified, 
     *              the object will be added at the end. 
     *              Behavior of clients when there are "gaps" (the list
     *              is missing objects at some positions) is undefined. 
     * 
     */
    void add(Vobject* obj, const string& title = "item", int pos = -1);

    /** Remove (the first occurance of) an object from the list */
    void remove(Vobject* obj) throw (NoSuchObjectError);

    /** Set multiple selection property. This does not affect the behavior
     * of the add() method, rather it instructs client applications to
     * allow or disallow multiple selections.
     *
     * @param m If true, the property is set to "yes", and multiple 
     *          selections should be allowed. If false, only one selection 
     *          should be allowed. If no argument is given, multiple selection 
     *          will be turned on.
     *          This property is initially set to "yes".
     *
     * @param pac   Property access control policty to use on this property.
     *          If not given, defaults to NoPropertyAccessControl::static_
     *
     */
    void setMultiple(bool m = true, PropertyAccessControl* pac = 0);

    bool getMultiple();

    Property* getMultipleObj();

    /** Return the Vobject containing selected objects */
    Vobject* selectedObjectList();

    /** Set the selected objects container object. Don't call after
        initialize() or it won't work. */
    void setSelectedObj(Vobject* obj);

    /** Return the Vobject containing choices objects */
    Vobject* choicesObjectList();

    /** Set the choices container object. Don't call after
        initialize() or it won't work right. */
    void setChoicesObj(Vobject* obj);

    /** Find "gui:selected" and "gui:choices" subobjects. 
     * You MUST call this, or call setSelectedObj(), setChoicesObj() and
        setMultiple(), for things to work correctly. */
    virtual void initialize();


    /** Find a suitable label Property for an item (for internal use, 
        primarily). The following sources are tried, in this order:
        <ol>
            <li>The value of the item's "misc:label" subproperty</li>
            <li>The value of the item's "misc:title" subproperty</li>
            <li>The value of the item's "misc:name" subproperty</li>
            <li>The value of the item's "misc:nick" subproperty</li>
            <li>0</li>
        </ol>
        @todo Use a property to set the order of label sources.
    */
    Property* getItemLabel(Vobject& item);
            
        
};



/** Local version of SelectList. 
 * @warning You must call initialize() for this object to work properly. */
class VOSGUI_API LocalSelectList : public virtual SelectList, public virtual LocalSelect
{

public:

    /** Constructor */
    LocalSelectList(MetaObject* superobject);

    /** Destructor */
    ~LocalSelectList();

    /** Static generator, for factory. */
    static MetaObject* new_LocalSelectList(MetaObject* superobject, const string& type);

    /** Creates required subobjects, and adds DoNothingListener to them
     * (this makes future operations faster). 
     * You MUST call this function (or setSelectedObj, setChoicesObj and
     * setMultiple) for things to work correctly.
     * @bug always sets the property access control on the "multiple" property
     *       to NoPropertyAccessControl::static_ 
     */
    virtual void initialize();


};


/** Remote version of SelectList. */
class VOSGUI_API RemoteSelectList : public virtual SelectList, public virtual RemoteSelect
{
public:

    /** Constructor */
    RemoteSelectList(MetaObject* superobject);

    /** Destructor */
    virtual ~RemoteSelectList();

    /** Static generator, for factory. */
    static MetaObject* new_RemoteSelectList(MetaObject* superobject, const string& type);


};

} //namespace VOSGUI 

#endif // #ifdef _GUI_SELECT_LIST_HH_

---