Shelf Funcs (2015)

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.

class lwsdk.LWShelfFuncs(self)

Bases: object

Proxy of C++ PCore::LWShelfFuncs class

 addNamedPreset(LWShelfCltID clt, LWImageID img, char params[], char name, char comment) → int index

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 a sequence 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 None.

You can also specify a name and a comment that will help the user identify the preset.

 close(LWShelfCltID clt)

Close the shelf window.

 isOpen(LWShelfCltID clt) → int bool

Returns true (1) if the shelf window is open.

 load(LWShelfCltID clt, char filename, int prompt_user)

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

 open(LWShelfCltID clt)

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

 save(LWShelfCltID clt, char filename, LWImageID thumbnail, char params[])

Save a preset in an external file.

 setContext(LWShelfCltID clt)

Set the shelf context.

 subscribe(char name, char subName, object data, int flags, callable loadOk_callback, callable load_callback, callable save_callback) → LWShelfCltID

Initialize the interaction between a plug-in instance and the shelf. The LWShelfCtlID returned by this function is passed as the first argument to all of the others. For reasons of internal management, the data parameter should unique to your instance, and must not be None (use your self instance here if you have nothing specific to use), and will be passed as the first argument to each of 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:

lwsdk.SHLF_BIN
    Saves to and loads from binary files.
lwsdk.SHLF_ASC
    Saves to and loads from ASCII (text) files
lwsdk.SHLF_SEP
    Saves to and loads from separate (non-LightWave) files.

The last three arguments 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 LWShelfFuncs.subscribe().

loadOK_callback(python data)
    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:

    lwsdk.SHLC_NOWAY
        Do not load. Your plug-in should tell the user why.
    lwsdk.SHLC_DFLT
        Display the default confirmation dialog.
    lwsdk.SHLC_FORCE
        Load without consulting the user.

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

load_callback(python data, LWLoadSate load, char filename, char params[])
    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 LWShelfFuncs.load() function
    to load a preset from a file. In the first case, the filename argument will be None,
    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 None, you'll read the preset from the file named in
    filename. You can still pass this on to and your handler's load callback by creating a
    LWLoadState for the preset file using the File I/O global.

    The parameter list is a sequence 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.

save_callback(python data, LWSaveState save, char filename)
    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 None,
    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 None, 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.

 unsubscribe(LWShelfCltID clt)

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