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. Theparams
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 toaddNamedPreset
, which is passed a default name generated by the shelf system. New code should calladdNamedPreset
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 whensave
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
orFORCE
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, thefilename
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 infilename
. 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
orsave
. 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
orsave
. When adding a preset to the shelf, thefilename
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 infilename
. 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.