CNS Plug-ins

Coding Considerations

##Getting Results

Every time you use an MMColor function, something is returned back from the plug-in, whether that be an image, a HexColor, or some other status text. This information can be very useful for letting you know if an error occurred. Consider the following code:

MMColor_GetColorComponent( “FF00FF” ; “RGB” ; “Red” )

The above code will extract the value of the Red component from the HexColor provided. If it was successful, the plug-in will return:

255

However, if there was an error with the parameters (for example, if the Component was not a part of the Color Space), the plug-in will return something like:

ERROR: GetColorComponent: The Color Space you specified (‘RGB’) does not contain the Component you specified (‘Hue’).

##Curly Brackets

Curly brackets indicate that a parameter or parameters are optional. Take the MMColor_ShowColorPicker function for example:

MMColor_ShowColorPicker{( StartHexColor )}

This function can be called without any parameters because the parameter section is surrounded by curly brackets indicating that is it optional. Using the function in this manner looks like:

MMColor_ShowColorPicker

The above code would open the System Color Picker Dialog. However, if you would like to specify an initial color for the System Color Picker Dialog, you can specify the HexColor for the “StartHexColor” parameter:

MMColor_ShowColorPicker( “00FF00” )

In more complex functions, there may be multiple optional parameters. Note that if there are optional parameters before one that you need to use, you must include any parameters before it. Consider the MMColor_CreateColorImage function:

MMColor_CreateColorImage( HexColor {; Width {; Height {; Alpha }}} )

If you want to specify 128 for the “Alpha” parameter, you must also specify the two optional parameters before it. The following is an incorrect example and a correct example of setting the “Alpha” parameter to 128:

INCORRECT: 

MMColor_CreateColorImage( “FFFF00” ; 128 )

CORRECT: 
MMColor_CreateColorImage( “FFFF00” ; “” ; “” ; 128 )

FileMaker Version Considerations

When plug-ins were first introduced, the only place you really wanted to use a plug-in function was the Set Field script step. However, since FileMaker 4, many new advancements have taken place. Though the Set Field script step is still a very common place to use plug-in functions, there are now many places that can logically be used. For a list of a few of these places, see the next section titled “Places to use MMColor Functions”.

It is important to keep in mind what versions of FileMaker will be in use when using MMColor and other plug-ins. For example, creating a variable using the Set Variable script step can be very convenient, however, that functionality only exists in FileMaker 8 and greater. If you or your users use FileMaker 7, then your script calls would fall on deaf ears if you used Set Variable script step. In addition, when using functions in a variable you will be less likely to see the results returned from the plug-in (such as error messages), because a variable cannot but put on a layout like a field.

Places to use MMColor Functions

You can use MMColor functions in any calculation engine dialog in FileMaker. Keep in mind that just because you can do something does not mean it is actually useful.

There are several places that fit very well depending on the situation: