UI/UI_Object.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *
 *      Side Effects
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * NAME:        UI_Object.h
 *
 * COMMENTS:
 *      
 *  A UI_Object is the base class for objects that are organized in a
 *  hierarchy and are capable of receiving UI_Events.
 *
 */
#ifndef __UI_Object__
#define __UI_Object__

#include "UI_API.h"
#include "UI_EventType.h"

#include <UT/UT_Pointers.h>
#include <UT/UT_Assert.h>

class RE_Render;
class UT_String;
class UI_Event;
class UI_Manager;
class UI_Queue;
class UI_DeviceEvent;
class UI_Object;
class UI_Value;

//
// Turn the following define to 1 to perform proxy pointer referencing of
// objects.  Turn it to 0 to disable the proxy pointers.  Proxy pointers
// prevent UI_Values sending events to deleted objects (which shouldn't happen
// in real life)
//
#define UI_ENABLE_PROXY_POINTERS        1

typedef void (UI_Object::*UI_EventMethod)(UI_Event *);

class UI_API UI_Object
{
public:
    UI_Object();

    virtual ~UI_Object();

    virtual void      handleEvent(UI_Event *event);
    virtual int  interestingEvent(UI_EventType t, UI_DeviceEvent *event) const;
    virtual void deleteReferences(UI_Object *to_whom);

    UI_Object   *getParent() const              { return parent; }
    void         setParent(UI_Object *p)        { parent = p; }
    int          isAncestor(UI_Object *who) const;

    void           addDependent(UI_Object *who);
    int         removeDependent(UI_Object *who);
    int        replaceDependent(UI_Object *who, UI_Object *with);
    int             isDependent(UI_Object *who) const;
    UT_Pointers   *getDependents() const { return dependents; }

    //
    // If you know you're going to add a *lot* of dependents then
    // let us know beforehand so we can pre-allocate the array...
    //
    void        dependentCountHint(int count);

    void               sendEvent(const UI_Event &e, int purge=0) const;
    void         distributeEvent(UI_Event *event, int upwards);
    void              relayEvent(UI_Event *event, UI_Object *target);
    void           generateEvent(UI_EventType t,  UI_Object *target,
                                 int purge=0);
    void             purgeEvents(UI_EventType t,  UI_Object *target,
                                 UI_EventMethod method=0);

    virtual const char  *className() const;

#if UI_ENABLE_PROXY_POINTERS == 1
    int                  getProxyId();
#endif

    // A redraw priority of 0 is the highest and 1 is the lowest.
    int                  getRedrawPriority() const
                        { return myRedrawPriority; }
    void                 setRedrawPriority(int priority)
                        {
                            UT_ASSERT(priority >= 0 && priority <= 1);
                            myRedrawPriority = priority;
                        }


    void                 bumpQueueCount(int dir) { myQueueCount += dir; }


    // only works in debug.
    void                 setName(const char *symbolName);
    const char          *getName() const;
    void                 buildFullPath(UT_String &string) const;


    static UI_Manager   *getManager()    { return theUIManager; }
    static UI_Queue     *getInputQueue() { return theUIQueue; }

    static int           keycmp(const char *, int key);

    int                  getNumValueInterests();
    UI_Value            *getValueInterest(int i);


    // only UI_Value should call these methods.
    void                 interestedInValue(UI_Value *);
    void                 removeValueInterest(UI_Value *);

protected:
    // This is the function called by the UI_Manager at the start of a call
    // to terminate, but only if this object has been added to the UI_Manager
    // list of pre-terminate callbacks.
    virtual void         preTerminateCallback()
                         { }

    UT_Pointers         *dependents;
    UT_Pointers         *myValueInterests;
    UI_Object           *parent;
    int                  myRedrawPriority;
    int                  myQueueCount;
#if UI_ENABLE_PROXY_POINTERS == 1
    int                  myProxyId;
#endif
#if defined(UI_DEBUG_OBJECT_NAME)
    char                *myName;
#endif

private:
    friend class         UI_Manager;
    void                 setManager(UI_Manager *m, UI_Queue *q);

    static UI_Manager   *theUIManager;
    static UI_Queue     *theUIQueue;
};

#endif

---