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

Wraps around a third-party plugin, such that it can be messaged or otherwise manipulated. More...

#include <hdicoreThirdPartyPlugin.h>

Public Types

enum  Options { NoOptions = 0, AutoSelectsResultsOption = 1 << 0, RetainsPartialPathSelectionOption = 1 << 1 }
 Identifies the configuration of various plug-in behaviors.
 

Public Member Functions

 ThirdPartyPlugin ()
 Constructs an empty ThirdPartyPlugin object. More...
 
 ThirdPartyPlugin (const ThirdPartyPlugin &p_)
 Constructs a new ThirdPartyPlugin object from an existing ThirdPartyPlugin object (copy constructor) More...
 
virtual ~ThirdPartyPlugin ()
 Destructs a ThirdPartyPlugin object. More...
 
virtual ThirdPartyPluginoperator= (const ThirdPartyPlugin &rhs_)
 Assigns one ThirdPartyPlugin object to another. More...
 
virtual bool operator== (const ThirdPartyPlugin &rhs_) const
 Tests whether a given ThirdPartyPlugin object is the same as another. More...
 
virtual bool operator!= (const ThirdPartyPlugin &rhs_) const
 Tests whether a given ThirdPartyPlugin object is not the same as another. More...
 
virtual SPPluginRef spPluginRef () const
 Gets the plugin ref around which this object is wrapped. More...
 
virtual bool isEmpty () const
 Gets whether the target ThirdPartyPlugin object is empty (constructed with the default ctor) More...
 
virtual std::string filePath () const
 Gets the full path of the plugin file at runtime. More...
 
virtual std::string fileName () const
 Gets the name of the plugin file at runtime. More...
 
virtual std::string name () const
 Gets the plugin name. More...
 
virtual Options options () const
 Gets the plugin's options. More...
 
virtual bool started () const
 Gets whether the plugin has started. More...
 
virtual bool broken () const
 Gets whether the plugin has reported an error condition that makes it unavailable. More...
 
virtual bool prepMessageData (SPMessageData &message__) const
 Initializes a message to be sent to the target plugin with message() More...
 
virtual SPErr message (const std::string &caller_, const std::string &selector_, SPMessageData *const message_, SPErr &result__) const
 Sends a message to the target plugin. More...
 
virtual bool cleanMessageData (SPMessageData &message__) const
 Destroys a message that has already been sent to the target plugin with message() More...
 

Friends

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

Detailed Description

Wraps around a third-party plugin, such that it can be messaged or otherwise manipulated.

Constructor & Destructor Documentation

hdi::core::ThirdPartyPlugin::ThirdPartyPlugin ( )

Constructs an empty ThirdPartyPlugin object.

Author
GW
Date
04/2014
Note
To test if a ThirdPartyPlugin object is empty, call isEmpty() on it
Empty ThirdPartyPlugin objects do not relate to any Illustrator plugin; they are designed to be "receivers" of some other ThirdPartyPlugin object via the overloaded assignment operator. Empty ThirdPartyPlugin objects are useless until such time (though it is safe to call any of their methods).
hdi::core::ThirdPartyPlugin::ThirdPartyPlugin ( const ThirdPartyPlugin p_)

Constructs a new ThirdPartyPlugin object from an existing ThirdPartyPlugin object (copy constructor)

Author
GW
Date
04/2014
Parameters
p_Existing ThirdPartyPlugin object
virtual hdi::core::ThirdPartyPlugin::~ThirdPartyPlugin ( )
virtual

Destructs a ThirdPartyPlugin object.

Author
GW
Date
04/2014

Member Function Documentation

virtual bool hdi::core::ThirdPartyPlugin::broken ( ) const
virtual

Gets whether the plugin has reported an error condition that makes it unavailable.

Author
GW
Date
04/2014
Returns
true if the plugin is broken, false otherwise
virtual bool hdi::core::ThirdPartyPlugin::cleanMessageData ( SPMessageData message__) const
virtual

Destroys a message that has already been sent to the target plugin with message()

Author
GW
Date
04/2014
Parameters
message__A reference to an existent SPMessageData object that needs to be cleaned up
Returns
true if the cleanup was successful, false otherwise
Note
Since you should have allocated the message__ argument using the Illustrator::alloc() method in the first place (right!?), you should now deallocate it using the Illustrator::free() method.
virtual std::string hdi::core::ThirdPartyPlugin::fileName ( ) const
virtual

Gets the name of the plugin file at runtime.

Author
GW
Date
04/2014
Returns
Plugin file name as UTF-8, e.g. "MyPlugin.aip"
virtual std::string hdi::core::ThirdPartyPlugin::filePath ( ) const
virtual

Gets the full path of the plugin file at runtime.

Author
GW
Date
04/2014
Returns
Plugin file path as UTF-8, e.g. "/Applications/Adobe Illustrator CC/Plug-ins/MyPlugin.aip"
virtual bool hdi::core::ThirdPartyPlugin::isEmpty ( ) const
virtual

Gets whether the target ThirdPartyPlugin object is empty (constructed with the default ctor)

Author
GW
Date
04/2014
Returns
true if the target ThirdPartyPlugin object is empty, false otherwise
virtual SPErr hdi::core::ThirdPartyPlugin::message ( const std::string &  caller_,
const std::string &  selector_,
SPMessageData *const  message_,
SPErr &  result__ 
) const
virtual

Sends a message to the target plugin.

Author
GW
Date
04/2014
Parameters
caller_Caller to send to the plugin
selector_Selector for caller_ to send to the plugin
message_Message data to send to the plugin. See notes.
result__Return-by-reference for the output error from the target plugin
Returns
Whether an error occurred when attempting to message the plugin
Note
The message_ argument MUST be initialized by the prepMessageData() method, and destroyed by the cleanMessageData() method.
You are not limited in sending merely an SPMessageData object to the plugin; you can send any other type of structure, but the first member of said structure MUST be a SPMessageData object (so you can legally cast the other structure to SPMessageData*). If you choose to go this route, the entire structure instance must be allocated using the Illustrator::alloc() method.
virtual std::string hdi::core::ThirdPartyPlugin::name ( ) const
virtual

Gets the plugin name.

Author
GW
Date
04/2014
Returns
The plugin name, as UTF-8
virtual bool hdi::core::ThirdPartyPlugin::operator!= ( const ThirdPartyPlugin rhs_) const
virtual

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

Author
GW
Date
04/2014
Parameters
rhs_ThirdPartyPlugin to compare against (righthand side of inequality operator)
Returns
true for the target and rhs_ being different plugins, false otherwise
virtual ThirdPartyPlugin& hdi::core::ThirdPartyPlugin::operator= ( const ThirdPartyPlugin rhs_)
virtual

Assigns one ThirdPartyPlugin object to another.

Author
GW
Date
04/2014
Parameters
rhs_Existing ThirdPartyPlugin object to copy values from
Returns
The target ThirdPartyPlugin object, but with its values updated to match that of the rhs_ argument
virtual bool hdi::core::ThirdPartyPlugin::operator== ( const ThirdPartyPlugin rhs_) const
virtual

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

Author
GW
Date
04/2014
Parameters
rhs_ThirdPartyPlugin to compare against (righthand side of equality operator)
Returns
true for the target and rhs_ being the same plugin, false otherwise
virtual Options hdi::core::ThirdPartyPlugin::options ( ) const
virtual

Gets the plugin's options.

Author
GW
Date
04/2014
Returns
Current plugin options
virtual bool hdi::core::ThirdPartyPlugin::prepMessageData ( SPMessageData message__) const
virtual

Initializes a message to be sent to the target plugin with message()

Author
GW
Date
04/2014
Parameters
message__A reference to an existent SPMessageData object that needs to be initialized
Returns
true if message__ could be initialized, false otherwise
Note
The message__ argument MUST already be allocated in Illustrator's shared memory using the Illustrator::alloc() method.
virtual SPPluginRef hdi::core::ThirdPartyPlugin::spPluginRef ( ) const
virtual

Gets the plugin ref around which this object is wrapped.

Author
GW
Date
04/2014
Returns
SPPluginRef for the target ThirdPartyPlugin 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 library.
virtual bool hdi::core::ThirdPartyPlugin::started ( ) const
virtual

Gets whether the plugin has started.

Author
GW
Date
04/2014
Returns
true if the plugin has started, false otherwise