uelem.hpp

/************************************************************************
 *
 *  uelem.hpp: Element Nodes (lightweight containers that can have children)
 *  Ubit GUI Toolkit - Version 6
 *  (C) 2009 | Eric Lecolinet | TELECOM ParisTech | http://www.enst.fr/~elc/ubit
 *
 * ***********************************************************************
 * COPYRIGHT NOTICE :
 * THIS PROGRAM IS DISTRIBUTED WITHOUT ANY WARRANTY AND WITHOUT EVEN THE
 * IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 * YOU CAN REDISTRIBUTE IT AND/OR MODIFY IT UNDER THE TERMS OF THE GNU
 * GENERAL PUBLIC LICENSE AS PUBLISHED BY THE FREE SOFTWARE FOUNDATION;
 * EITHER VERSION 2 OF THE LICENSE, OR (AT YOUR OPTION) ANY LATER VERSION.
 * SEE FILES 'COPYRIGHT' AND 'COPYING' FOR MORE DETAILS.
 * ***********************************************************************/

#ifndef _uelem_hpp_
#define _uelem_hpp_ 1
#include <string.h>     // memset
#include <ubit/uattr.hpp>
#include <ubit/uupdate.hpp>
#include <ubit/uargs.hpp>
#include <ubit/ustr.hpp>
namespace ubit {
  
  // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  class UElem: public UNode {
    UElem& operator=(const UElem&);
    
    explicit UElem(const UElem&);
    
  public:
    //UCLASS("#element", UElem, new UElem)
    UCLASS(UElem)
    
    UElem(UArgs node_arglist = UArgs::none);
    virtual ~UElem();
    
    virtual void destructs();
    
    virtual UElem* toElem() {return this;}
    virtual const UElem* toElem() const {return this;}
    
    static UStyle* createStyle();
    const UStyle& getStyle(UUpdateContext*) const;
    virtual int getNodeType() const {return ELEMENT_NODE;}
    
    virtual const UStr& getNodeName() const {return getClass().getName();}
    
    virtual int getDisplayType() const {return INLINE;}
    
    virtual void initNode(UDoc* context) {}
    
    
    // - - - - - - - - - - - - - - - - - - - - - - - - 
    // attributes.
    
    UElem& setAttr(UNode& attribute);
    UElem& addAttr(const UArgs& attributes);
    UElem& removeAttr(UNode& attribute, bool auto_delete = true);
    UElem& removeAllAttrs(bool auto_delete = true);
    bool getAttrValue(UStr& value, const UStr& attr_name) const;
    UAttr* getAttr(const UStr& attr_name) const;
    template <class ATTR> 
    ATTR* getAttr() const {ATTR* a; _attributes.findClass(a); return a;}
    template <class ATTR> 
    ATTR& obtainAttr()  
    {ATTR* a; _attributes.findClass(a); if (!a) addAttr(a = new ATTR); return *a;}
    // - - - - - - - - - - - - - - - - - - - - - - - - - - 
    // children.
    
    virtual bool isParentOf(const UNode& possible_child) const;
    
    UElem& add(const UArgs& children);
    UElem& add(const UArgs& children, int position);
    UElem& add(const UArgs& children, UChildIter iterator);
    virtual UElem& addImpl(const UArgs& nodes, UChildIter pos, UChildren& in_list);
    virtual bool addImpl1(const UChild& node, UChildIter pos, UChildren& in_list);
    
    // - - - - 
    
    UElem& remove(UNode& child, bool auto_delete = true);
    UElem& remove(int pos, bool auto_delete = true);
    UElem& remove(UChildIter pos, bool auto_delete = true);
    UElem& removeAll(bool auto_delete = true);
    virtual UElem& removeImpl(UChildIter begin, int N, bool autodel, UChildren& in_list);
    virtual bool removeImpl1(UChildIter pos, int auto_delete, UChildren& in_list);  
    
    // - - - - 
    
    UChildren& getChildren() const {return children();}
    /* return the child list.
     * @see: child(), getChild(), cbegin(), cend(), crbegin(), crend(), attributes().
     */
    
    int getChildCount() const {return children().size();}
    /* return the number of children.
     * @see: child(), getChild(), cbegin(), cend(), crbegin(), crend(), attributes().
     */
    
    UChildIter child(int pos) const {return children().at(pos);}
    UNode* getChild(int pos) const;  
    UChildIter cbegin() const {return children().begin();}
    UChildIter cend() const {return children().end();}
    
    UChildReverseIter crbegin() const {return children().rbegin();}
    
    UChildReverseIter crend() const {return children().rend();}
    
    // - - - text - - - - - - - - - - - - - - - - - - - - - - - - -
    
    virtual UStr retrieveText(bool recursive = true) const;
    virtual void retrieveText(UStr& string, bool recursive = true) const;
    // - - - graphics and layout - - - - - - - - - - - - - - - - - -
    
    virtual bool isShown() const;
    bool isShowable() const {return emodes.IS_SHOWABLE;}
    void setShowable(bool s) const {emodes.IS_SHOWABLE = s;}
    
    virtual void show(bool = true);
    static void closeWin(UInputEvent&, int status);
    void repaint() {update(UUpdate::paint);}
    
    void update() {update(UUpdate::layoutAndPaint);}
    
    virtual void update(const UUpdate& update_options, UDisp* = null);
    void doUpdate() {doUpdate(UUpdate::layoutAndPaint, null);}
    
    virtual void doUpdate(const UUpdate&, UDisp* = null);
    // - - - events - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    
    UElem& ignoreEvents(bool state = true);
    UElem& catchEvents(const UChild& condition_callback_expr);
    UElem& observeChildrenEvents(const UChild& condition_callback_expr);
    bool isIgnoringEvents() const {return emodes.IGNORE_EVENTS;}
    
    bool hasCallback(long callback_id) const;
    
    virtual bool fire(UEvent&) const;
    
    // - - - states - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    
    UElem& enable(bool state = true) {return setEnabled(state);} 
    
    virtual UElem& setEnabled(bool state = true, bool call_callbacks = true);
    bool isEnabled() const;
    
    // - - - - -
    
    virtual UElem& setSelected(bool state = true, bool call_callbacks = true);
    bool isSelected() const {return emodes.IS_SELECTED;}  
    
    bool isSelectable() const {return emodes.IS_SELECTABLE;}
    UElem& setSelectable(bool state = true);
    
    // - - - - -
    
    bool isArmed() const;
    
    bool isArmable() const {return emodes.IS_ARMABLE;}
    UElem& setArmable(bool state = true);
    
    // - - - - -
    
    UElem& setAutoRepeat(bool state = true);
    bool isAutoRepeat() const {return emodes.IS_AUTO_REPEAT;}
    
    bool isCrossable() const {return emodes.IS_CROSSABLE;}
    UElem& setCrossable(bool state = true);
    
    UElem& setBrowsable(bool = true);
    bool isBrowsable() const {return emodes.IS_BROWSABLE;}
    
    bool isDragged() const;
    bool isDraggable() const {return emodes.IS_DRAGGABLE;}
    UElem& setDraggable(bool = true);
    
    bool isDroppable() const {return emodes.IS_DROPPABLE;}
    UElem& setDroppable(bool = true);
    
    // - - - - -
    
    bool isTextEditable() const {return emodes.IS_TEXT_EDITABLE;}
    bool isFloating() const {return emodes.IS_FLOATING;}
    bool isVertical() const {return emodes.IS_VERTICAL;}    // && HAS_ORIENT ?  !!!!
    bool isWidthResizable()  const {return !emodes.IS_WIDTH_UNRESIZABLE;}
    bool isHeightResizable() const {return !emodes.IS_HEIGHT_UNRESIZABLE;}
    virtual bool isSubWin() const {return false;}  // redefined by USunWin => MUST be virtual!
    
    void disableMenuClosing(bool s = true) {emodes.DONT_CLOSE_MENUS = s;}
    
    bool isMenuClosingDisabled() const {return emodes.DONT_CLOSE_MENUS;}
    
    // - - - impl. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
#ifndef NO_DOC
    
    struct Modes {
      unsigned IS_SHOWABLE:1;      
      unsigned IS_BROWSABLE:1;     
      unsigned IS_CROSSABLE:1;     
      unsigned IS_ARMABLE:1;       
      unsigned IS_AUTO_REPEAT:1;   
      unsigned IS_DRAGGABLE:1;     
      unsigned IS_DROPPABLE:1;     
      unsigned IS_SELECTABLE:1;    
      unsigned IS_SELECTED:1;      
      unsigned IS_TEXT_SELECTABLE:1;
      unsigned IS_TEXT_EDITABLE:1; 
      unsigned IS_WIDTH_UNRESIZABLE:1;
      unsigned IS_HEIGHT_UNRESIZABLE:1;
      unsigned IS_FLOATING:1;       
      unsigned IS_VERTICAL:1;       
      unsigned HAS_ORIENT:1;        // A REVOIR @@@@ !!!!.
      unsigned HAS_CURSOR:1;        
      unsigned HAS_LAYOUT:1;        
      unsigned HAS_TIP:1;           
      unsigned DONT_CLOSE_MENUS:1;
      unsigned OBSERVE_EVENTS:1;
      unsigned IGNORE_EVENTS:1;    
      enum {
        CATCH_MOUSE_MASK = 1<<0, CATCH_MOUSE_MOVE_MASK = 1<<1, 
        CATCH_WHEEL_MASK = 1<<2, CATCH_KEY_MASK = 1<<3
      };
      unsigned CATCH_EVENTS:4;  
    };
    
    enum {REMOVE_FROM_PARENTS = -1};
    
    bool isBrowsingGroup() {return emodes.IS_BROWSABLE;}       // !!!
    //virtual UElem* getBrowsingGroup() {return emodes.IS_BROWSABLE ? this : null;} 
    
    //UElem& setConst() {UObject::setConst(); return *this;} // redefined from UObject.
    
    virtual UChildren& children() const {return _children;}
    /*[impl] return the child list.
     * @see: child(), getChild(), cbegin(), cend(), crbegin(), crend(), attributes().
     */
    
    virtual UChildren& attributes() const {return _attributes;}
    /*[impl] returns the attribute list.
     * @see: abegin(), aend(), children().
     */
    
    UChildIter abegin() const {return attributes().begin();}
    /*[impl] returns an iterator to the beginning the ATTRIBUTE list.
     * works in the same was as cbegin() cend() for the CHILD list.
     * @see: aend(), attributes()
     */
    
    UChildIter aend() const {return attributes().end();}
    //[impl] returns an iterator to the end of the attribute list (@see abegin()).
    
    UObject::State getInterState() const {return ostate;}
    //[impl] returns the internal interactive state.
    
    void setInterState(UObject::State);
    //[impl] changes the internal interactive state.
    
    virtual const UStr* getTextSeparator() const;
    
    virtual void deleteViewsInside(const std::vector<UView*>& parent_views);
    
    virtual void initView(UView* parent_view);
    virtual void initChildViews(UElem*);
    virtual void highlight(bool state) {};
    
    virtual int retrieveRelatedViews(std::vector<UView*>& collating_vector) const;
    /* returns the views that are related to this element.
     * retrieves all the views where this element currently appears. This list is 
     * obtained  by collating the views of all the UBox parents of this element
     * (this may be indirect parents as this element may be a child of another element
     * that is a child of a UBox, and so on).
     *
     * - 'collating_vector' is not emptied: the views are added to the end of what
     *   it already contains.
     * - the function returns the number of views that were added (which may thus differ
     *   from the total size of 'collating_vector')
     *
     * Note that elements and boxes can have several parents, so that multiple wiews
     * can be associated to the same widget (see UElem and UBox classes for details)
     */
    
    UElem& _setArmableAndSelectable(bool state);
    
    /* [impl] behavioral functions.
     * these functions are called when the object receives the corresponding events.
     * Usually, these functions should not be redefined by clients. Instead, clients
     * should add UOn::xxx conditions that are called by these functions
     * @see class UOn.
     */
    
    virtual void keyPressBehavior(UKeyEvent&);
    virtual void keyReleaseBehavior(UKeyEvent&);
    virtual void enterBehavior(UInputEvent&, bool is_browing);
    virtual void leaveBehavior(UInputEvent&, bool is_browing);
    virtual void armBehavior(UInputEvent&, bool is_browing);
    virtual void disarmBehavior(UInputEvent&, bool is_browing);
    virtual void actionBehavior(UInputEvent&);
    
  protected:
    friend class UNode;
    friend class UEdit;
    friend class UChildEventFlag;  
    friend class UPos;
    friend class USize;
    friend class UOrient;
    friend class UCursor;
    friend class UTip;
    friend class UStr;
    friend class UWin;
    friend class UOn;
    friend class UEventFlow;
    friend class UViewStyle;
    friend class UUpdateContext;
    friend class UWinUpdateContext;
    //short istate; inherited from UObject
    mutable Modes emodes;
    long callback_mask;
    mutable UChildren _children;
    virtual int   _getTextLength(bool recursive) const;
    virtual char* _getTextData(char *ptr, bool recursive) const;
#endif
  };
  
  //typedef UElem UGroup; 
  //[Ubit5 compatibility] UGroup is an obsolete synonym for UElem.
  
  inline UElem& uelem(UArgs args = UArgs::none) {return *new UElem(args);}
  
  inline UElem& ugroup(UArgs args = UArgs::none) {return *new UElem(args);}
  
}
#endif