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.
 *
 * 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_Assert.h>
#include <UT/UT_UniquePtr.h>
#include <hboost/container/stable_vector.hpp>


class UT_WorkBuffer;
class UI_Event;
class UI_Manager;
class UI_Queue;
class UI_DeviceEvent;
class UI_Object;
class UI_Value;
class UI_KeyDelegate;
class UI_HotkeyEcho;


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

// stable_vector is a hybrid of list and vector; giving random access and
// stable iterators upon insert/erase (except for an element pointed to), 
// albeit with the loss of contiguity.
typedef hboost::container::stable_vector<UI_Object *> UI_ObjectList;
typedef hboost::container::stable_vector<UI_Value *> UI_ValueList;
typedef hboost::container::stable_vector<UI_KeyDelegate *> UI_KeyDelegateList;

class UI_API UI_Object
{
public:
    UI_Object();

    virtual ~UI_Object();

    // !!! WARNING: Do NOT derive from UT_NonCopyable due to Visual C++ bug !!!
    // !!! Otherwise Visual C++ will start causing subclass callback member
    // !!! method pointers (of single inheritance chains) to become larger than
    // !!! UI_EventMethod.
    UI_Object(const UI_Object &) = delete;
    UI_Object &operator=(const UI_Object &) = delete;
    // !!! WARNING: Do NOT derive from UT_NonCopyable due to Visual C++ bug !!!

    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 myParent; }
    void                 setParent(UI_Object *p)        { myParent = p; }
    bool                 isAncestor(const UI_Object *who) const;

    void                 addDependent(UI_Object *who);
    bool                 removeDependent(UI_Object *who);
    bool                 replaceDependent(UI_Object *who, UI_Object *with);
    bool                 isDependent(UI_Object *who) const;
    bool                 hasDependents() const { return !myDependents.empty(); }
    const UI_ObjectList &dependents() const { return myDependents; }

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

    // This method is similar to "distributeEvent()" but it bypasses the event
    // queue, triggering the events on the dependents immediately.
    // **This should only be used in special circumstances.**
    void                 triggerImmediateEvent(UI_Event *event, int upwards);

    virtual const char  *className() const { return "UI_Object"; }

    int                  getProxyId();

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


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

    // Debug events which target this UI_Object coming in from given UI_Value.
    // You must also enable the define UI_QUEUE_DEBUG_TARGET_ORIGIN in
    // UI_Queue.C in order to use this method. The type is optional; if
    // specified, only events of that type are monitored.
    // Either object or value (or both) can be specified.
    void                 debugQueueEventsFor(
                            const UI_Value *value,
                            const char *name, 
                            UI_EventType t = UI_EVENT_NO_EVENT) const;


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

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

    static void          keyEcho(const char *, const UI_HotkeyEcho &);
    static void          actionKeyEcho(const char *,
                                       const char *custom_suffix = 0);
    static void          toggleKeyEcho(const char *, bool new_value);

    const UI_ValueList  &valueInterests() const { return myValueInterests; }


    // Only UI_Value should call these methods.
    // DO NOT MAKE THESE VIRTUAL!
    void                 interestedInValue(UI_Value *);
    void                 removeValueInterest(UI_Value *);

    // Only UI_KeyDelegate should call these methods.
    // DO NOT MAKE THESE VIRTUAL!
    void                 addKeyDelegateClientship(UI_KeyDelegate *);
    void                 removeKeyDelegateClientship(UI_KeyDelegate *);

protected:
    UI_ObjectList       &dependents() { return myDependents; }

    // 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()
                         { }

private:
    UI_Object           *myParent;
    UI_ObjectList        myDependents;
    UI_ValueList         myValueInterests;
    UT_UniquePtr<UI_KeyDelegateList>
                         myKeyDelegateClientships;
    int                  myQueueCount;
    int                  myProxyId;
    char                *myName;

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

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

#endif