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

#ifndef __UN_StickyNoteData_h__
#define __UN_StickyNoteData_h__

#include "UN_API.h"
#include "UN_Data.h"
#include "UN_Utils.h"
class UN_GraphData;


// ============================================================================
using UN_CustomStickyNoteData = 
            UN_CustomDataT< UN_StickyNoteID, UN_StickyNoteIndex >;
using UN_CustomStickyNoteDataPtr = UT_UniquePtr< UN_CustomStickyNoteData >;

// ============================================================================
/// Container of data for all the sticky notes in the graph.
/// 
/// NOTE: This class is generally not trivially relocatable, because 
/// its base class (UN_Data) is not trivially relocatable (see comment there).

class UN_API UN_StickyNoteData : public UN_Data
{
public:
    /// Constructors and destructors.
     UN_StickyNoteData( UN_CustomStickyNoteDataPtr custom_data 
             = UN_CustomStickyNoteDataPtr() );
    ~UN_StickyNoteData() = default;

                        UN_StickyNoteData(UN_StickyNoteData &&);
    UN_StickyNoteData & operator=(UN_StickyNoteData &&);

protected:
    /// This container can have large data, so generally, forbid 
    /// the costly copy operations to the public.
    /// Knowledgable friends and derived classes can still use them.
    friend UN_GraphData;
                        UN_StickyNoteData(const UN_StickyNoteData &) = default;
    UN_StickyNoteData & operator=(const UN_StickyNoteData &)   = default;

public:
    /// Increases the capacity of the data buffer arrays to the given minimum,
    /// unless the capacity is already greater or equal to that minimum,
    /// in which case the capacity remains unchanged.
    void                setCapacityIfNeeded( UN_DataSize min_capacity );

    /// @{ Returns sticky notes's custom data container, 
    /// if one was provided to c-tor.
    UN_CustomStickyNoteData *       customStickyNoteData()
    { 
        return UTverify_cast<UN_CustomStickyNoteData*>( customData() );
    }

    const UN_CustomStickyNoteData * customStickyNoteData() const
    { 
        return UTverify_cast<const UN_CustomStickyNoteData*>( customData() ); 
    }
    /// @}
    
    /// Merges another sticky data data container into this one.
    /// Returns a mapping between the sticky data IDs in the merge source 
    /// and destination (this) data buffers.
    UN_StickyNoteIDRemap merge( const UN_StickyNoteData &src_sticky_note_data );

    /// Adds a slot for a new sticky note in this container.
    /// Returns an ID that should be used to refer to this new sticky note
    /// for accessing its data (eg, source port, destination port, etc).
    UN_StickyNoteID     addStickyNote();

    /// Clears the data for the given sticky note to the default state.
    void                clearStickyNote(UN_StickyNoteID sticky_note_id );

    /// Removes the sticky note from this container and frees the
    /// data slot it occupied. After calling this method, 
    /// the container will have no knowledge of the sticky note by this ID.
    /// Returns true on successs; false if the sticky note was not found.
    bool                removeStickyNote( UN_StickyNoteID sticky_note_id );

    /// Frees the data slots occupied by all the sticky notes.
    /// @param 'reset_next_id' If true, the sticky note ID generator is reset to zero.
    void                removeAllStickyNotes( bool reset_next_id );

    /// Returns true if the given ID refers to a valid sticky note entry 
    /// in the data buffers. Ie, such a sticky note exists and is valid.
    bool                isValid( UN_StickyNoteID sticky_note_id ) const
                            { return UN_Data::isValid( sticky_note_id ); }


    /// Iterator for traversing valid sticky note IDs.
    class IDIterator : public UN_DataIndexMap::IDIterator
    {
    public:
        using value_type = UN_StickyNoteID;

        IDIterator( const UN_DataIndexMap::IDIterator &id_iterator )
            : UN_DataIndexMap::IDIterator( id_iterator )
        {}

        value_type operator*() const
        { return UN_StickyNoteID( UN_DataIndexMap::IDIterator::operator*() ); }
    };

    /// Iterator for traversing valid sticky note IDs in an ascending order.
    class OrderedIDIterator : public UN_DataIndexMap::OrderedIDIterator
    {
    public:
        using value_type = UN_StickyNoteID;

        OrderedIDIterator(const UN_DataIndexMap::OrderedIDIterator &id_iterator)
            : UN_DataIndexMap::OrderedIDIterator( id_iterator )
        {}

        value_type operator*() const
        { return UN_StickyNoteID( 
                UN_DataIndexMap::OrderedIDIterator::operator*() ); }
    };


    /// Returns a range for iterating valid sticky note IDs. 
    using IDRange = UT_IteratorRange< IDIterator >;
    IDRange idRange() const
    {
        auto id_range( UN_Data::idRange() );
        return IDRange( id_range.begin(), id_range.end() );
    }

    /// Returns a range for iterating valid sticky note IDs. 
    using OrderedIDRange = UT_IteratorRange< OrderedIDIterator >;
    OrderedIDRange orderedIDRange() const
    {
        auto id_range( UN_Data::orderedIDRange() );
        return OrderedIDRange( id_range.begin(), id_range.end() );
    }

    /// Returns a list of all the valid sticky note IDs in the graph.
    UN_StickyNoteIDList stickyNoteIDs() const
    {
        SYS_STATIC_ASSERT( sizeof(UN_StickyNoteID) == sizeof(UN_DataID) );
        return reinterpret_cast<UN_StickyNoteIDList&&>( std::move( dataIDs() ));
    }

    /// Returns a list of all the valid sticky note IDs in the graph.
    UN_StickyNoteIDList sortedStickyNoteIDs() const
    {
        SYS_STATIC_ASSERT( sizeof(UN_StickyNoteID) == sizeof(UN_DataID) );
        return reinterpret_cast<UN_StickyNoteIDList&&>( 
                std::move(sortedDataIDs() ));
    }

protected:
    /// Sets the sticky note name that differentiates it among its siblings. 
    // Only the friend UN_GraphData can call it because it may need to
    // enforce a unique name.
    void setName( UN_StickyNoteID note_id, const UT_StringRef &name )
    {
        UT_ASSERT( !myCheckValidNames 
                || UN_Utils::isValidGraphItemName( name, myNameSafeChars ));
        setData( myName, note_id, name );
    }

public:
    /// Returns the name that identifies the sticky notes among its siblings.
    const UT_StringHolder & name( UN_StickyNoteID note_id ) const
    {
        return getDataRef( myName, note_id, UT_StringHolder::theEmptyString );
    }

    /// Sets the sticky note's contents text.
    void setText( UN_StickyNoteID note_id, const UT_StringRef &text )
    {
        setData( myText, note_id, text );
    }

    /// Returns the sticky note's contents.
    const UT_StringHolder & text( UN_StickyNoteID note_id ) const
    {
        return getDataRef( myText, note_id, theDefText );
    }

    /// Sets the sticky note's location in the graph editor.
    void setPosition( UN_StickyNoteID note_id, const UT_Vector2D &position )
    {
        setData( myPosition, note_id, position );
    }

    /// Returns the sticky note's position in the graph editor.
    const UT_Vector2D & position( UN_StickyNoteID note_id ) const
    {
        return getDataRef( myPosition, note_id, theDefPos );
    }

    /// Sets the sticky note's width and height.
    void setDimensions( UN_StickyNoteID note_id, const UT_Vector2D &dimensions )
    {
        setData( myDimensions, note_id, dimensions );
    }

    /// Returns the sticky note's dimensions (width & height).
    const UT_Vector2D & dimensions( UN_StickyNoteID note_id ) const
    {
        return getDataRef( myDimensions, note_id, theDefDim );
    }
    
    /// Sets the sticky notes's background color in the graph editor.
    void setColor( UN_StickyNoteID note_id, const UT_Color &color )
    {
        setData( myColor, note_id, color );
    }

    /// Returns the sticky note's background color in the graph editor.
    const UT_Color & color( UN_StickyNoteID note_id ) const
    {
        return getDataRef( myColor, note_id, theDefColor );
    }

    /// Sets the sticky notes's text (foreground) color in the graph editor.
    void setTextColor( UN_StickyNoteID note_id, const UT_Color &text_color )
    {
        setData( myTextColor, note_id, text_color );
    }

    /// Returns the sticky note's text (foreground) color in the graph editor.
    const UT_Color & textColor( UN_StickyNoteID note_id ) const
    {
        return getDataRef( myTextColor, note_id, theDefTextColor );
    }

    /// Sets the sticky note's text size.
    void setTextSize( UN_StickyNoteID note_id, float text_size )
    {
        setData( myTextSize, note_id, text_size );
    }

    /// Returns the sticky note's text size.
    float textSize( UN_StickyNoteID note_id ) const
    {
        return getDataRef( myTextSize, note_id, theDefTextSize );
    }

    /// Sets the sticky note's collapsed (minimized) state.
    void setCollapsed( UN_StickyNoteID note_id, bool is_collapsed )
    {
        setData( myIsCollapsed, note_id, is_collapsed );
    }

    /// Returns true if the sticky note is collapsed (minimized).
    bool isCollapsed( UN_StickyNoteID note_id ) const
    {
        return getDataVal( myIsCollapsed, note_id, theDefCollapsed );
    }

    /// Sets the flag on the sticky note to avoid drawing its background,
    /// effectively making it transparent.
    void setBackgroundHidden( UN_StickyNoteID note_id, bool is_hidden )
    {
        setData( myIsBackgroundHidden, note_id, is_hidden );
    }

    /// Returns true if the background of the sticky note is not drawn,
    /// effectively making it transparent.
    bool isBackgroundHidden( UN_StickyNoteID note_id ) const
    {
        return getDataVal( myIsBackgroundHidden, note_id, 
                theDefBackgroundHidden);
    }


    /// Asserts that the sticky note names are alphanumeric.
    void setCheckValidStickyNoteNames( bool flag )
    {
        myCheckValidNames = flag; 
    }

    /// A set of additional characters that are legal in sticky note names.
    void setStickyNoteNameSafeChars( const UT_StringRef &safe_chars )
    {
        myNameSafeChars = safe_chars; 
    }

protected:
    /// Returns the sticky note's data index into the data buffer arrays.
    UN_StickyNoteIndex  stickyNoteIndex( UN_StickyNoteID id ) const
                            {
                                return UN_StickyNoteIndex( 
                                        UN_Data::dataIndex( id ));
                            }

private:
    /// Returns the current size of the internals data buffers.
    /// The number of valid entries (slots) in data buffers is less than
    /// or equal to that number, since some data slots may be free.
    UN_DataSize coreDataBufferSize() const
    {
        UN_DataSize size( myName.size() );
        UT_ASSERT( isCoreDataSizeConsistent( size ));
        return size;
    }

    /// Handles merging of another sticky note data container into this one.
    void        mergeCoreData( const UN_StickyNoteData &src,
                               const UN_DataMergeInfo &merge_info );

    /// Adds a new data slot to accommodate a new data piece at the given index.
    void        addCoreData( UN_StickyNoteIndex sticky_note_index );

    /// Clears the data for the given sticky note to the default state.
    void        clearCoreData( UN_StickyNoteIndex sticky_note_index );

    /// Frees the data slot occupied by the given sticky note,
    /// clearing it if necessary.
    void        removeCoreData() //, index)
                    // Nothing urgent to free; will clear lazily
                    { UT_ASSERT( isDataSizeConsistent() ); }

    /// Frees all the data slots.
    void        removeAllCoreData();

    /// Sets the capacity of core data buffers if needed.
    void        setCoreDataCapacityIfNeeded( UN_DataSize min_capacity );

    /// @{ Returns true if the sizes of all core data buffers are equal.
    bool        isCoreDataSizeConsistent( UN_DataSize expected_size ) const;
    bool        isCoreDataSizeConsistent() const
                    { return isCoreDataSizeConsistent( myName.size() ); }
    /// @}

    /// Returns true if the sizes of data buffers and index map are equal.
    bool        isDataSizeConsistent() const;

public:
    // The default values for the UN sticky note data.
    static inline const UT_StringHolder    theDefText;
    static inline const auto theDefPos   = UT_Vector2D(0.0);
    static inline const auto theDefDim   = UT_Vector2D(2.5);
    static inline const auto theDefColor = 
                                UT_Color(UT_RGB, 1.000F, 0.969F, 0.522F);
    static inline const auto theDefTextColor = UT_BLACK;
    static inline const auto theDefTextSize  = 0.0F;
    static inline const auto theDefCollapsed = false;
    static inline const auto theDefBackgroundHidden = false;

private: 
    /// The name of the sticky note, to identify it in a subnet.
    UN_StringDataBuffer         myName;

    /// The contents of the sticky note.
    UN_StringDataBuffer         myText;

    /// The location of the sticky note in the graph.
    UN_Vector2DDataBuffer       myPosition;

    /// The width and height of the sticky note in the graph.
    UN_Vector2DDataBuffer       myDimensions;

    /// Sticky note's (backgroun) color.
    UN_ColorDataBuffer          myColor;

    /// Sticky note's text color.
    UN_ColorDataBuffer          myTextColor;

    /// Sticky note's text size.
    UN_FloatDataBuffer          myTextSize;

    /// Collapsed (minimized) flag.
    UN_BoolDataBuffer           myIsCollapsed;

    /// Indicates that the background is not rendered.
    UN_BoolDataBuffer           myIsBackgroundHidden;


    /// Extra characters that are legal in the sticky note names,
    /// in addition to the standard C-var style alphanumerics.
    UT_StringHolder             myNameSafeChars;

    /// Check an assertion that the sticky note names are alphanumeric.
    bool                        myCheckValidNames = false;
};


#endif