Globals: Color Picker

Color Picker

Availability  LightWave 6.0
Component  Layout, Modeler
Header  lwhost.h

The color picker global returns a function that prompts the user for a color selection. The request displays the color dialog currently installed in LightWave. This may be the default system dialog or a custom ColorPicker plug-in.

The function returned by the color picker global calls the color picker module's activation function directly. Plug-ins calling the function act as the host side of the ColorPicker plug-in class.

Global Call

   LWColorActivateFunc *colorpick;
   colorpick = global( LWCOLORACTIVATEFUNC_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to an LWColorActivateFunc.

   typedef int LWColorActivateFunc (int version, LWColorPickLocal *);

The return value of this function can be any of the values defined for the return values of activation functions. Any value other than AFUNC_OK must be handled as an error.

The version is passed as the version argument to the color picker's activation function. This should be set to the value defined by the LWCOLORPICK_VERSION symbol in lwdialog.h. Color picker plug-ins with a different activation version will return AFUNC_BADVERSION.

The second argument to this function is a pointer to a structure that is passed as the local argument to the color picker's activation function.

The Local Structure

The color picker function passes an LWColorPickLocal as the local argument to the activation function of the color picker plug-in.

   typedef void LWHotColorFunc (void *data, float r, float g, float b);

   typedef struct st_LWColorPickLocal {
      int             result;
      const char     *title;
      float           red, green, blue;
      void           *data;
      LWHotColorFunc *hotFunc;
   } LWColorPickLocal;

result

The result of the request. This will be 1 if the user selected a color, 0 if the user cancelled the request, and a negative number to indicate an error.

title

The title string. This is generally displayed near the top of the color dialog and tells the user the context of the color request.

red, green, blue

The initial color. If the user selects a color, these fields will be modified to contain the selected color. The nominal range for RGB levels is 0.0 to 1.0, but they can be outside this range.

data

A pointer to data that will be passed to your hot color callback. This can point to anything your callback requires, or NULL. The color picker ignores it.

hotFunc( data, r, g, b )

A color callback you supply. The color picker calls this while the user is playing with any of its color selection mechanisms. This allows you to update your own display interactively as the user selects a color. (The "hot" part of the name refers to this dynamic interaction. This isn't an NTSC color gamut test.) The callback should execute quickly enough that it doesn't bog down the interactivity of the color picker with the user.

Example

This code fragment asks the user for a color.

   #include <lwserver.h>
   #include <lwhost.h>

   void colorcb( MyDisplayData *data, float r, float g, float b )
   {
      /* redraw my display with the current color */
      ...
   }

   LWColorActivateFunc *colorpick;
   LWColorPickLocal clrloc;
   MyDisplayData myhotdata;
   int result;

   colorpick = global( LWCOLORACTIVATEFUNC_GLOBAL, GFUSE_TRANSIENT );
   if ( !colorpick ) goto NoColorPick;  /* global calls can fail */

   clrloc.title   = "Widget Color";
   clrloc.red     = current_red;
   clrloc.green   = current_green;
   clrloc.blue    = current_blue;
   clrloc.data    = &myhotdata;
   clrloc.hotFunc = colorcb;

   result = colorpick( LWCOLORPICK_VERSION, &clrloc );
   if ( result == AFUNC_OK && clrloc.result > 0 ) {
      current_red   = clrloc.red;
      current_green = clrloc.green;
      current_blue  = clrloc.blue;
      ...