### 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. | Global Call Panel Callbacks Drawing Functions Controls Control Callbacks Macros Panel Life Cycle Panel Attributes Creating Controls Edit fields Buttons Sliders and mouse feedback Multiple choice Color Files and directories Drawing XPanels Control Values Control Attributes History Example
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` and `addControl`. 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 the `open` 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 with `PAN_W` and `PAN_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 calling `handle`. If `flag` 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. If `flag` is `EVNT_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. The `ptag` 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, PAN_MOUSEWHEEL` 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` and `PAN_USERCLOSE`. `pankey( panel, userdata, key )` The form for `PAN_USERKEYS` and `PAN_USERKEYUPS`. For alphanumeric keys, the key code is just the ASCII code. lwpanel.h defines special codes for other keys. A value of '1' should be returned if the key was processed, or '0' if not. `panmouse( panel, userdata, qualifiers, x, y )` For `PAN_MOUSEBUTTON`, `PAN_MOUSEMOVE` and `PAN_MOUSEWHEEL`. The `x` and `y` mouse positions are relative to the upper left corner of the panel. For `PAN_MOUSEBUTTON` and `PAN_MOUSEMOVE`, the `qualifiers` are bit flags.
          IQ_CTRL
          IQ_SHIFT
          IQ_ALT
          IQ_CONSTRAIN
          IQ_ADJUST
          MOUSE_LEFT
          MOUSE_MID
          MOUSE_RIGHT
          MOUSE_DOWN
For `PAN_MOUSEWHEEL`, the `qualifiers` value is an integer count of the number of clicks made by the mouse wheel. The sign of the value indicates the direction the mouse wheel moved. `pandraw( panel, userdata, drawmode )` This is for `PAN_USERDRAW`. The `drawmode` 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. If `h` 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. The `ctag` 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` and `Y` 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, CTL_MOUSEBUTTON` The position of the mouse at the time of the most recent control event, relative to the upper left corner of the panel and which mouse button was used in selecting.. `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 for `CTLF_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 the `CON_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`. The `drawmode` is one of the modes listed for the `draw` 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 to `PANF_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` and `Y` 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 the `PAN_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, and `VEC` 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 the `min`, `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 ) c = DISTSLIDER_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. The `PERCENT` 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. The `DISTSLIDER_CTL` control is a minislider with a floating point edit field that displays the current unit type after the number and handles the conversion. `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, and `DRAGAREA` controls generate both click and drag events. For `AREA`, the `CTL_MOUSEX` and `CTL_MOUSEY` values contain click coordinates relative to the upper left corner of the control. For `DRAGAREA`, `MOUSEX` and `MOUSEY` are relative to the upper left corner of the panel. Use the `GETV_IVEC` macro in the `DRAGAREA` 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` and `VCHOICE`, 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. The `W` 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 are
      int count( void *userdata )
      char *name( void *userdata, int index )
  The `userdata` is the `CTL_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, and `name` 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. The `globalFn` is the GlobalFunc passed to your activation function. If you set the LWPanelFuncs `globalFun` field, you can get it from there. The control value is an LWItemID given as a pointer. In addition to the item types listed on the Item Info page, lwpanel.h defines `LWI_IMAGE`, for a list of images, and `LWI_ANY`, for a list of items of all types. Remember to include lwrender.h. `PIKITEM` behaves like `POPDOWN`. `c = CHANNEL_CTL( pf, pan, label, w, h );` Displays a tree containing the channels currently in the scene. The control value is an LWChannelID given as a pointer. 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 for `CUSTPOPUP`. The value of the control is a 0-based index into the current list. After the control has been created, you must call the `CON_SETEVENT` macro, or the control `set` function with the `CTL_USERDATA` tag, even if your userdata is NULL. `LISTBOX` controls rely on this to perform some internal initialization. `c = MULTILIST_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 for `LISTBOX` and `CUSTPOPUP`. 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 control `set` function with the `CTL_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, which can be obtained and set through `GET_ADDR()` and `SET_ADDR()`. 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 the `flags` value in your node data, and if it's 0, retrieve it from your data and put it into `flags`. `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 the `parent` node. This isn't in the `TREE_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 the `TREE_CTL` macro to create the control, putting your move callback in `desc.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's `HOTX` and `HOTY`) 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_ADDR( ctl, p )                 GET_ADDR( ctl, p )
       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. These have been modified in LW8.2 to support the LWT_POINTER data type for 64-bit compatability. `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's `set` function with the `CTL_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. In LightWave® 9.6, `LWPANELS_API_VERSION` was incremented to 20 and the `DISTSLIDER_CTL` and `CTL_MOUSEBUTTON` tag and enumerations 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 );