Best practice to spawn window with text input UI from effects parameters?

[Arie Stavchansky]

Hi There!

I'm writing this post to seek out some guidance and "best practices" for implementing a specific type of parameter in my effect.

In many third-part effects, I've seen buttons along with the list of configurable paramters that spawn a modal window that allows users to enter in text and then somehow store that text with the layer.  

I'm sure there are many ways to accomplish this, but wondered if any of you have knowledge about a relatively simple way of doing this.  

Does it require linking to a C++ library or framework that allows for the creation of custom UI elements?  Or, does Adobe's AE SDK have methods for generating this from the C++?

Is it better to just have the button perform some kind of ExtendScript that launches a dialog?

Thanks for your time!

—Arie

[shachar carmi]

Hi Arie! how are you? 🙂

there are 2 separate issues here:

1. getting the user input.

2. storing the data in the effect instance.

getting the data can be VERY easy. i used javascript for that. using AEGP_ExecuteScript i launched a pormpt. it takes text input from the user, and by checking the returned value you can tell if the user hit "ok" or "cancel".

easy peasy.

if you want to go fnacier, you can use OS level windows. takes some chweing thorugh on both OSes, but no 3rd party library needed.

as for storing the data in the effect, you can either use sequence data, or an arb param. i went the arb route, as it allows the user to undo/redo the operation.

for final touches, i also added a custom UI to the arb paramthat shows the current text value. if you with to avoid that, a simple button to trigger the window would do the trick.

[Arie Stavchansky]

Shachar, many thanks for your reply, I appreciate it very much — especially with what's going on on your part of the world.  I should be asking you how you are doing!  I will follow up via email, soon.

I think I'm going to go with your suggestions regarding the AEGP_ExecuteScript as that is the easiest in terms of cross-OS compatibility.  I'm not prepared to chew through docs for handling custom GUI's for both UIs.  I just need a text string to be stored with the layer, nothing else.

If I go with the arbitrary parameter route, does that have a display in the list of parameters?  If it does display, should I just hide its visibility from the user?

Also, I guess I'm not clear: does the arbitrary parameter have the button that effectively executes the AEGP_ExecuteScript resource string?  In other words, is everything handled with the arb param?  Both the text string capture, store, and recall (read)?

Do you have a screenshot of the custom UI you build to dipsy the current text value?

Many thanks for your guidance, as always it's a huge help!

—Arie

[shachar carmi · Accepted solution]

technically, the clickable "thing", the launching of the prompt and the storing of the string are separate things and don't have to be parts of the same param. you can have a button param launch the prompt, and store the string in an arb. that arb can very well be hidden.

i opted for having it all on the arb. i made a custom UI that both shows the current string AND is clickable.

here's an example from one of my plugins:

[Arie Stavchansky]

Shachar,

I've built sample custom ECW UI plugin from the SDK download.  This example is a bit more complex than yours, but I'm trying to understand how to "draw" the area and "fill" it with UI stuff.

In the sample, the end-user can click and drag anywhere on the custom UI to alter the color display.  But, for some reason there is a strange two-character string in the middle of the custom UI.  I looked at the code, but could not find this string anywhere.  Like your example, I just want to display text and have it clickable to launch the text area input from the ExtendScript.  

I guess I was hoping to see how I can get text to display in the custom UI.  What part of the sample code should I look at to understand that part?

Here is what I'm seeing:

UI from Sample ECW_UI project.

Thanks again for your time and help!

—Arie

[shachar carmi]

i think this might be a utf16 thing... did you connvert your string to utf16 before passing it on to drawbot's DrawString()?

[Arie Stavchansky]

You are right, it was something to do with the way the project was being built.  I eventually got it to print out correctly!

 

I will likely have more questions about the custom UI, but this is a great place to start.  Many thanks Shachar!

—Arie

[shachar carmi]

glad to help, my good friend. 🙂

[Arie Stavchansky]

@shachar carmi I'm curious how much data can be stored in the arb parameter.  In this case as I am looking to store a text string, I want to be sure I can store enough characters before I take implementation farther.

Is there a limit to how many characters can be stored within the arb parameter?

Another question: is it possible to have the string of text "wrap" within the effects controls UI if I did NOT want to hide it?

Also, I reviewed the documentation for arbitrary parameters and also looked at the "ColorGrid" sample project.  It seems like arbitrary parameters requires ALOT of code because you have to "react" to the many "Arbitrary Data Selectors".  Is it easier to just store the captured string to the layer's sequence data?

To read the stored data using the AEGP_ExecuteScript() function so it displays again in the prompt when the user wishes to edit it at a later time, is it easier to implement if using the arb param or the layer's sequence data?

Thanks!

[shachar carmi]

There's no hard limit on an arb param's data size that i know of. the only cosideration is that AE makes a TON of copies of each arb data handle (seriously, a REDICULOUS amount), so it tends to take up a lot more ram then you intend...

for a path text string, this is a non issue. for non-keyframable arb params, this is also a non-issue. i implemented image data saving in an arb which is keyframable (a few MB each), and oh boy... was it an issue.

but for a path string that's a mere few bytes and usually less than a kb, negligible.

there are no "wrap" options for drawbot text drawing that i'm aware of. there are truncation options thought. for exampe, kDRAWBOT_TextTruncation_EndEllipsis.

i personally don't use these truncation options or wraping, and instead handle it with my own code. (honest to god, i don't remember why... perhaps legacy dating back before drawbot)

the problem i ran into, is that drawbot doesn't offer means of measuring a string's length like gdiplus or quartz do. so i'm doing an estimate using the font size * some factor. it's rough, but good enough for my purposes.

as for arb vs sequence data. it's really about the use case.

sequence:

1. is not undo/redo-able.

2. survives the user hitting the effect's "reset" button.

3. is ram firednly and doesn't create a ton of copies.

4. is invisible to the user.

5. syncing it to the render thread is possible at certain times only...

6. is not keyframeable.

7. can not be directly accessed by other components such as an external AEGP.

arb:

1. is keyframable if needed.

2. has a standarad UI, as opposed to sequence data which is invisble.

3. takes up more ram per unit saved due to many copies made. (matters only on large data sets)

4. somewhat cumbersome implementation...

bottom line is, if you need it to look and behave like a param, go with an arb.

the secret for handling arbs easily, is the passed refcon pointer passed on the arb defntion during param setup. i pass a pointer to a handler class instead of recognizing the sepcific arb using a stateless switch. unce i built that handler class, arbs became breeze to handle.

i personally use an arb for text-based params for many of the above mentioned reasons.

[Arie Stavchansky]

Thank you for confirming that arb param is probably the best way to go.

Another question:  since I'm using the AEGP_ExecuteScript with a resource string.  What is the best practice to get the hidden arb param data into that resource string when it pops up?  Is it some kind of sprintf statement on the C++ side that substitutes tokens in the resource string so that the actual text string can appear in the UI?

For example, would the ExtendScript resource string for the AEGP_ExecuteScript might look like:

string myScript = sprintf("alert('arbitrary parameter data: %s')", arb_param_data);

And finally, how do plugin vendors get small bitmap images of their company logo to appear in their effect in the effects control window?  Do they use the arbitrary parameter for this?  Take this example from RedGiant effect:

[shachar carmi]

sprintf is a solid choice. on my code i see that i used some custom version of std::string (that allocates memory from AE instead of the heap), so i'm not limited to the sprintf buffer size. (you can of course dynamically allocate some buffer to use with sprintf.

also note that AEGP_ExecuteScript takes utf8, unless you set one or it's flags to true in which case it will use loval settings. i use false to always have utf8.

as for the "banner" ui, you CAN use any param. however, PF_Param_NO_DATA is the best choice. it's a param with no associated data, so it doesn't waste resources on tracknig an unsued param value.