Panels
Availability LightWave 6.0 | Component Layout, Modeler | Header lwpanel.h
The Panels global supplies a set of routines for creating user interface windows from within plug-ins. Also see the related raster and context menu globals.
LWPanels (or the newer XPanels system) gives you a way to create interfaces for your plug-ins that have the LightWave look and feel, using a single code base for all of the platforms LightWave supports.
Creating a non-trivial user interface is a complex task that demands an understanding of both real-time, event-driven programming and of human factors (the ergonomics of the mind). Good design marries function and aesthetics, while a good implementation seeks a balance between responsiveness and power.
This page can't hope to teach any of that, of course, but it's worth mentioning that there's more to this process than the mere building blocks presented here.
If you've programmed interfaces for Microsoft Windows or Apple MacOS, you're familiar with a design method that uses resource files to define dialogs "ahead of time," or statically. When your code runs, you make an operating system call to load your dialog template and use it to create a dialog. Events are either sent to a single, central callback or are pulled by your code from an event queue.
LWPanels doesn't use dialog templates. Dialogs, or panels, are built "on the fly" by calling functions that add and position a panel's controls.. Panels are defined by a sequence of function calls rather than a list of directives in a resource file. And events may be sent to many different callbacks. You tell LWPanels where to send them.
If you're accustomed to designing dialogs in a visual environment, the LWPanels approach may take some getting used to.
Other aspects of a panel's life cycle are very similar to those for Windows or MacOS dialogs. You initialize the values of controls before the panel is displayed, and you can read back those values at any time, but in particular after the panel is closed. Interactive controls like sliders generate events while the user is modifying them, and you can respond to those events by changing the values or the appearance of other controls. You can draw on a panel, and blit bitmaps onto it.
If you haven't written an interface in another environment, your first reading of this page is likely to be overwhelming. (In fact, that may be true regardless of your previous experience.) Try looking at some of the SDK samples, particularly the ones mentioned by name at the end of this page, to get an initial idea of what's going on, and then refer back to the documentation for an explanation of anything you don't immediately understand.
Handlers whose interfaces use LWPanels will almost always
create and display their panels from within the callback you put in the options
field of the LWInterface structure. (Don't use the panel
field of that structure;
that's for xpanels.)
Global Call
LWPanelFuncs *panf; panf = global( LWPANELFUNCS_GLOBAL, GFUSE_TRANSIENT );
The global function returns a pointer to an LWPanelFuncs.
typedef struct st_LWPanelFuncs { LWPanelID (*create) (char *, void *); void (*destroy) (LWPanelID); int (*open) (LWPanelID, int flags); int (*handle) (LWPanelID, int); void (*draw) (LWPanelID, DrMode); void (*close) (LWPanelID); void (*get) (LWPanelID, pTag, void *); void (*set) (LWPanelID, pTag, void *); LWControl * (*addControl) (LWPanelID, char *type, LWPanControlDesc *, char *label); LWControl * (*nextControl) (LWPanelID, LWControlID); DrawFuncs *drawFuncs; void *user_data; GlobalFunc *globalFun; } LWPanelFuncs;
panel = create( title, panf )
- Create a panel. This allocates resources for the panel but doesn't display it.
destroy( panel )
- Free the resources allocated by
create
andaddControl
. The panel ID is no longer valid after this is called. Panels should not be destroyed while open. result = open( panel, flags )
- Display the panel. The panel and its controls must already be created, positioned,
sized, initialized and ready to go. The flags are a combination of the following.
PANF_BLOCKING
- When this is set, the panel is modal, meaning that it will be the only LightWave window
that can receive user input. The
open
function will not return until the panel has been closed. Without this flag, the panel is non-modal and theopen
function returns immediately. PANF_CANCEL
- Add a Cancel button at the bottom of the panel.
PANF_FRAME
- Add operating system-specific decoration to the panel window. This flag currently has no effect.
PANF_MOUSETRAP
- The panel wants mouse input, which will be passed to panel callbacks.
PANF_PASSALLKEYS
- The Enter and Escape keys normally close a panel. This flag allows the panel's keyboard callback to handle them instead.
PANF_ABORT
- Changes the label of the Cancel button to "Abort". This should be used with
the
PANF_CANCEL
flag. PANF_NOBUTT
- Display no buttons (no Continue or Continue/Cancel) at the bottom of the panel.
PANF_RESIZE
- Allow resizing of the panel window. When this is set, the panel will accept calls to the
set
function withPAN_W
andPAN_H
tags.
result = handle( panel, flag )
- Process user input for non-modal panels. When the panel is non-modal (opened without the
PANF_BLOCKING
flag),open
returns immediately. In order to allow user input processing to occur, the plug-in yields control by callinghandle
. Ifflag
is 0,handle
returns as soon as the event queue is empty. It returns 0 if the panel is still open, or -1 if the user has closed it. Ifflag
isEVNT_BLOCKING
,handle
won't return until the user closes the panel. draw( panel, drmode )
- Redraw the panel. LWPanels performs its own drawing and then calls your panel draw
callback, if you've set one. Any of the drawing modes described later
for controls are also valid here, but in most cases you'll use
DR_REFRESH
. close( panel )
- Close a non-modal panel. Typically users will close your panels, so you won't need to call this. A closed panel can be reopened later.
get( panel, ptag, value )
set( panel, ptag, value )- Set and retrieve various panel attributes. The
value
is the panel attribute cast as a void *. Many of the attributes are pointers to callback functions, which are described below. Theptag
identifies the attribute and can be one of the following.PAN_X, PAN_Y, PAN_W, PAN_H
- Panel position and size in pixels.
PAN_TITLE
- The panel title passed to
create
. PAN_PANFUN
(get)- The LWPanelFuncs pointer passed to
create
. PAN_FLAGS
(get)- The flags passed to the
open
function. PAN_USERDATA
- Your data pointer. This is passed as the second argument to all of the panel callbacks.
PAN_MOUSEX, PAN_MOUSEY
- The position of the mouse at the time of the most recent event, relative to the upper left corner of the panel.
PAN_QUALIFIERS
(get)- An integer containing bit flags that provide additional information about the most recent mouse event. These are the same qualifier bits that are passed to mouse callbacks.
PAN_MOUSEBUTTON, PAN_MOUSEMOVE
- Your mouse event callbacks.
PAN_USERKEYS, PAN_USERKEYUPS
- Your keyboard input callbacks.
PAN_USERDRAW
- Your panel draw callback.
PAN_USERACTIVATE, PAN_USEROPEN, PAN_USERCLOSE
- Callbacks that LWPanels calls when the panel is activated (receives input focus from the operating system), opened and closed, respectively.
PAN_VERSION
(get)- The LWPanels API version. Compare this to
LWPANELS_API_VERSION
, which is defined in lwpanel.h. PAN_RESULT
(set )- Set this to pass results when closing panels manually.
PAN_HOSTDISPLAY
(get)- A pointer to a HostDisplayInfo for the panel.
PAN_TO_FRONT
(set)- Move the panel to the top of the window z-order.
control = addControl( panel, type, ctrldesc, label )
- Add a control to a panel. Call this after the panel has been created but before it's
opened. In practice, you'll seldom call this function explicitly. For each control type,
lwpanel.h supplies a macro that calls
addControl
with the proper arguments for that control. Returns a pointer to an LWControl structure, described below. By default, each control is positioned beneath the previous one, and the panel autosizes to fit all of the controls. Controls can be moved after they're created, but internally they remain in the order in which they're created, which for example affects the drawing order. control = nextControl( panel, control )
- Enumerate the controls that have been added to a panel. Get the first control in the list by passing NULL as the second argument.
drawFuncs
- A pointer to a DrawFuncs structure, described below.
user_data
- A place to store whatever you like.
globalFun
- Set this to the GlobalFunc passed to your activation function.
Panel Callbacks
The LWPanelFuncs set
function allows you to install a number of panel
callbacks that LWPanels will call when certain events occur. You aren't required to
install any, so only use them if you need them. All panel callbacks receive as their
second argument the value you set for PAN_USERDATA
.
panhook( panel, userdata )
- This is the form of the callback for
PAN_USERACTIVATE
,PAN_USEROPEN
andPAN_USERCLOSE
. pankey( panel, userdata, key )
- The form for
PAN_USERKEYS
andPAN_USERKEYUPS
. For alphanumeric keys, the key code is just the ASCII code. lwpanel.h defines special codes for other keys. panmouse( panel, userdata, qualifiers, x, y )
- For
PAN_MOUSEBUTTON
andPAN_MOUSEMOVE
. Thex
andy
mouse positions are relative to the upper left corner of the panel. Thequalifiers
are bit flags.IQ_CTRL IQ_SHIFT IQ_ALT IQ_CONSTRAIN IQ_ADJUST MOUSE_LEFT MOUSE_MID MOUSE_RIGHT MOUSE_DOWN
pandraw( panel, userdata, drawmode )
- This is for
PAN_USERDRAW
. Thedrawmode
is the same as those used for controls and is described later.
Drawing Functions
The drawFuncs
member of LWPanelFuncs is a structure containing functions that
allow you to draw on your panel. See also the Raster Functions
global for creating and efficiently displaying bitmaps. You can call these at any time,
but in most cases you'll want to be synchronized with the redrawing done by LWPanels, and
for that you should limit drawing to panel and control draw callbacks.
typedef struct st_DrawFuncs { void (*drawPixel) (LWPanelID, int color, int x, int y); void (*drawRGBPixel)(LWPanelID, int r, int g, int b, int x, int y); void (*drawLine) (LWPanelID, int color, int x1, int y1, int x2, int y2); void (*drawBox) (LWPanelID, int color, int x, int y, int w, int h); void (*drawRGBBox) (LWPanelID, int r, int g, int b, int x, int y, int w, int h); void (*drawBorder) (LWPanelID, int indent, int x, int y, int w, int h); int (*textWidth) (LWPanelID, char *text); void (*drawText) (LWPanelID, char *text, int color, int x, int y); const LWDisplayMetrics *(*dispMetrics)(); } DrawFuncs;
drawPixel( panel, color, x, y )
drawRGBPixel( panel, r, g, b, x, y )- Draw a pixel. The coordinates are relative to the upper-left corner of the panel. The color is specified as one of the palette colors defined in lwpanel.h or as levels of red, green and blue between 0 and 255.
drawLine( panel, color, x1, y1, x2, y2 )
- Draw a line connecting the endpoints.
drawBox( panel, color, x, y, w, h )
drawRGBBox( panel, r, g, b, x, y, w, h )- Draw a solid rectangle.
drawBorder( panel, indent, x, y, w, h )
- Draw a rectangular border similar to the ones use to mark the borders of controls. The
indent
is the thickness of the border. Ifh
is 0,drawBorder
creates a horizontal divider. w = textWidth( panel, str )
- Returns the pixel width of the character string. Use this and the font height information in the LWDisplayMetrics structure to find the rectangular extent of a line of text.
drawText( panel, str, color, x, y )
- Render a line of text.
dmet = dispMetrics()
- Returns an LWDisplayMetrics structure. Except for the screen size and text height, most
of this structure is obsolete.
typedef struct st_display_Metrics { int width, height; int pixX, pixY; int maxColors, depth; int textHeight; int textAscent; } display_Metrics; #define LWDisplayMetrics display_Metrics
width, height
- The size of the screen, in pixels.
pixX, pixY
- The pixel aspect ratio. In most cases,
pixX == pixY
, indicating square pixels. maxColors, depth
- Palette size and bit depth for indexed color displays.
depth
is 0 for true color displays. textHeight
- The height of the LWPanels font in pixels.
textAscent
- Ignore this.
Controls
For each control you add to a panel, the LWPanelFuncs addControl
function
returns a pointer to an LWControl.
typedef struct st_LWControl { void (*draw)(LWControlID, DrMode); void (*get) (LWControlID, cTag, LWValue *); void (*set) (LWControlID, cTag, LWValue *); void *priv_data; } LWControl;
draw( control, drawmode )
- Draw or redraw the control. LWPanels performs its own drawing and calls your control
draw callback, if you've set one for this control. The draw mode is
one of the following.
DR_RENDER
- Draw the control normally.
DR_GHOST
- Draw the control with a disabled or ghosted appearance.
DR_ERASE
- Erase the control.
DR_REFRESH
- Redraw the control in its current state (normal, ghosted or erased).
get( control, ctag, param )
set( control, ctag, param )- Get and set control attributes, including the value of the control. The
param
is a pointer to an LWValue. Thectag
identifies the attribute and is one of the following.CTL_VALUE
- The value of the control.
CTL_LABEL
- The control label passed to
addControl
. CTL_X, CTL_Y, CTL_W, CTL_H
- The rectangular extent of the control, in pixels. This may include some padding used for
control spacing and alignment.
X
andY
are relative to the upper left corner of the panel. CTL_HOTX, CTL_HOTY, CTL_HOTW, CTL_HOTH
- The extent of the control's "hot" area. Generally this excludes the label and any padding but may include the border decoration.
CTL_LABELWIDTH
- The width of the label in pixels. Because of padding, this may differ from
W - HOTW
. CTL_MOUSEX, CTL_MOUSEY
- The position of the mouse at the time of the most recent control event, relative to the upper left corner of the panel..
CTL_FLAGS
- Flags marking the current state of the control.
CTLF_DISABLE
indicates the control is disabled, or read-only, but still visible. Disabled controls can still trigger callback events, so that, for example, you can display a message explaining why the control's functionality is unavailable.CTLF_INVISIBLE
indicates that the control has been erased.CTLF_GHOST
is a synonym forCTLF_DISABLED
. These flags will affect the draw mode passed to your control draw callbacks. CTL_USERDATA
- Your data pointer for this control. This is passed as the second argument to the control
callbacks. Note: For some control types, calling
set
with this tag (or calling theCON_SETEVENT
macro) has important side effects. Even if your userdata is NULL for those controls, you'll want to explicitly set it before opening the panel. CTL_USERDRAW
- Your control draw callback.
CTL_USEREVENT
- Your control event callback.
CTL_PANEL, CTL_PANFUN
(get)- The panel and LWPanelFuncs.
CTL_RANGEMIN, CTL_RANGEMAX
- Slider limits.
CTL_ACTIVATE
(set)- Set the input focus to this control. Only valid for edit fields.
priv_data
- An opaque pointer to data used internally by LWPanels.
Control Callbacks
The LWControl set
function allows you to install callbacks for custom drawing
related to the control and for responding to control events. These callbacks receive as
their second argument the value you set for CTL_USERDATA
.
ctlevent( control, userdata )
- This is the form of the callback for
CTL_USEREVENT
. The context of a control event will vary depending on the type of control. Sliders generate events as the user moves them, and button controls generate an event when they're pressed. ctldraw( control, userdata, drawmode )
- This is for
CTL_USERDRAW
. Thedrawmode
is one of the modes listed for thedraw
function. You can draw anywhere on the panel from within this callback.
In addition to these, several control types have type-specific callbacks. These are described in the following sections.
Macros
The lwpanel.h header file defines a set of macros that hide some of the complexity of using the LWPanels system. These macros are an integral part of the LWPanels API.
The macros require that your source declare and initialize a few variables.
static LWPanControlDesc desc; static LWValue ival = { LWT_INTEGER }, ivecval = { LWT_VINT }, fval = { LWT_FLOAT }, fvecval = { LWT_VFLOAT }, sval = { LWT_STRING };
These are used as temporary variables while setting up arguments to the panel functions.
Panel Life Cycle
Three macros are provided for creating, displaying and destroying a panel.
PAN_CREATE( pf, title )
- Calls the LWPanelFuncs
create
function. PAN_POST( pf, pan )
- Calls the LWPanelFuncs
open
function with the flags set toPANF_BLOCKING | PANF_CANCEL | PANF_FRAME
. PAN_KILL( pf, pan )
- Calls the LWPanelFuncs
destroy
function.
Panel Attributes
These macros call the LWPanelFuncs get
and set
functions for specific
attributes. An advantage of using them is that you can use constants in your source code.
The macro takes care of stuffing the value into an appropriate variable and passing a
pointer to that variable. The first two arguments to all of these functions are the
LWPanelFuncs pointer and the panel.
x = PAN_GETX( pf, pan )
y = PAN_GETY( pf, pan )
w = PAN_GETW( pf, pan )
h = PAN_GETH( pf, pan )- Get the position and size of the panel in pixels.
X
andY
are relative to the upper left corner of the screen. PAN_SETW( pf, pan, w )
PAN_SETH( pf, pan, h )
MOVE_PAN( pf, pan, x, y )- Set the position and size of the panel. Note that the panel automatically adjusts its size as controls are added to it.
PAN_SETDATA( pf, pan, userdata )
PAN_SETDRAW( pf, pan, drawFn )
PAN_SETKEYS( pf, pan, keyFn )- Set the
PAN_USERDATA
and the panel draw and key event callbacks. version = PAN_GETVERSION( pf, pan )
- Returns the version of LWPanels.
Creating Controls
After creating a panel and before displaying it, your code calls these macros to populate the panel with the elements of your interface. The first three arguments to all of these macros are
- the LWPanelFuncs returned by the global call
- the LWPanelID returned by the
create
call (or thePAN_CREATE
macro) - a string that will be used to label the control
All of these macros ultimately call the LWPanelFuncs addControl
function and
return a pointer to LWControl for the newly created control.
Edit fields
c = INT_CTL( pf, pan, label )
c = INTRO_CTL( pf, pan, label )
c = IVEC_CTL( pf, pan, label )
c = IVECRO_CTL( pf, pan, label )- Integer edit fields.
RO
is read-only, andVEC
is a group of three fields. c = FLOAT_CTL( pf, pan, label )
c = FLOATRO_CTL( pf, pan, label )
c = FVEC_CTL( pf, pan, label )
c = FVECRO_CTL( pf, pan, label )
c = DIST_CTL( pf, pan, label )
c = DVEC_CTL( pf, pan, label )- Floating point edit fields. The distance controls handle unit inputs and conversions.
c = STR_CTL( pf, pan, label, cw )
c = STRRO_CTL( pf, pan, label, cw )- String edit fields. The
cw
argument is the number of characters that should be visible, or the width of the control in characters. The string itself can be longer or shorter than this. If the fixed width of the integer and floating point controls isn't suitable, you can of course use the string controls and do the numeric conversion yourself.
Buttons
c = BUTTON_CTL( pf, pan, label )
c = WBUTTON_CTL( pf, pan, label, w )- Simple buttons. In order for these to do anything, you'll need to set an event callback
that responds when the button is pressed. The
WBUTTON
version accepts a width in pixels. c = BOOL_CTL( pf, pan, label )
c = BOOLBUTTON_CTL( pf, pan, label )
c = WBOOLBUTTON_CTL( pf, pan, label, w )- The first of these displays a checkmark, while the other two are buttons that are displayed in selected or unselected states. The underlying value is an integer set to 0 or 1.
Sliders and mouse feedback
c = SLIDER_CTL( pf, pan, label, w, min, max )
c = UNSLIDER_CTL( pf, pan, label, w, min, max )- This kind of slider is a thumb button that moves in or along a horizontal track. It has
an associated integer edit field. The
UN
version is "unbounded," meaning that values outside themin
,max
range can be entered in the edit field. The width is in pixels. c = HSLIDER_CTL( pf, pan, label, w, min, max )
c = VSLIDER_CTL( pf, pan, label, h, min, max )- Horizontal and vertical sliders, without an associated edit field. The width or height is in pixels.
c = MINISLIDER_CTL( pf, pan, label, w, min, max )
c = PERCENT_CTL( pf, pan, label )
c = ANGLE_CTL( pf, pan, label )- A minislider is a small button that captures mouse drag but doesn't move. It has an
associated integer edit field. The
w
argument is the visible width of the edit field in pixels. ThePERCENT
control is a minislider with a floating point edit field that displays the percent (%) character after the number.ANGLE
also has a floating point edit field. The value is displayed to the user in degrees, but plug-ins get and set it in radians. c = DRAGBUT_CTL( pf, pan, label, w, h )
c = VDRAGBUT_CTL( pf, pan, label )
c = HDRAGBUT_CTL( pf, pan, label )- Drag buttons are minisliders with no associated edit field.
c = AREA_CTL( pf, pan, label, w, h )
c = DRAGAREA_CTL( pf, pan, label, w, h )- These create a rectangle with a border.
AREA
controls generate mouse click events, andDRAGAREA
controls generate both click and drag events. ForAREA
, theCTL_MOUSEX
andCTL_MOUSEY
values contain click coordinates relative to the upper left corner of the control. ForDRAGAREA
,MOUSEX
andMOUSEY
are relative to the upper left corner of the panel. Use theGETV_IVEC
macro in theDRAGAREA
event callback to get an array of three integers containing control-relative mouse coordinates.
Multiple choice
c = HCHOICE_CTL( pf, pan, label, choices )
c = VCHOICE_CTL( pf, pan, label, choices )- An array of mutually exclusive boolean buttons.
c = TABCHOICE_CTL( pf, pan, label, choices )
- Similar to
HCHOICE
andVCHOICE
, but drawn to look like file folder tabs. These are generally used to switch between several sets of controls occupying the same space, like flipping to different tabbed notebook pages. You're responsible for erasing and drawing the appropriate sets of controls affected by tabbing. c = POPUP_CTL( pf, pan, label, choices )
c = WPOPUP_CTL( pf, pan, label, choices, w )
c = POPDOWN_CTL( pf, pan, label, choices )- These create scrolling popup menus. The
choices
argument is a NULL-terminated string array, and the value of the control is a 0-based index into this array. TheW
version lets you set the width in pixels.POPUP
s display the label to the left of the button and the current selection on the button face, and when opened, the position of the menu window is shifted so that the current selection is under the mouse cursor.POPDOWN
s display the label on the button face and always open with the first menu item under the cursor.
c = CUSTPOPUP_CTL( pf, pan, label, w, nameFn, countFn )- Like
WPOPUP
, but uses callbacks to fill in the menu rather than a static string array. The menu can therefore be different each time the user opens it. The value of the control is a 0-based index into the current list of menu items. The callbacks areint count( void *userdata ) char *name( void *userdata, int index )
The
userdata
is theCTL_USERDATA
for the control. If you have more than one custom popup that uses the same callbacks, you can use this to distinguish between them.count
returns the number of menu items, andname
returns an item, given a 0-based index. c = ITEM_CTL( pf, pan, label, globalFn, itemtype )
c = WITEM_CTL( pf, pan, label, globalFn, itemtype, w )
c = PIKITEM_CTL( pf, pan, label, globalFn, itemtype, w )- These are
POPUP
s that display a list of scene items. TheglobalFn
is the GlobalFunc passed to your activation function. If you set the LWPanelFuncsglobalFun
field, you can get it from there. The control value is an LWItemID cast as an int. In addition to the item types listed on the Item Info page, lwpanel.h definesLWI_IMAGE
, for a list of images, andLWI_ANY
, for a list of items of all types. Remember to include lwrender.h.PIKITEM
behaves likePOPDOWN
.
c = CHANNEL_CTL( pf, pan, label, w, h );- Displays a tree containing the channels currently in the scene. The control value is an LWChannelID cast as an int. You'll need lwenvel.h and the Channel Info global to set and make use of this value.
c = LISTBOX_CTL( pf, pan, label, w, ch, nameFn, countFn )
- A listbox is a static rectangle containing a menu with a scrollbar.
ch
is the height of the menu area of the listbox in text lines (the number of visible menu items). The callbacks are of the same form as those forCUSTPOPUP
. The value of the control is a 0-based index into the current list. After the control has been created, you must call theCON_SETEVENT
macro, or the controlset
function with theCTL_USERDATA
tag, even if your userdata is NULL.LISTBOX
controls rely on this to perform some internal initialization. c = MULTILISTBOX_CTL( pf, pan, label, w, ch, nameFn, countFn, columnFn )
- Like a listbox, but divides the text of each item into multiple columns. The
countFn
callback is the same as those forLISTBOX
andCUSTPOPUP
. The other two are of the following form.char *mname( void *userdata, int index, int column ) int colwidth( void *userdata, int index )
The name callback returns a string, given 0-based indexes for the list position and column. The column callback returns the width of each column in pixels. You can have up to ten columns. Return 0 when the column index is greater than or equal to the number of columns you want.
After the control has been created, you must call the
CON_SETEVENT
macro, or the controlset
function with theCTL_USERDATA
tag, even if your userdata is NULL.MULTILISTBOX
controls rely on this to perform some internal initialization. c = TREE_CTL( pf, pan, label, w, h, infoFn, countFn, childFn )
- A tree control is like a listbox, but with the menu items organized hierarchically.
Child nodes of the tree can be revealed, hidden and sometimes moved by the user. The value
of a tree control is a pointer to a node in your tree data, cast as an int. Trees don't
prescribe the internal form of your tree data, but you have to be able to answer the
questions about that data asked by the callbacks, which look like this.
void *child( void *userdata, void *node, int i )
- Returns a pointer to the i-th child of the node.
node
is a pointer returned by a previous call to this callback, or NULL for the root. int count( void *userdata, void *node )
- Returns the number of child nodes for a given node.
char *info( void *userdata, void *node, int *flags )
- Returns the name of the node. This is what is displayed in the tree control. If
flags
is non-zero, store theflags
value in your node data, and if it's 0, retrieve it from your data and put it intoflags
. void move( void *userdata, void *node, void *parent, int i )
- Called when the user moves a node. The node becomes the
i
-th child of theparent
node. This isn't in theTREE_CTL
macro's argument list.TREE_CTL
sets this to NULL, which prevents the user from moving your nodes. If you want to allow the user to move your nodes, use the code in the body of theTREE_CTL
macro to create the control, putting your move callback indesc.tree.moveFn
.
Color
c = RGB_CTL( pf, pan, label )
c = MINIRGB_CTL( pf, pan, label )
c = MINIHSV_CTL( pf, pan, label )
c = RGBVEC_CTL( pf, pan, label )- RGB (and HSV) levels for all of these controls are integers in the range 0 to 255. You can offer your users more sophisticated color selection by creating a button that calls the current colorpicker.
Files and directories
c = FILE_CTL( pf, pan, label, cw )
c = LOAD_CTL( pf, pan, label, cw )
c = SAVE_CTL( pf, pan, label, cw )
c = DIR_CTL( pf, pan, label, cw )- These combine a string edit field with a button that opens the file dialog.
cw
is the width of the edit field in characters.FILE
is an older control type preserved for backward compatibility. c = FILEBUTTON_CTL( pf, pan, label, w )
c = LOADBUTTON_CTL( pf, pan, label, w )
c = SAVEBUTTON_CTL( pf, pan, label, w )
c = DIRBUTTON_CTL( pf, pan, label, w )- Just the button for opening the file dialog. The label appears inside the button.
Drawing
c = TEXT_CTL( pf, pan, label, strings )
- Use this to put static lines of text on the panel.
c = BORDER_CTL( pf, pan, label, w, h )
- For drawing borders. If
h
is 0, the border is a horizontal divider. c = CANVAS_CTL( pf, pan, label, w, h )
- A bordered rectangle for convenient drawing. The width and height don't include the
border, so the rectangle
(0, 0, w-1, h-1)
(relative to the control'sHOTX
andHOTY
) lies inside the border. c = OPENGL_CTL( pf, pan, label, width, height )
- This creates and initializes an OpenGL window. LWPanels takes care of the platform specific setup for the window. You can draw in this window using standard OpenGL function calls during your event and draw callbacks for the control.
XPanels
c = XPANEL_CTL( pf, pan, label, xpanel )
- This creates an xpanel window on your panel. Anything you can put into an xpanel can be put into an xpanel control.
Control Values
These macros call the LWControl get
and set
functions with the CTL_VALUE
attribute, which is how you initialize and read back the values of your controls.
SET_STR( ctl, buf, buflen ) GET_STR( ctl, buf, buflen ) SET_INT( ctl, n ) GET_INT( ctl, n ) SET_FLOAT( ctl, f ) GET_FLOAT( ctl, f ) SET_IVEC( ctl, x, y, z ) GET_IVEC( ctl, x, y, z ) SETV_IVEC( ctl, nv ) GETV_IVEC( ctl, nv ) SET_FVEC( ctl, x, y, z ) GET_FVEC( ctl, x, y, z ) SETV_FVEC( ctl, fv ) GETV_FVEC( ctl, fv )
Control Attributes
These macros get and set other control attributes.
CON_X( ctl )
CON_Y( ctl )
CON_W( ctl )
CON_H( ctl )- Returns the position and size of the control.
CON_HOTX( ctl )
CON_HOTY( ctl )
CON_HOTW( ctl )
CON_HOTH( ctl )- Returns the position and size of the control's "hot" rectangle.
CON_LW( ctl )
- Returns the label width.
CON_PAN( ctl )
CON_PANFUN( ctl )- Returns the panel the control belongs to and the LWPanelFuncs pointer.
CON_MOUSEX( ctl )
CON_MOUSEY( ctl )- Returns mouse coordinates for the most recent mouse event.
MOVE_CON( ctl, x, y )
- Set the positon of the control relative to the upper left corner of the panel.
CON_SETEVENT( ctl, eventFn, userdata )
- Set the control's event function and
CTL_USERDATA
. Note: For some control types, calling this macro (or the control'sset
function with theCTL_USERDATA
tag) has important side effects. Even if your userdata is NULL for those controls, you'll want to explicitly set it before opening the panel. ERASE_CON( ctl )
REDRAW_CON( ctl )
GHOST_CON( ctl )
RENDER_CON( ctl )
UNGHOST_CON( ctl )- Draw or redraw the control.
ACTIVATE_CON( ctl )
- Activate the control (give the control the input focus). This is only valid for edit field controls.
History
In LightWave 7.0, LWPANELS_API_VERSION
was incremented to 19 and the PANF_NOBUTT
and PANF_RESIZE
flags were added.
Example
At least ten of the SDK samples use the LWPanels system. The panctl sample exercises LWPanels by creating an instance of every supported control type. It also demonstrates event handling for some of the interactive controls. The hello sample is the simplest example. It creates a panel with a single string control. The complete life cycle of this panel is repeated in the following code fragment.
#include <lwserver.h> #include <lwpanel.h> LWPanelFuncs *panf; LWPanelID panel; LWControl *ctl; LWPanControlDesc desc; LWValue sval = { LWT_STRING }; char edit[ 80 ] = "This is an edit field."; panf = global( LWPANELFUNCS_GLOBAL, GFUSE_TRANSIENT ); if ( !panf ) return AFUNC_BADGLOBAL; panel = PAN_CREATE( panf, "Hello World!" ); if ( !panel ) return AFUNC_BADGLOBAL; ctl = STR_CTL( panf, panel, "Edit Me", 40 ); SET_STR( ctl, edit, sizeof( edit )); if ( panf->open( panel, PANF_BLOCKING | PANF_CANCEL )) GET_STR( ctl, edit, sizeof( edit )); PAN_KILL( panf, panel );