Globals: Shelf Functions

Shelf Functions

Availability  LightWave 6.0
Component  Layout, Modeler
Header  lwshelf.h

The shelf is a window where users can store and retrieve presets for your plug-in. The shelf API supplies functions that let you subscribe (connect), set the context (tell the shelf that your interface is the active one), open the shelf window, and add, load and save presets.

For some plug-in classes, you don't need to call this global in order to gain access to the shelf's preset management. Beginning with LightWave 7.0, the user can load and save presets for your plug-in through the VIPER (Versatile Interactive Preview Render) interface. Presets can be added to the shelf or loaded into your plug-in through calls to your regular handler load and save callbacks.

Global Call

   LWShelfFuncs *shelff;
   shelff = global( LWSHELFFUNCS_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to an LWShelfFuncs.

   typedef struct st_LWSHELFFUNCS {
      LWShelfCltID (*subscribe)(char *name, char *subName,
                                  void *userData, int flags,
                                  LWShelfLoadOkFunc *,
                                  LWShelfLoadFunc *,
                                  LWShelfSaveFunc *);
      void (*unsubscribe)   (LWShelfCltID);
      void (*open)          (LWShelfCltID);
      int  (*isOpen)        (LWShelfCltID clt);
      void (*close)         (LWShelfCltID);
      void (*setContext)    (LWShelfCltID);
      int  (*addPreset)     (LWShelfCltID, LWPixmapID img,
                               LWShelfParmList parms);
      void (*load)          (LWShelfCltID, char *filename,
                               int prompt_user);
      void (*save)          (LWShelfCltID, char *filename,
                               LWImageID thumimg, LWShelfParmList);
      int  (*addNamedPreset)(LWShelfCltID clt, LWPixmapID img,
                               LWShelfParmList parms, const char *name,
                               const char *comment );
   } LWShelfFuncs;

client = subscribe( class, server, userdata, flags, loadok, load, save )

Initialize the interaction between a plug-in instance and the shelf. The client ID returned by this function is passed as the first argument to all of the others. The user data, typically the instance data for handlers, will be passed as the first argument to the three callbacks. The flags argument is a set of flag bits combined using bitwise-or. They indicate what kind of preset loading and saving the plug-in supports and can be any combination of the following.

SHLF_BIN

Saves to and loads from binary files.

SHLF_ASC

Saves to and loads from ASCII (text) files

SHLF_SEP

Saves to and loads from separate (non-LightWave) files.

unsubscribe( client )

Conclude your instance's use of the shelf. You should call this before your instance is destroyed.

open( client )

Open the preset shelf window and set the context to your plug-in. The window will display only the presets for your plug-in.

open = isOpen( client )

Returns true if the shelf window is open.

close( client )

Close the shelf window.

setContext( client )

Set the shelf context.

index = addPreset( client, img, params )

Add a preset to the shelf. The img is the preset's thumbnail in the shelf window, created using the Image Utility functions. The params are passed as a NULL-terminated array of strings (tags) that you can use in your shelf load callback to tell which parameters in this preset should be loaded. In the simplest case, params will be NULL.

addPreset is implemented as a call to addNamedPreset, which is passed a default name generated by the shelf system. New code should call addNamedPreset directly.

load( client, filename, prompt_user )
save( client, filename, thumb_img, params )

Load or save a preset in an external file. Presets are ordinarily stored in a file managed by the shelf system, but you can use these functions to load and save presets in files you name. For loading, if prompt_user is true and the preset contains a parameter list (params was non-NULL when save was called for the preset), the user is prompted for input.

index = addNamedPreset( client, img, params, name, comment )

Add a named preset to the shelf. Like addPreset, but you can also specify a name and a comment that will help the user identify the preset.

Callbacks

The last three arguments to the subscribe function are callbacks that the shelf calls when a preset is to be loaded or saved. The shelf system calls these to actually load and save the preset. For all three callbacks, the first argument is the user data you passed to subscribe.

   typedef int  LWShelfLoadOkFunc (void *userdata);
   typedef void LWShelfLoadFunc   (void *userdata, const LWLoadState *,
                                     const char *filename,
                                     LWShelfParmList);
   typedef void LWShelfSaveFunc   (void *userdata, const LWSaveState *,
                                     const char *filename );

LWShelfLoadOkFunc

Returns a code that tells the shelf system whether to load the preset and whether the user should be prompted first. The code can be one of the following.

SHLC_NOWAY

Do not load. Your plug-in should tell the user why.

SHLC_DFLT

Display the default confirmation dialog.

SHLC_FORCE

Load without consulting the user.

Your plug-in can display its own confirmation dialog and then return NOWAY or FORCE as appropriate, but you'll lose the ability to use parameter lists to selectively load parameters from your presets.

LWShelfLoadFunc

Load the preset. The shelf calls this when the user double-clicks on a preset thumbnail in the shelf window, or when you call the load function to load a preset from a file. In the first case, the filename argument will be NULL, and you'll read the preset's parameters by calling the LWLoadState functions. Typically, handlers pass this job on to their handler load callback. In the second case, the LWLoadState will be NULL, and you'll read the preset from the file named in filename. You can still pass this on to your handler's load callback by creating an LWLoadState for the preset file using the File I/O global.

The parameter list is an array of strings. It contains a subset of the parameter list you passed to addPreset, addNamedPreset or save. The default load confirmation dialog presents the list to the user and allows the user to select parameters. Only selected parameters are passed to your load callback. You can use the selections to load only portions of a preset.

LWShelfSaveFunc

Save the preset. The shelf calls this when you call addPreset, addNamedPreset or save. When adding a preset to the shelf, the filename argument will be NULL, and you'll store the preset's parameters by calling the LWSaveState functions. Typically, handlers pass this job on to their handler save callback. When saving a preset to a file, the LWSaveState will be NULL, and you'll write the preset to the file named in filename. You can still pass this on to your handler's save callback by creating an LWSaveState for the preset file using the File I/O global.

The parameter list is an array of strings representing parameters or groups of parameters in your preset data. When the preset is reloaded, the user can select from this list of named parameters, and the user's selection will be passed to the load callback.

Example

The shelf SDK sample is a Master plug-in that demonstrates the shelf functions. (This is all it does, in fact.) The plug-in's "data" is merely a color. The interface lets you add color presets to the shelf or save them in separate files. You can then load them back into the plug-in's handler instance.