UN_StickyNote.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:        UN_StickyNote.h ( UN Library, C++)
 *
 * COMMENTS:
 *      
 */

#ifndef __UN_StickyNote_h__
#define __UN_StickyNote_h__

#include "UN_API.h"
#include "UN_Handle.h"
#include "UN_Port.h"
#include "UN_StickyNoteUtils.h"

class UN_ConstGraph;
class UN_Graph;


// ============================================================================
/// Base class template for the UN sticky note handle.
/// Its main purpose is to factor common code for const and non-const handles.
template <typename BASE_CLASS,  // class to derive from
          typename GRAPH_DATA>  // UN_GraphData or const UN_GraphData
class UN_StickyNoteBase : public BASE_CLASS
{
protected:
    /// Constructs a handle for an invalid sticky note.
    UN_StickyNoteBase() = default;

    /// Constructs a handle that references the given sticky note in the given graph.
    UN_StickyNoteBase( GRAPH_DATA *graph_data, UN_StickyNoteID note_id )
        : BASE_CLASS( graph_data, note_id ) 
        {}

public:
    /// @{ Returns the owner of the underlying graph data structures.
    GRAPH_DATA *        graphData() const
                            { return BASE_CLASS::graphData(); }
    const UN_GraphData *constGraphData() const
                            { return BASE_CLASS::constGraphData(); }
    /// @}

    /// Returns the unique ID of the sticky note this handle refers to.
    UN_StickyNoteID     stickyNoteID() const
                            { return UN_StickyNoteID( BASE_CLASS::dataID() ); }

    /// @{ Returns true if this note is valid within the graph; false otherwise.
    bool                isValid() const
                            { return UN_StickyNoteUtils::isValid( 
                                        graphData(), stickyNoteID()); 
                            }

    explicit operator   bool() const
                            { return isValid(); }
    /// @}
    
    /// Returns the sticky note name that differentiates it among its siblings. 
    const UT_StringHolder & name() const
    { 
        return UN_StickyNoteUtils::name( graphData(), stickyNoteID() );
    }

    /// Returns the sticky note's contents.
    const UT_StringHolder & text() const
    { 
        return UN_StickyNoteUtils::text( graphData(), stickyNoteID() );
    }

    /// Returns the sticky note's position in the graph editor.
    const UT_Vector2D & position() const
    { 
        return UN_StickyNoteUtils::position( graphData(), stickyNoteID() );
    }

    /// Returns the sticky note's dimensions (width & height).
    const UT_Vector2D & dimensions() const
    { 
        return UN_StickyNoteUtils::dimensions( graphData(), stickyNoteID() );
    }

    /// Returns the sticky note's (background) color.
    const UT_Color & color() const
    { 
        return UN_StickyNoteUtils::color( graphData(), stickyNoteID() );
    }

    /// Returns the sticky note's text (foreground) color.
    const UT_Color & textColor() const
    { 
        return UN_StickyNoteUtils::textColor( graphData(), stickyNoteID() );
    }

    /// Returns the sticky note's text size.
    float textSize() const
    { 
        return UN_StickyNoteUtils::textSize( graphData(), stickyNoteID() );
    }

    /// Returns true if the sticky note is collapsed (minimized).
    bool isCollapsed() const
    { 
        return UN_StickyNoteUtils::isCollapsed( graphData(), stickyNoteID() );
    }

    /// Returns true if the background of the sticky note is not drawn,
    /// effectively making it transparent.
    bool isBackgroundHidden() const
    { 
        return UN_StickyNoteUtils::isBackgroundHidden( graphData(), 
                stickyNoteID() );
    }
};

// ============================================================================
/// A handle that references a mutable sitkcy note in a graph.
/// It abstracts the APIs that operate on this sitkcy note's data stored inside 
/// graph's data containers.
/// It is a non-const (read-write) handle, so allows both queries 
/// and mutations of the sitkcy note's data.
class UN_API UN_StickyNote : public UN_StickyNoteBase< UN_Handle, UN_GraphData >
{
public:
    /// Constructs a handle for an invalid sitkcy note.
    UN_StickyNote() = default;

    /// Constructs a handle referencing the given note in the given graph.
    UN_StickyNote( UN_GraphData *graph_data, UN_StickyNoteID note_id )
        : UN_StickyNoteBase( graph_data, note_id ) 
    {}

    /// @{ Comparison operators.  
    // Allows comparing sticky note handles, but guards against 
    // comparing sticky note to ports, for example.
    bool    operator==( const UN_StickyNote &other ) const
                { return UN_ConstHandle::operator==( other ); }
    bool    operator!=( const UN_StickyNote &other ) const
                { return UN_ConstHandle::operator!=( other ); }
    /// @}
    
    /// Returns the graph whithin which this sticky note exists.
    UN_Graph graph() const;

    /// Sets the sticky note name that differentiates it among its siblings. 
    void setName( const UT_StringRef &name ) const
    { 
        UN_StickyNoteUtils::setName( graphData(), stickyNoteID(), name );
    }

    /// Sets the sticky note's type that determines its functional behavour.
    void setText( const UT_StringRef &type_name ) const
    { 
        UN_StickyNoteUtils::setText( graphData(), stickyNoteID(), type_name );
    }

    /// Sets the sticky note's location in the graph editor.
    void setPosition( const UT_Vector2R &position ) const
    { 
        UN_StickyNoteUtils::setPosition( graphData(), stickyNoteID(), 
                position );
    }

    /// Sets the sticky note's width and height.
    void setDimensions( const UT_Vector2R &dimensions ) const
    { 
        UN_StickyNoteUtils::setDimensions( graphData(), stickyNoteID(), 
                dimensions );
    }

    /// Sets the sticky note's (background) color.
    void setColor( const UT_Color &color ) const
    { 
        UN_StickyNoteUtils::setColor( graphData(), stickyNoteID(), color );
    }

    /// Sets the sticky note's text (foreground) color.
    void setTextColor( const UT_Color &color ) const
    { 
        UN_StickyNoteUtils::setTextColor( graphData(), stickyNoteID(), color );
    }

    /// Sets the sticky note's text size.
    void setTextSize( float text_size ) const
    {
        UN_StickyNoteUtils::setTextSize( graphData(), stickyNoteID(), 
                text_size );
    }

    /// Sets the sticky note's collapsed (minimized) state.
    void setCollapsed( bool is_collapsed ) const
    {
        UN_StickyNoteUtils::setCollapsed( graphData(), stickyNoteID(), 
                is_collapsed );
    }

    /// Sets the flag on the sticky note to avoid drawing its background,
    /// effectively making it transparent.
    void setBackgroundHidden( bool is_hidden ) const
    {
        UN_StickyNoteUtils::setBackgroundHidden( graphData(), stickyNoteID(), 
                is_hidden );
    }
};


// ============================================================================
/// A handle that references a const sticky note in a graph.
/// It abstracts the APIs that operate on this sticky note's data stored inside 
/// graph's data containers.
/// It is a constant handle, so allows only queries of the sticky note's data,
/// and does not allow setting any new values for.
class UN_API UN_ConstStickyNote : public UN_StickyNoteBase< UN_ConstHandle, 
    const UN_GraphData >
{
public:
    /// Constructs a handle for an invalid sticky note.
    UN_ConstStickyNote() = default;

    /// Constructs a handle referencing the given sticky note in the given graph.
    UN_ConstStickyNote( const UN_GraphData *graph_data, UN_StickyNoteID note_id )
        : UN_StickyNoteBase( graph_data, note_id ) 
    {}

    /// Constructs a const handle from a mutable sticky note handle.
    UN_ConstStickyNote( const UN_StickyNote &note )
        : UN_ConstStickyNote( note.constGraphData(), note.stickyNoteID() ) 
    {}

    /// @{ Comparison operators.  
    // Allows comparing sticky note handles, but guards against 
    // comparing notes to notes, for example.
    bool    operator==( const UN_ConstStickyNote &other ) const
                { return UN_ConstHandle::operator==( other ); }
    bool    operator!=( const UN_ConstStickyNote &other ) const
                { return UN_ConstHandle::operator!=( other ); }
    /// @}


    /// Returns the graph whithin which this sticky note exists.
    UN_ConstGraph graph() const;
};

// ============================================================================
// Free functions to compare a non-const sticky note handle to a const sticky
// note handle.
// Note, the const to non-const comparison is covered by implicit conversion
// of non-const handle to const handle, and using const to const handle comp.
static inline bool
operator==( const UN_StickyNote &a,  const UN_ConstStickyNote &b )
{
    return b == UN_ConstStickyNote(a);
}

static inline bool
operator!=( const UN_StickyNote &a,  const UN_ConstStickyNote &b )
{
    return !(b == a);
}

// ============================================================================
#endif