Hot Door CORE  0.7.0
Adobe® Illustrator® Plug-in Library
Public Types | Public Member Functions | Friends | List of all members
hdi::core::TextRange Class Reference

Allows for easy manipulation of Illustrator text ranges. More...

#include <hdicoreTextRange.h>

Public Types

enum  CollapseDirection { UnknownCollapseDir = 0, CollapseEndDir = 10, CollapseStartDir = 20 }
 
typedef std::vector< TextArt * > TextArtVector
 
typedef std::vector< TextPara * > TextParaVector
 
typedef std::vector< TextRange * > TextRangeVector
 
typedef std::vector< TextWord * > TextWordVector
 

Public Member Functions

 TextRange ()
 Creates a new TextRange object. More...
 
 TextRange (const TextRange &tr_)
 TextRange copy constructor. More...
 
virtual ~TextRange ()
 Destructs a TextRange object. More...
 
virtual TextRangeoperator= (const TextRange &rhs_)
 Overloaded assignment operator for TextRange objects. More...
 
virtual bool operator== (const TextRange &rhs_) const
 Tests whether a given TextRange object is the same as another. More...
 
virtual bool operator!= (const TextRange &rhs_) const
 Tests whether a given TextRange object is not the same as another. More...
 
virtual std::auto_ptr< ATE::ITextRange > ateTextRange () const
 Gets the ATE text range ref around which the target object is wrapped. More...
 
virtual bool isEmpty () const
 Gets whether the target TextRange object is empty. More...
 
virtual std::auto_ptr< TextRangeduplicate () const
 Duplicates the target text range, returning a new unique TextRange object. More...
 
virtual int32_t start () const
 Gets the start offset of the target text range. More...
 
virtual void setStart (const int32_t start_)
 Sets the start offset of the target text range. More...
 
virtual int32_t end () const
 Gets the end offset of the target text range. More...
 
virtual void setEnd (const int32_t end_)
 Sets the end offset of the target text range. More...
 
virtual int32_t size () const
 Retrieves the number of characters in the target text range. More...
 
virtual void setRange (const int32_t start_, const int32_t end_)
 Convenience method to set both the start and end points of the target text range. More...
 
virtual void collapse (const CollapseDirection dir_=CollapseEndDir)
 Resets start or end point of the target range so that it contains only one character, either the first or the last. More...
 
virtual int32_t move (const int32_t unit_)
 Moves the target text range by adding or subtracting a number of characters to or from the start and end offsets. More...
 
virtual std::auto_ptr< TextStorystory () const
 Retrieves the story that contains this text range. More...
 
virtual void setStory (const TextStory &story_)
 Sets the story that contains this text range. More...
 
virtual std::auto_ptr< TextRangeSetselections () const
 Retrieves the selected text within this text range. More...
 
virtual TextArtVector textFrames () const
 Gets a vector of the text frames contained in this text range. More...
 
virtual TextParaVector paragraphs () const
 Gets a vector of the paragraphs contained in this text range. More...
 
virtual TextWordVector words () const
 Gets a vector of the words contained in this text range. More...
 
virtual TextRangeVector runs () const
 Gets a vector of the text ranges (that share character attributes) contained in this text range. More...
 
virtual std::auto_ptr< TextCharInspectorcharInspector () const
 Creates an inspector with which to access the character features of all characters in the target text range. More...
 
virtual std::auto_ptr< TextParaInspectorparaInspector () const
 Creates an inspector with which to access the paragraph features of all paragraphs in the target text range. More...
 
virtual std::auto_ptr< TextCharStyleSetnamedCharStyles () const
 Retrieves a set of all named character styles used in the target text range. More...
 
virtual bool setNamedCharStyle (const std::string &name_)
 Associates a named character style to the target text range. The inherited values can be overridden by styles or features specified locally in contained text ranges or individual characters. More...
 
virtual void clearNamedCharStyle ()
 Removes the association of the target text range and its character style. Copies the feature values of the character style into local override values in the contained characters. More...
 
virtual std::auto_ptr< TextParaStyleSetnamedParaStyles () const
 Retrieves a set of all named paragraph styles used in the target text range. More...
 
virtual bool setNamedParaStyle (const std::string &name_)
 Associates a named paragraph style to the target text range. The inherited values can be overridden by styles or features specified locally in contained text ranges or individual paragraphs. More...
 
virtual void clearNamedParaStyle ()
 Removes the association of the target text range and its character style. Copies the feature values of the character style into local override values in the contained characters. More...
 
virtual std::auto_ptr< TextCharFeaturesuniqueCharFeatures () const
 Retrieves the unique character features used in the target text range. Unique features are those which have the same value in all text runs in the range. More...
 
virtual std::auto_ptr< TextParaFeaturesuniqueParaFeatures () const
 Retrieves the unique paragraph features used in the target text range. Unique features are those which have the same value in all text runs in the range. More...
 
virtual bool hasLocalCharFeatures () const
 Reports whether there any local character feature overrides for characters contained in the target text range. More...
 
virtual std::auto_ptr< TextCharFeatureslocalCharFeatures () const
 Retrieves the character features that have local overrides in the target text range, and whose local values are the same in all text runs in the range. More...
 
virtual void setLocalCharFeatures (const TextCharFeatures &feat_)
 Replaces all of the local overrides for all characters in the target text range with a new set of feature values. All values that are assigned become local values, replacing any previous local value. These local values override any specified in a style associated with the character or the text range. All values that are unassigned remove any previous local values, so that those values are inherited. More...
 
virtual void replaceOrAddLocalCharFeatures (const TextCharFeatures &feat_)
 Modifies the local overrides for all characters in the target text range. All values that are assigned become local values, replacing any previous local value. Values that are unassigned leave any previous local values unchanged. More...
 
virtual void clearLocalCharFeatures ()
 Removes all local overrides for all characters in the target text range. All character features are then inherited from styles associated with the character or text range, or from the normal style. More...
 
virtual bool hasLocalParaFeatures () const
 Reports whether there any local paragraph feature overrides for paragraphs contained in the target text range. More...
 
virtual std::auto_ptr< TextParaFeatureslocalParaFeatures () const
 Retrieves the paragraph features that have local overrides in the target text range, and whose local values are the same in all text runs in the range. More...
 
virtual void setLocalParaFeatures (const TextParaFeatures &feat_)
 Replaces all of the local overrides for all paragraphs in the target text range with a new set of feature values. All values that are assigned become local values, replacing any previous local value. These local values override any specified in a style associated with the paragraph or the text range. All values that are unassigned remove any previous local values, so that those values are inherited. More...
 
virtual void replaceOrAddLocalParaFeatures (const TextParaFeatures &feat_)
 Modifies the local overrides for all paragraphs in the target text range. All values that are assigned become local values, replacing any previous local value. Values that are unassigned leave any previous local values unchanged. More...
 
virtual void clearLocalParaFeatures ()
 Removes all local overrides for all paragraphs in the target text range. All paragraph features are then inherited from styles associated with the paragraph or text range, or from the normal style. More...
 
virtual void insertBefore (const std::string &text_)
 Inserts text into the target text range before the current start point. More...
 
virtual void insertAfter (const std::string &text_)
 Inserts text into the target text range after the current end point. More...
 
virtual void insertBefore (const TextRange &otherRange_)
 Inserts text into the target text range before the current start point. More...
 
virtual void insertAfter (const TextRange &otherRange_)
 Inserts text into the target text range after the current end point. More...
 
virtual std::string contents (const std::string &le_="\n") const
 Gets the value (contents) of the text range. More...
 
virtual void select (const bool addToCurrSelection_=false)
 Selects the text in the target text range. More...
 
virtual void deselect ()
 Deselects the text in the target text range; this can result in a discontiguous selection, if this text range is a subset of the selected text. More...
 
virtual void changeCase (const CaseChangeType type_)
 Changes the case of the text in the target text range. More...
 
virtual void fitHeadlines ()
 Adjusts the tracking of the text in the target range to fit on one line spanning the width of the area text object. More...
 
virtual void remove ()
 Deletes all of the characters in the target text range. More...
 

Friends

plugin::TextRange * __accessImpl (const TextRange &)
 
TextRange __accessCtor (const plugin::TextRange &)
 

Detailed Description

Allows for easy manipulation of Illustrator text ranges.

Constructor & Destructor Documentation

hdi::core::TextRange::TextRange ( )

Creates a new TextRange object.

Author
GW
Date
12/2013
Note
New TextRange objects do not relate to any text range on the Illustrator artboard; they are designed to be "receivers" of some other TextRange object via the overloaded assignment operator or assigned to some other existent text art.
hdi::core::TextRange::TextRange ( const TextRange tr_)

TextRange copy constructor.

Author
GW
Date
12/2013
Parameters
tr_TextRange object to copy values from
virtual hdi::core::TextRange::~TextRange ( )
virtual

Destructs a TextRange object.

Author
GW
Date
12/2013

Member Function Documentation

virtual std::auto_ptr<ATE::ITextRange> hdi::core::TextRange::ateTextRange ( ) const
virtual

Gets the ATE text range ref around which the target object is wrapped.

Author
GW
Date
12/2013
Returns
ATE::ITextRange for the target object
Note
Generally, you shouldn't need to call this method. Only use it if you know what you're doing. If a specific piece of functionality provided by Illustrator is not handled by this class (or related classes), then it should probably be added to the hdi_core library.
virtual void hdi::core::TextRange::changeCase ( const CaseChangeType  type_)
virtual

Changes the case of the text in the target text range.

Author
GW
Date
12/2013
Parameters
type_Desired case type
virtual std::auto_ptr<TextCharInspector> hdi::core::TextRange::charInspector ( ) const
virtual

Creates an inspector with which to access the character features of all characters in the target text range.

Author
GW
Date
12/2013
Returns
The new character inspector object
virtual void hdi::core::TextRange::clearLocalCharFeatures ( )
virtual

Removes all local overrides for all characters in the target text range. All character features are then inherited from styles associated with the character or text range, or from the normal style.

Author
GW
Date
08/2014
virtual void hdi::core::TextRange::clearLocalParaFeatures ( )
virtual

Removes all local overrides for all paragraphs in the target text range. All paragraph features are then inherited from styles associated with the paragraph or text range, or from the normal style.

Author
GW
Date
08/2014
virtual void hdi::core::TextRange::clearNamedCharStyle ( )
virtual

Removes the association of the target text range and its character style. Copies the feature values of the character style into local override values in the contained characters.

Author
GW
Date
08/2014
virtual void hdi::core::TextRange::clearNamedParaStyle ( )
virtual

Removes the association of the target text range and its character style. Copies the feature values of the character style into local override values in the contained characters.

Author
GW
Date
08/2014
virtual void hdi::core::TextRange::collapse ( const CollapseDirection  dir_ = CollapseEndDir)
virtual

Resets start or end point of the target range so that it contains only one character, either the first or the last.

Author
GW
Date
12/2013
Parameters
dir_The direction constant to collapse; CollapseEndDir sets the start offset to the end offset, while CollapseStartDir sets the end offset to the start offset
virtual std::string hdi::core::TextRange::contents ( const std::string &  le_ = "\n") const
virtual

Gets the value (contents) of the text range.

Author
GW
Date
12/2013
Parameters
le_Indicates the desired line ending for the output string
Returns
A string for the value of the text art, as UTF-8
Note
Illustrator forces text art to utilize the "\r" character for line endings; if this behavior is unexpected or undesired for your application (as most systems use either "\n" or "\r\n" these days), you can specify what you'd prefer with the optional le_ argument.
virtual void hdi::core::TextRange::deselect ( )
virtual

Deselects the text in the target text range; this can result in a discontiguous selection, if this text range is a subset of the selected text.

Author
GW
Date
12/2013
virtual std::auto_ptr<TextRange> hdi::core::TextRange::duplicate ( ) const
virtual

Duplicates the target text range, returning a new unique TextRange object.

Author
GW
Date
12/2013
Returns
A new TextRange object for the duplicate
virtual int32_t hdi::core::TextRange::end ( ) const
virtual

Gets the end offset of the target text range.

Author
GW
Date
12/2013
Returns
The 0-based index of the end offset from the beginning of the containing story
virtual void hdi::core::TextRange::fitHeadlines ( )
virtual

Adjusts the tracking of the text in the target range to fit on one line spanning the width of the area text object.

Author
GW
Date
12/2013
Note
This is the equivalent of choosing the Type > Fit Headline menu item with the text range selected.
virtual bool hdi::core::TextRange::hasLocalCharFeatures ( ) const
virtual

Reports whether there any local character feature overrides for characters contained in the target text range.

Author
GW
Date
08/2014
Returns
true if there are local overrides, false otherwise
virtual bool hdi::core::TextRange::hasLocalParaFeatures ( ) const
virtual

Reports whether there any local paragraph feature overrides for paragraphs contained in the target text range.

Author
GW
Date
08/2014
Returns
true if there are local overrides, false otherwise
virtual void hdi::core::TextRange::insertAfter ( const std::string &  text_)
virtual

Inserts text into the target text range after the current end point.

Author
GW
Date
12/2013
Parameters
text_The text to be inserted, as UTF-8
Note
Triggers a reflow operation that resets the start and end points of the target and any other affected ranges to include both the old and new text.
virtual void hdi::core::TextRange::insertAfter ( const TextRange otherRange_)
virtual

Inserts text into the target text range after the current end point.

Author
GW
Date
12/2013
Parameters
otherRange_A text range object containing the text
Note
Triggers a reflow operation that resets the start and end points of the target and any other affected ranges to include both the old and new text.
virtual void hdi::core::TextRange::insertBefore ( const std::string &  text_)
virtual

Inserts text into the target text range before the current start point.

Author
GW
Date
12/2013
Parameters
text_The text to be inserted, as UTF-8
Note
Triggers a reflow operation that resets the start and end points of the target and any other affected ranges to include both the old and new text.
virtual void hdi::core::TextRange::insertBefore ( const TextRange otherRange_)
virtual

Inserts text into the target text range before the current start point.

Author
GW
Date
12/2013
Parameters
otherRange_A text range object containing the text
Note
Triggers a reflow operation that resets the start and end points of the target and any other affected ranges to include both the old and new text.
virtual bool hdi::core::TextRange::isEmpty ( ) const
virtual

Gets whether the target TextRange object is empty.

Author
GW
Date
12/2013
Returns
true if the target TextRange object is empty, false otherwise
virtual std::auto_ptr<TextCharFeatures> hdi::core::TextRange::localCharFeatures ( ) const
virtual

Retrieves the character features that have local overrides in the target text range, and whose local values are the same in all text runs in the range.

Author
GW
Date
08/2014
Returns
The character features object containing the unique local feature values. Other features are unassigned. If all features are unassigned, either there are no local overrides, or the local overrides have no common values.
virtual std::auto_ptr<TextParaFeatures> hdi::core::TextRange::localParaFeatures ( ) const
virtual

Retrieves the paragraph features that have local overrides in the target text range, and whose local values are the same in all text runs in the range.

Author
GW
Date
08/2014
Returns
The paragraph features object containing the unique local feature values. Other features are unassigned. If all features are unassigned, either there are no local overrides, or the local overrides have no common values.
virtual int32_t hdi::core::TextRange::move ( const int32_t  unit_)
virtual

Moves the target text range by adding or subtracting a number of characters to or from the start and end offsets.

Author
GW
Date
12/2013
Parameters
unit_The number of characters, positive to move the range toward the end, negative to move it toward the beginning of the story
Returns
The number of characters by which the range was translated, or 0 if the translation could not be made within the story bounds
Note
Does not move the range if the result would be out of the story bounds.
virtual std::auto_ptr<TextCharStyleSet> hdi::core::TextRange::namedCharStyles ( ) const
virtual

Retrieves a set of all named character styles used in the target text range.

Author
GW
Date
08/2014
Returns
The character style set object
virtual std::auto_ptr<TextParaStyleSet> hdi::core::TextRange::namedParaStyles ( ) const
virtual

Retrieves a set of all named paragraph styles used in the target text range.

Author
GW
Date
08/2014
Returns
The paragraph style set object
virtual bool hdi::core::TextRange::operator!= ( const TextRange rhs_) const
virtual

Tests whether a given TextRange object is not the same as another.

Author
GW
Date
12/2013
Parameters
rhs_TextRange to compare against (righthand side of inequality operator)
Returns
true for the target and rhs_ being different text ranges, false otherwise
virtual TextRange& hdi::core::TextRange::operator= ( const TextRange rhs_)
virtual

Overloaded assignment operator for TextRange objects.

Author
GW
Date
12/2013
virtual bool hdi::core::TextRange::operator== ( const TextRange rhs_) const
virtual

Tests whether a given TextRange object is the same as another.

Author
GW
Date
12/2013
Parameters
rhs_TextRange to compare against (righthand side of equality operator)
Returns
true for the target and rhs_ being the same text range, false otherwise
virtual TextParaVector hdi::core::TextRange::paragraphs ( ) const
virtual

Gets a vector of the paragraphs contained in this text range.

Author
GW
Date
08/2014
Returns
The vector of paragraphs
Warning
The caller assumes responsibility for the memory of the contained TextPara objects.
virtual std::auto_ptr<TextParaInspector> hdi::core::TextRange::paraInspector ( ) const
virtual

Creates an inspector with which to access the paragraph features of all paragraphs in the target text range.

Author
GW
Date
12/2013
Returns
The new paragraph inspector object
virtual void hdi::core::TextRange::remove ( )
virtual

Deletes all of the characters in the target text range.

Author
GW
Date
12/2013
Note
Triggers a reflow operation that resets the start and end points of any other affected ranges.
virtual void hdi::core::TextRange::replaceOrAddLocalCharFeatures ( const TextCharFeatures feat_)
virtual

Modifies the local overrides for all characters in the target text range. All values that are assigned become local values, replacing any previous local value. Values that are unassigned leave any previous local values unchanged.

Author
GW
Date
08/2014
Parameters
Thenew feature set object
Note
Triggers a reflow operation that can cause previously obtained text runs to become invalid.
virtual void hdi::core::TextRange::replaceOrAddLocalParaFeatures ( const TextParaFeatures feat_)
virtual

Modifies the local overrides for all paragraphs in the target text range. All values that are assigned become local values, replacing any previous local value. Values that are unassigned leave any previous local values unchanged.

Author
GW
Date
08/2014
Parameters
feat_The new feature set object
Note
Triggers a reflow operation that can cause previously obtained text runs to become invalid.
virtual TextRangeVector hdi::core::TextRange::runs ( ) const
virtual

Gets a vector of the text ranges (that share character attributes) contained in this text range.

Author
GW
Date
08/2014
Returns
The vector of text ranges
Warning
The caller assumes responsibility for the memory of the contained TextRange objects.
virtual void hdi::core::TextRange::select ( const bool  addToCurrSelection_ = false)
virtual

Selects the text in the target text range.

Author
GW
Date
12/2013
Parameters
addToCurrSelection_true to add the target's text to the current selection, false to clear the current selection before selecting this text
virtual std::auto_ptr<TextRangeSet> hdi::core::TextRange::selections ( ) const
virtual

Retrieves the selected text within this text range.

Author
GW
Date
08/2014
Returns
The text ranges object containing the selected text
virtual void hdi::core::TextRange::setEnd ( const int32_t  end_)
virtual

Sets the end offset of the target text range.

Author
GW
Date
12/2013
Parameters
end_The 0-based index of the end offset from the beginning of the containing story
virtual void hdi::core::TextRange::setLocalCharFeatures ( const TextCharFeatures feat_)
virtual

Replaces all of the local overrides for all characters in the target text range with a new set of feature values. All values that are assigned become local values, replacing any previous local value. These local values override any specified in a style associated with the character or the text range. All values that are unassigned remove any previous local values, so that those values are inherited.

Author
GW
Date
08/2014
Parameters
feat_The new feature set object
Note
Triggers a reflow operation that can cause previously obtained text runs to become invalid.
virtual void hdi::core::TextRange::setLocalParaFeatures ( const TextParaFeatures feat_)
virtual

Replaces all of the local overrides for all paragraphs in the target text range with a new set of feature values. All values that are assigned become local values, replacing any previous local value. These local values override any specified in a style associated with the paragraph or the text range. All values that are unassigned remove any previous local values, so that those values are inherited.

Author
GW
Date
08/2014
Parameters
feat_The new feature set object
Note
Triggers a reflow operation that can cause previously obtained text runs to become invalid.
virtual bool hdi::core::TextRange::setNamedCharStyle ( const std::string &  name_)
virtual

Associates a named character style to the target text range. The inherited values can be overridden by styles or features specified locally in contained text ranges or individual characters.

Author
GW
Date
08/2014
Parameters
Thename of the style, as UTF-8
Returns
true if the style is successfully applied, false if there is no style with the specified name
virtual bool hdi::core::TextRange::setNamedParaStyle ( const std::string &  name_)
virtual

Associates a named paragraph style to the target text range. The inherited values can be overridden by styles or features specified locally in contained text ranges or individual paragraphs.

Author
GW
Date
08/2014
Parameters
Thename of the style, as UTF-8
Returns
true if the style is successfully applied, false if there is no style with the specified name
virtual void hdi::core::TextRange::setRange ( const int32_t  start_,
const int32_t  end_ 
)
virtual

Convenience method to set both the start and end points of the target text range.

Author
GW
Date
12/2013
Parameters
start_The 0-based index of the start offset from the beginning of the containing story
end_The 0-based index of the end offset from the beginning of the containing story
virtual void hdi::core::TextRange::setStart ( const int32_t  start_)
virtual

Sets the start offset of the target text range.

Author
GW
Date
12/2013
Parameters
end_The 0-based index of the start offset from the beginning of the containing story
virtual void hdi::core::TextRange::setStory ( const TextStory story_)
virtual

Sets the story that contains this text range.

Author
GW
Date
08/2014
Parameters
Newcontaining story
virtual int32_t hdi::core::TextRange::size ( ) const
virtual

Retrieves the number of characters in the target text range.

Author
GW
Date
12/2013
Returns
The size of the text range
virtual int32_t hdi::core::TextRange::start ( ) const
virtual

Gets the start offset of the target text range.

Author
GW
Date
12/2013
Returns
The 0-based index of the start offset from the beginning of the containing story
virtual std::auto_ptr<TextStory> hdi::core::TextRange::story ( ) const
virtual

Retrieves the story that contains this text range.

Author
GW
Date
08/2014
Returns
The story object
virtual TextArtVector hdi::core::TextRange::textFrames ( ) const
virtual

Gets a vector of the text frames contained in this text range.

Author
GW
Date
08/2014
Returns
The vector of text frames
Warning
The caller assumes responsibility of the memory for the contained TextArt objects.
virtual std::auto_ptr<TextCharFeatures> hdi::core::TextRange::uniqueCharFeatures ( ) const
virtual

Retrieves the unique character features used in the target text range. Unique features are those which have the same value in all text runs in the range.

Author
GW
Date
08/2014
Returns
The character features object containing the unique feature values. Other features are unassigned.
virtual std::auto_ptr<TextParaFeatures> hdi::core::TextRange::uniqueParaFeatures ( ) const
virtual

Retrieves the unique paragraph features used in the target text range. Unique features are those which have the same value in all text runs in the range.

Author
GW
Date
08/2014
Returns
The paragraph features object containing the unique feature values. Other features are unassigned.
virtual TextWordVector hdi::core::TextRange::words ( ) const
virtual

Gets a vector of the words contained in this text range.

Author
GW
Date
08/2014
Returns
The vector of words
Warning
The caller assumes responsibility for the memory of the contained TextWord objects.