cantext.h

Go to the documentation of this file.

/*! \file cantext.h
    \brief a2dText derived from a2dCanvasObject, holds multiline text 
    \author Klaas Holwerda, Erik van der Wal

    Copyright: 2000-2004 (c) Klaas Holwerda

    Licence: wxWidgets Licence

    RCS-ID: $Id: cantext.h,v 1.29 2009/07/16 20:06:33 titato Exp $
*/

#ifndef __WXCANTEXT_H__
#define __WXCANTEXT_H__

#include "wx/canvas/canobj.h"

/*! \defgroup textrelated Text related classes
*/

//! a2dText is an abstract base class.
/*! 
    The text is filled with a background if a2dFill != *a2dTRANSPARENT_FILL
    The fill colour is the Colour of the a2dFill.
    The a2dStroke colour is the colour used for the text itself.

    The text can be aligned, see SetAlignment() for info.
    \par User editing keys:
    
<TABLE border=0 cellpadding=0 cellspacing=0>
<tr><td colspan=2><br><b>Cursor movement</b></td></tr><br>
<tr><td colspan=2>Text selection can be done by pressing the Shift key, simultaneously with one of the following keys.<br></td></tr><br>

<TR><TD class="memItemLeft" nowrap>Cursor up/down</TD><TD class="memItemRight"> Move cursor one line up/down.</TD></TR>
<TR><TD class="memItemLeft" nowrap>Cursor Left / Ctrl + B</TD><TD class="memItemRight"> Move cursor one character to the left.</TD></TR>
<TR><TD class="memItemLeft" nowrap>Cursor Right / Ctrl + F</TD><TD class="memItemRight"> Move cursor one character to the right.</TD></TR>
<TR><TD class="memItemLeft" nowrap>Ctrl + Left / Alt + B</TD><TD class="memItemRight"> Move cursor to start of (previous) word.</TD></TR>
<TR><TD class="memItemLeft" nowrap>Ctrl + Right / Alt + F</TD><TD class="memItemRight"> Move cursor to start of next word.</TD></TR>
<TR><TD class="memItemLeft" nowrap>Home / Ctrl + A</TD><TD class="memItemRight"> Move to start of line</TD></TR>
<TR><TD class="memItemLeft" nowrap>End / Ctrl + E</TD><TD class="memItemRight"> Move to end of line</TD></TR>
<TR><TD class="memItemLeft" nowrap>Ctrl + N</TD><TD class="memItemRight"> Move to start of next line.</TD></TR>
<TR><TD class="memItemLeft" nowrap>Ctrl + P</TD><TD class="memItemRight"> Move to start of previous line.</TD></TR>
<TR><TD class="memItemLeft" nowrap>Ctrl + Home</TD><TD class="memItemRight"> Move to start of text.</TD></TR>
<TR><TD class="memItemLeft" nowrap>Ctrl + End</TD><TD class="memItemRight"> Move to end of text.</TD></TR>

<TR><TD colspan=2><br><b>Deletion</b></TD></TR><br>
<TR><TD colspan=2>If part of the text is selected, deleting it will take precedence over the following keys.<br></TD></TR><br>

<TR><TD class="memItemLeft" nowrap>Backspace / Ctrl + H</TD><TD class="memItemRight"> Delete previous character.</TD></TR><br>
<TR><TD class="memItemLeft" nowrap>Delete / Ctrl + D</TD><TD class="memItemRight"> Delete next character.</TD></TR><br>
<TR><TD class="memItemLeft" nowrap>Ctrl + Backspace / Ctrl + W</TD><TD class="memItemRight"> Delete to start of (previous) word.</TD></TR><br>
<TR><TD class="memItemLeft" nowrap>Ctrl + Delete / Alt + D</TD><TD class="memItemRight"> Delete to start of next word.</TD></TR><br>
<TR><TD class="memItemLeft" nowrap>Ctrl + K</TD><TD class="memItemRight"> Delete to end of line.</TD></TR><br>
<TR><TD class="memItemLeft" nowrap>Ctrl + U</TD><TD class="memItemRight"> Delete current line</TD></TR><br>

<TR><TD colspan=2><br><b>Clipboard<br></b></TD></TR><br>

<TR><TD class="memItemLeft" nowrap>Ctrl + C / Ctrl + Insert</TD><TD class="memItemRight"> Copy text to clipboard.</TD></TR><br>
<TR><TD class="memItemLeft" nowrap>Ctrl + V / Shift + Insert</TD><TD class="memItemRight"> Paste text from clipboard.</TD></TR><br>
<TR><TD class="memItemLeft" nowrap>Ctrl + X / Shift + Delete</TD><TD class="memItemRight"> Cut text to clipboard.</TD></TR><br>

<TR><TD colspan=2><br><b>Text alignment</b></TD></TR><br>
<TR><TD colspan=2>Num lock should be on to use these keys.<br></TD></TR><br>

<TR><TD class="memItemLeft" nowrap>Ctrl + Keypad 1..9</TD><TD class="memItemRight"> Align the text to a different direction.</TD></TR><br>
<TR><TD class="memItemLeft" nowrap>Ctrl + Keypad 0</TD><TD class="memItemRight"> Toggle between bounding box and text alignment.</TD></TR><br>

</TABLE>

    \bug EW: Solve behaviour when having a stretched affine matrix. Actually this bug is caused by
             the drawing of the text (which cannot be stretched). Maybe even prevent stretching. 
    \todo EW: How should up-down key react with reversed y-axis? 
    \todo EW: Undo while text editing?

    Proper constructors for several cases.
    \code
        a2dText( text, x, y, a2dFont( fontfile, size ) );

        a2dText( text, x, y, a2dFont( wxfont, size, alignment), angle, up );


        a2dText( text, x, y, a2dFont( wxfont, size, alignment), 0.0, up );

        text->SetFont( a2dFont( wxfont, text->GetTextHeight(), text->GetAlignment() ) );
        
        text->SetFont( a2dFont( wxfont, size, text->GetAlignment() ) );
    \endcode

    \ingroup canvasobject
    \ingroup textrelated
*/

class A2DCANVASDLLEXP a2dText: public a2dCanvasObject
{
public:
    enum a2dTextFlags
    {
        //! Allows multiple lines of text
        a2dCANOBJTEXT_MULTILINE = 1 << 1,
        //! Todo: The text will not be user-editable, but is selectable
        a2dCANOBJTEXT_READONLY = 1 << 2,
        //! show the caret
        a2dCANOBJTEXT_CARETVISIBLE = 1 << 3,
        //! next line is higher in Y if set
        a2dCANOBJTEXT_NEXTLINEUP = 1 << 4,
        //! Text is always readible from the bottom right.
        a2dCANOBJTEXT_ENGINEERING = 1 << 5,
        //! disable background drawing
        a2dCANOBJTEXT_BACKGROUND = 1 << 6,
        //! allow draw a frame rect around a text
        a2dCANOBJTEXT_FRAME      = 1 << 7,
        a2dCANVASTEXT_DEFAULTFLAGS = a2dCANOBJTEXT_MULTILINE
                | a2dCANOBJTEXT_CARETVISIBLE
                | a2dCANOBJTEXT_NEXTLINEUP
    };    

public:
    A2D_DECLARE_EVENT_TABLE()
    DECLARE_DYNAMIC_CLASS(a2dText)

    //! constructor
    /*!
        create text object at (0,0) text is set to "not specified" if not given 
    */
    a2dText( const wxString &text = wxT("not specified"));

    //! constructor
    /*!
        \param text text to display
        \param x x start
        \param y y start
        \param font a2dFont to use
        \param angle angle in degrees
        \param up if true next line is higher in Y else lower
        \param alignment Alignment of the text. (See SetAlignment)
    */
    a2dText( const wxString &text, double x, double y, 
            const a2dFont& font = *a2dDEFAULT_CANVASFONT, double angle = 0.0, 
            bool up = false, int alignment = a2dDEFAULT_ALIGNMENT );

protected:
    //! copy constructor
    a2dText( const a2dText &other, CloneOptions options );

public:
    //! Destructor
    ~a2dText();

    //! Clone this object and return a pointer to the new object. 
    virtual a2dObject* Clone( CloneOptions options ) const
        { return new a2dText( *this, options ); }

public:

    //! get the number of lines in the text
    int GetLines() const;

    //! get lines into array, return number of lines
    int GetAsArray( wxArrayString& array );

    //! get the number of lines in the text
    wxString GetLine(int line) const;

    //! set the text for the object '\n' in string means new line
    inline void SetText( const wxString& text )
        { m_text = text; m_utbbox_changed = true; SetPending(true); }
    //! get the text of the object '\n' in string means new line
    inline wxString GetText() const { return m_text; }

    //! set text height in world coordinates
    inline void SetTextHeight( double height )
        { m_font.SetSize(height); m_utbbox_changed = true; SetPending(true); }
    //! get text height in world coordinates
    inline double GetTextHeight() const { return m_font.GetSize(); }

    //! Height in world coordinates of one line
    inline double GetLineHeight() const { return m_font.GetLineHeight(); }

    //! Set Space in world coordinates between two lines
    inline void SetLineSpacing( double linespace )
        { m_linespace = linespace; m_utbbox_changed = true; SetPending(true); }
    //! Get Space in world coordinates between two lines
    inline double GetLineSpacing() const { return m_linespace; }

    //! Set the text flags
    inline void SetTextFlags( unsigned int textflags ) { m_textflags = textflags; m_utbbox_changed = true; }
    //! Get the text flags
    inline unsigned int GetTextFlags() const { return m_textflags; }
        
    //! Set if multiple lines of text are allowed.
    void SetMultiLine(bool multiline = true);
    //! True if multiple lines of text are allowed.
    inline bool GetMultiLine() const
        { return (m_textflags & a2dCANOBJTEXT_MULTILINE) != 0; }

    //! Set if text is readonly
    void SetReadOnly(bool readonly = true);
    //! True if text is readonly.
    inline bool GetReadOnly()
        { return (m_textflags & a2dCANOBJTEXT_READONLY) != 0; }

    //! next line is higher in Y if true or lower if false
    void SetNextLineDirection( bool up );
    //! next line is higher in Y if true or lower if false
    inline bool GetNextLineDirection() const
        { return (m_textflags & a2dCANOBJTEXT_NEXTLINEUP) != 0; }

    //! Keep text readible from the bottom right.
    void SetEngineeringText( bool engineering = true );
    //! Is text always readible from the bottom right.
    inline bool GetEngineeringText() const
        { return ( m_textflags & a2dCANOBJTEXT_ENGINEERING ) != 0; }

    //! Set if a background will be drawn.
    /*!
        When a layer style is used with a non transparent fill, 
        overlapping text is disturbing in case background overlaps other text.
        By setting this flag false the background is set transparent, even if a private fill style is used.
        Of course one can set the object to use a transparent fill, but this takes memory.
    */
    void SetBackGround(bool background = true);
    //! \see SetBackGround()
    inline bool GetBackGround() const
        { return ( m_textflags & a2dCANOBJTEXT_BACKGROUND ) != 0; }

    //! Set if a frame rect will be drawn.
    /*!
        
    */
    void SetDrawFrame(bool frame = true);
    //! \see SetDrawFrame()
    inline bool GetDrawFrame() const
        { return ( m_textflags & a2dCANOBJTEXT_FRAME ) != 0; }

    //! set font for text
    /*! This class takes care of deleting the font
        \param font The font to set
        \param lineSpaceFactor The m_linespace will be set to font.GetSize() * lineSpaceFactor
    */
    void SetFont( const a2dFont& font, double lineSpaceFactor = 0.1 );
    //! get font for text
    /*! Returns a pointer to the current font. If you need a copy, use (a2dFont) GetFont()->Clone(flat_copy).
    */
    inline a2dFont GetFont() const { return m_font; }

    //! set position of caret (-1 means off)
    inline void SetCaret( int position )
        { m_caret = position; SetPending(true); }
    //! Get position of caret (-1 means off)
    inline int GetCaret() const { return m_caret; }

    //! Set caret to the character closest to the position
    /*! \param ic iterative context
        \param x (mouse pointer) x-coordinate in absolute world coordinates
        \param y (mouse pointer) y-coordinate in absolute world coordinates
        \return True if mouse-position was within this object
    */
    bool SetCaret( a2dIterC& ic, double x, double y );

    //! set caret on or off
    void SetCaretShow( bool visible = true );
    //! return true if caret is visible
    inline bool GetCaretShow() const
        { return (m_textflags & a2dCANOBJTEXT_CARETVISIBLE) != 0; }

    //! Set the position of the anchor point w.r.t the text.
    /*! \param alignment sets the direction of the anchor point. The direction can be set like e.g.
        wxCENTRE, wxLEFT, wxMINX | wxMAXY. Another setting is wxBBOX, which sets the anchor point not
        at the corners of the actual text, but at the corrners of the bounding box of each line.
        Not specifying either a horizontal or vertical position will default to the centre. So only
        specifying wxLEFT corresponds to the middle-left position.
        <!-- view picture using monospaced font -->
        \code
                    wxCENTRE
                 +-----^-----+ wxBBOX|wxTOP
        wxTOP    +------#----+
                 |      #    |
        wxCENTER | #### #### |
                 |#   # #   #| wxBBOX|wxCENTER
        wxBOTTOM +-####-#---#+
                 |    #      |
                 | ###       |
                 +-----v-----+ wxBBOX|wxBOTTOM
              wxLEFT      wxRIGHT
        \endcode

        \remark
        - Although it seems more logical to position the text w.r.t the anchor point, this would leed
            to some non-intuitive situations, like using wxLEFT for right aligned text.  
        - The types wxMINY and wxMAXY are created, because the definition of top and bottom
          are unknown because the orientation of the y-axis is only known to views and not to the
          component itself. To be consistent, wxMINX and wxMAXX are created as well.
    */
    inline void SetAlignment(int alignment)
        { if(m_alignment != alignment) {
            m_alignment = alignment; m_utbbox_changed = true; SetPending(true); } }
    //! Get the position of the anchor point w.r.t the text
    /*! \return The alignment setting.
    */
    inline int GetAlignment() const
        { return m_alignment; }

    bool GeneratePins( a2dPinClass* toConnectTo, a2dConnectTask task, double x, double y );

    bool AdjustPinLocation(); 

    //! return text as a vector path, where text outline is converted to polyline or polygons.
    a2dCanvasObjectList* GetAsCanvasVpaths( bool transform = true );

#if wxART2D_USE_CVGIO
    //! Write object specific CVG data 
    virtual void DoSave( wxObject* parent, a2dIOHandlerXmlSerOut &out, a2dXmlSer_flag xmlparts , a2dObjectList* towrite );

    //! Load object specific CVG data 
    void DoLoad( wxObject* parent, a2dIOHandlerXmlSerIn& parser, a2dXmlSer_flag xmlparts );
#endif //wxART2D_USE_CVGIO

    static a2dPropertyIdFont* PROPID_Font;

    DECLARE_PROPERTIES()

protected:

    bool DoUpdate( UpdateMode mode, const a2dBoundingBox& childbox, const a2dBoundingBox& clipbox, const a2dBoundingBox& propbox );

    //! Render derived object 
    virtual void DoRender( a2dIterC& ic, OVERLAP clipparent );

    virtual bool DoIsHitWorld( a2dIterC& ic, a2dHitEvent& hitEvent );

    //! Get boundingbox without the affine matrix transform included. 
    /*! \return The boundingbox.
    */
    virtual a2dBoundingBox DoGetUnTransformedBbox( a2dBboxFlags flags = a2dCANOBJ_BBOX_NON ) const;

    //! Set caret to the character closest to the position
    /*!
        \param xh (mouse pointer) x-coordinate in world coordinates
        \param yh (mouse pointer) y-coordinate in world coordinates
    */
    void SetCaretUntransformed( double xh, double yh );

    //! Calculate a new affine, so text is always readible from the bottom right.
    a2dAffineMatrix GetEngineeringTransform( a2dIterC& ic );

    virtual bool DoStartEdit( wxUint16 editmode, wxEditStyle editstyle );

    virtual void DoEndEdit();

    void OnChar(wxKeyEvent& event);

    void OnCanvasObjectMouseEvent( a2dCanvasObjectMouseEvent& event );

    void OnHandleEvent(a2dHandleMouseEvent &event);

    const a2dFont& MX_GetFont() const { return m_font; }
    void MX_SetFont( const a2dFont& value ) { m_font = value; }

    //! font
    a2dFont m_font;

    //! space between the lines
    double   m_linespace;

    //! the text to display
    wxString m_text;

    //! contains several text flags.
    unsigned int m_textflags;
    
    //! position of caret within text string
    int m_caret;

    //! X position of caret in world coordinate in line
    double m_XcaretinLine;

    //! Y position of caret in world coordinate in line
    double m_YcaretinLine;

    //! Untransformed bounding box.
    mutable a2dBoundingBox m_untransbbox;

    //! Untransformed bounding box changed
    mutable bool m_utbbox_changed;

    //! Selection starting position
    size_t m_selection_start_pos;
    //! Selection end position
    size_t m_selection_end_pos;

    //! The first editable character, usually 0, but may be different for a2dVisibleProperty
    size_t m_firsteditable;

    //! Alignment.
    int m_alignment;

private:
    //!this is a not implemented copy constructor that avoids automatic creation of one
    a2dText( const a2dText &other );
};

#if defined(WXART2D_USINGDLL)
template class A2DCANVASDLLEXP a2dSmrtPtr<a2dText>;
#endif

#endif /* __WXCANTEXT_H__ */

cantext.h Source File -- Tue Aug 31 17:56:23 2010 -- 31 Aug 2010 -- 1.5.5 -- wxArt2D -- . -- Reference Documentation