I'm trying to simply create a rectangle and then fill it with a pattern that the user can specify but which is also loaded by the plug-in. I'm pretty sure I can make the box and fill it easily enough with the AIActionManagerSuite.
I just have no idea how to get a custom pattern from a file into a swatch programmatically. Any ideas?
You can do it by specifing a path too. Combine what you have there with this:
|ASErr ASAPI(*||ImportStyles )(const ai::FilePath& source, AIDocumentHandle *newdoc)|
|Imports styles from a file, and creates a new document containing the styles.|
Assuming you feed it a valid path to a valid Illustrator file, that will return the handle to the document, but the document won't be displayed. From there, you can use GetSwatchList to pull out the list of swatches it contains
There are a variety of APIs that let you specify a document handle and pull things like graphic styles, swatches, etc from them. It's quite useful! I only discovered this myself about a year ago, and it's let me do some wonderfully fun things!
No, this function is effectively the code behind the 'Other library...' option on the Symbol, Swatch & Graphic Style panels, the one where you can open an existing 'library' for those three types of art. That is basically calling ImportStyles() on whatever you pick (which you'll note has to be an existing AI file). In the UI case, that creates a new panel and populates it based on what it found inside. If you just call ImportStyles(), you'll have a handle to a document but that document won't appear anywhere. You don't have to close it (AI will do that when you shutdown) though I suspect you could if you really wanted. The main purpose of the handle is to feed it to those APIs like the first one you listed.
This function doesn't require there be a document open already, you could call this any time, even if there was nothing open. The API does this in a few places behind the scenes; for example, I know that if you place an image that it creates a hidden document and then moves the art over to the current document. This is doing something similar.
So, yes, it kind of means 'Get a document handle based on the specified file path'. That's not a bad way to put it.