logoLightwave3D Panel Services:logo

User-Interface functions for plugins.

Lightwave3D panel services are a set of routines for creating user interface panels within plugins. Interface code will work on all supported Lightwave3D platforms (Windows, SGI, Amiga, ...) and match the look of the Lightwave3D interface. In addition, basic drawing routines are provided. Lwpanels.p is a global-class plug-in. This means that its functions are only available to other plug-ins, not to end users. To call lwpanels.p from a plug-in file, you must first get access to its functions by calling the global function with the name for the plug-in service, in this case "LWPanelServices". If the plug-in is loaded in LW, the global function will return the address of a LWPanelFuncs structure, which has pointers to all the available functions. The definitions for this and other necessary structures are in the file lwpanel.h, which must be #included in your source.

Panels

The LWPanelFuncs structure has the following functions:

LWPanelID create(char *title, void *data)
Create a panel. The data pointer is provided for client use, as it will be passed to all the callback functions.
void destroy(LWPanelID panID)
Free the panel and all its controls.
int open(LWPanelID panID, int flags)
Open the panel. The size, position, should already be set and controls all added and positioned. Set bits in flags to determine whether there will be a cancel button (PANF_CANCEL), whether the panel will block all other input waiting to be closed (PANF_BLOCKING).
int handle(LWPanelID panID, int EventMode)
For panels opened in a non-blocking mode, this function handles all the accumulated input. It returns -1 if the user has closed the panel, or 0 otherwise. If the EventMode specified has the EVNT_BLOCKING bit set, this function will not return until the panel is closed.
void draw(LWPanelID panID, DrMode mode)
Draw or redraw the panel and its controls. Use any of the enumerated DrMode types.
void close(LWPanelID)
Close the panel. It can be reopened.
void get(LWPanelID, pTag tag, void *value);
Query a panel for the value specified by the tag. This is the only way of getting information about a panel. The value argument should point to the appropriate data type (integer or address). Use the following tags:
PAN_X, PAN_Y, PAN_W, PAN_H -- Panel position and size.
PAN_MOUSEX, PAN_MOUSEY -- Mouse position at last event, relative to Panel position
PAN_TITLE -- Panel title
PAN_LWINSTANCE -- Some LWInstance data (or whatever) which you previously stashed there
void set(LWPanelID, pTag tag, void *value);
Set specified value for panel. This is the only way to position or size the panel, or attach callbacks. The value argument should point to the appropriate data type (integer or address). Use the following tags:
PAN_X, PAN_Y, PAN_W, PAN_H -- Panel position and size. To ensure compatibility across all displays, the maximum panel size is limited to 640x480 (at 0,0). Sorry.
PAN_TITLE -- Panel title, initially set by create().
PAN_USERDATA -- Data passed to callbacks.
PAN_USERDRAW -- Draw callback function, if initialized, this function will be called whenever the panel is drawn.
PAN_USEROPEN -- Open callback function, if initialized, this function will be called whenever the panel is opened.
PAN_USERCLOSE -- Close callback function, if initialized, this function will be called whenever the panel is closed.
PAN_USERKEYS -- Keyboard callback function, if initialized, this function will be called upon keyboard input
PAN_MOUSEBUTTON -- Mouse click callback function, if initialized, this function will be called upon mouse button up or down events.
PAN_MOUSEMOVE -- Mouse move callback function, if initialized, this function will be called upon mouse move events after a button down event and before the next up event.
LWControl *addControl(LWPanelID pan, char *type, LWPanControlDesc *data, char *label)
Add a control element to a panel. The type of control is determined both by the value of the type string and the LWPanControlDesc structure.
        Type string             Value type       ControlDesc type

        ButtonControl           LWT_INTEGER
        BoolControl             LWT_INTEGER
        BoolButtonControl       LWT_INTEGER
        TextControl             LWT_INTEGER      LWPanTextDesc
        EditControl             LWT_STRING       LWPanStringDesc
        InfoControl             LWT_STRING
        FileControl             LWT_STRING       LWPanStringDesc
        FileButtonControl       LWT_STRING       LWPanStringDesc
        NumControl              LWT_INTEGER
        NumInfoControl          LWT_INTEGER
        FloatControl            LWT_FLOAT
        FloatInfoControl        LWT_FLOAT
        FVecControl             LWT_VFLOAT
        FVecInfoControl         LWT_VFLOAT
        VecControl              LWT_VINT
        VecInfoControl          LWT_VINT
        RGBControl              LWT_VINT
        HSVControl              LWT_VINT
        RGBVecControl           LWT_VINT
        ChoiceControl           LWT_INTEGER      LWPanChoiceDesc
        PopupControl            LWT_INTEGER      LWPanChoiceDesc
        SliderControl           LWT_INTEGER      LWPanRangeDesc
        MiniSliderControl       LWT_INTEGER      LWPanRangeDesc
        AreaControl             LWT_INTEGER      LWPanAreaDesc
        OpenGLControl           LWT_INTEGER      LWPanAreaDesc
        LWListControl           LWT_INTEGER      LWPanLWItemDesc

Controls are stacked as they are added, and remain in that order internally regardless of any onscreen repositioning. A control's initial position will be determined by the vertical position and height of the previous control. As a consequence, controls may be moved up into multiple columns as they are created so subsequent rows will created in the right position automatically. Controls may most easily be added by using the supplied preprocessor macros in LWPanel.h (i.e. SLIDER_CTL), which initialize the appropriate LWPanControlDesc values for you.

LWControl *nextControl(LWPanelID pan, LWControlID ctl)
Returns the next control, or the first if ctl is NULL, or NULL if there are no controls at all.
DrawFuncs *drawFuncs
A DrawFuncs structure, brimming with useful functions for drawing on your panels. More below.
void *user_data
Just a spare pointer you may use for anything.
GlobalFunc *globalFun
Put your global pointer in here for convenient access.

Controls

The LWControl structure has the following elements:

void draw(LWControlID ctl, DrMode mode)
Draw the control in the given mode.
void get(LWControlID ctl, cTag tag, DynaValue *val)
Get a value from a control. It will be returned as the appropriate DynaValue type (pointers = LWT_INTEGER)
void set(LWControlID ctl, cTag tag, DynaValue *val)
Set a value for a control. It will be returned as the appropriate DynaValue type (pointers = LWT_INTEGER)
void *priv_data
System-critical internal data, DO NOT TOUCH.

Like the LWPanelFuncs structure, the LWControl structure is accessed only through its get() and set() member functions using a set of tags. Unlike the LWPanelFuncs, control values use DynaValues rather than generic pointers in get() and set(). For each of the named control types (i.e. "BoolControl" ) there is an associated data type (i.e. LWT_INTEGER). This is the type of the DynaValue which must be used to get and set the value of the control. Other types may be used to set other control attributes. Again, a set of macros has been provided (e.g. SET_INT) to make this slightly prettier to code. Most controls get user input, and thus generate 'events'. If a UserEvent callback function has been installed (by using set() with CTL_USEREVENT), then it will be called for each event, and passed the LWControl, and a pointer to the data you provided to the panel create() call or re-set() with CTL_USERDATA. An exception to this is the OpenGL Control, which gets no input, and whose only 'event' is a redraw. The UserEvent function should, in this case, do your rendering. Note that to cause ANY control to draw, including OpenGL controls, you should call that control's draw() member function.

The following tags can be used with LWControls:

        CTL_VALUE         -- Control's main value, maybe a vector or other composite value type
        CTL_X, CTL_Y  -- Control's position, including margin
        CTL_LABEL         -- The text next to the the control
        CTL_USERDRAW  -- Callback function for control redraws
        CTL_USEREVENT -- Callback for events
        CTL_USERDATA  -- Pointer handed back to callbacks
        (these are read-only)
        CTL_HOTX, CTL_HOTY, CTL_HOTW, CTL_HOTH -- Clickable 'hot' area of control
        CTL_LABELWIDTH          -- Width of label area.
        CTL_FLAGS                       -- CTLF_ bits
        CTL_W, CTL_H            --      Size of control
        CTL_MOUSEX, CTL_MOUSEY  -- Mouse position at last event.
        CTL_PANEL, CTL_PANFUN   -- Originating LWPanelID and LWPanelFuncs, for convenience

DrawFuncs

The DrawFuncs struct is your access to graphics routines provided as a complimentary gift to users of the LW Panel Services. It has the following:

void drawPixel(LWPanelID pan,int c,int x,int y)
Call this to draw a pixel with color c at (x,y).
void drawRGBPixel(LWPanelID pan,int r,int g,int b,int x,int y)
Call this to draw a pixel with true color r,g,b at (x,y).
void drawLine(LWPanelID pan,int c,int x1,int y1,int x2,int y2)
Call this to draw a line with color c from (x1,y1) to (x2,y2).
void drawBox(LWPanelID pan,int c,int x,int y,int w,int h)
Call this to draw a box with color c at (x,y) with dimensions of w by h.
void drawRGBBox(LWPanelID pan,int r,int g,int b,int x,int y,int w,int h)
Call this to draw a box with true color r,g,b at (x,y) with dimensions of w by h.
void drawBorder(LWPanelID pan,int indent,int x,int y,int w,int h)
Call this to draw a border inside the given rectangle, if indent is 0, then the border will appear raised. If h is 0, the border is specially rendered as a horizontal divider.
int textWidth(LWPanelID pan,char *txt)
Return the width of the given string in pixels.
void drawText(LWPanelID pan,char *txt,int c,int x,int y)
Draw the given string at (x,y) in color c.
const DisplayMetrics *dispMetrics()
Return the ever-handy display metrics structure, which tells you how big and deep your display is, and other stuff too!

The colors used by these functions, and the DisplayMetrics definition can be found in lwpanel.h.

Get Yours Now!