channelui (lx_channelui.hpp)

From The Foundry MODO SDK wiki
(Redirected from LXu CHANNELUI (index))
Jump to: navigation, search
There are security restrictions on this page


Channel UI

The item.channel command is used to show channels as controls in the UI. For full support the channels need to provide some way to tell the UI if the channel is enabled or when the some state changes. This is done by providing an ILxChannelUI interface on the item type/package object.

(1) SDK: Declarations
 #define LXu_CHANNELUI   "d04810aa-d88a-44ef-92c2-797374b42365"
 #define LXa_CHANNELUI   "channelui"

The enable method works very much like a command enable function, and returns the same kinds of codes: LXe_CMD_DISABLED if disabled, LXe_OK for enabled and anything else for a failure code. The item type and channel name are provided as arguments, allowing the same object to handle multiple different channels.

A disable message can be returned as part of the ILxMessageID. Note that, as with commands, the code stored in the ILxMessageID should also be returned by the enable function.

The item argument may be NULL, or may be provided by the caller. The object can use this for for more specific enable tests. Note that it is valid for the item to be NULL, in which case a general test should be applied to item type itself.

(2) SDK: ILxChannelUI interface
         LXxMETHOD(  LxResult,
 Enabled) (
         LXtObjectID              self,
         const char              *channelName,
         LXtObjectID              msg,
         LXtObjectID              item,
         LXtObjectID              chanRead);

item.channel needs a way to know what other channels this channel might depend on for its enable state. The following methods are used to see if a recently changed channel is a dependency of this channel and thus control if this channel is enabled (i.e., available for user interaction) or not (i.e., "ghosted"). If the changed channel is a dependency, then this channel's UI representation is told to update it's "enabled" state with that returned by the Enabled() method.

Note that the dependency mechanism only allows watching channels on the same item. This includes allowing packages to watch for changes to channels on other packages as long as both packages are on the same item. If you need more flexibility, you'll need to implement your own notifier through the UIHints() method. The depItemType argument thus indicates a channel in different package on the item, or a supertype of the item itself.

(3) SDK: ILxChannelUI interface
         LXxMETHOD(  LxResult,
 DependencyCount) (
         LXtObjectID               self,
         const char               *channelName,
         unsigned                 *count);

(4) SDK: ILxChannelUI interface
         LXxMETHOD(  LxResult,
 DependencyByIndex) (
         LXtObjectID               self,
         const char               *channelName,
         unsigned                  index,
         LXtItemType              *depItemType,
         const char              **depChannelName);

This variation is more robust, taking an item type as a string instead of an integer code. This works well for packages, which do not support type codes. Clients only need to implement one of those, although DependencyByIndexName() is preferred.

(5) SDK: ILxChannelUI interface
         LXxMETHOD(  LxResult,
 DependencyByIndexName) (
         LXtObjectID               self,
         const char               *channelName,
         unsigned                  index,
         const char              **depItemTypeName,
         const char              **depChannelName);

Entire items can also be disabled or enabled. When disabled, all controls related to item (such as channel controls in property forms) will be considered disabled, and the item will be marked as disabled in the Item List. The item argument is the specific item being tested.

(6) SDK: ILxChannelUI interface
         LXxMETHOD(  LxResult,
 ItemEnabled) (
         LXtObjectID              self,
         LXtObjectID              msg,
         LXtObjectID              item);

An item can return a specific icon resource name based on some state, like an item tag. This isn't updated too frequently, and thus should be a relatively static icon. If this returns a failure code or is not implemented, the icon found referenced in the Item Help configs is used. The resource name should not include any size suffix (ie: return "MyItemIcon", not "MyItemIcon_20").

(7) SDK: ILxChannelUI interface
         LXxMETHOD(  LxResult,
 ItemIcon) (
         LXtObjectID               self,
         LXtObjectID               item,
         const char              **icon);

A channel's UI hints are automatically populated for it before being used for the UI. However, items further tweak these by implementing this method and setting the UI hints properties themselves.

(8) SDK: ILxChannelUI interface
         LXxMETHOD(  LxResult,
 UIHints) (
         LXtObjectID               self,
         const char               *channelName,
         LXtObjectID               hints);

Channels can similar return a specific UIValueHints object for their UI, and to provide a per-channel notifier list.

(9) SDK: ILxChannelUI interface
         LXxMETHOD(  LxResult,
 UIValueHints) (
         LXtObjectID               self,
         const char               *channelName,
         void                    **ppvObj);

ILxChannelUI1 (Legacy Interface)

(10) SDK: Declarations
 #define LXu_CHANNELUI1  "BF1BFE3B-F0F5-490b-8961-721795DA57B4"
 #define LXa_CHANNELUI1  "channelui1"

(11) SDK: ILxChannelUI1 interface
         LXxMETHOD(  LxResult,
 Enabled) (
         LXtObjectID              self,
         const char              *channelName,
         LXtObjectID              msg,
         LXtObjectID              item,
         LXtObjectID              chanRead);
 
         LXxMETHOD(  LxResult,
 DependencyCount) (
         LXtObjectID               self,
         const char               *channelName,
         unsigned                 *count);
 
         LXxMETHOD(  LxResult,
 DependencyByIndex) (
         LXtObjectID               self,
         const char               *channelName,
         unsigned                  index,
         LXtItemType              *depItemType,
         const char              **depChannelName);
 
         LXxMETHOD(  LxResult,
 ItemEnabled) (
         LXtObjectID              self,
         LXtObjectID              msg,
         LXtObjectID              item);
 
         LXxMETHOD(  LxResult,
 UIHints) (
         LXtObjectID               self,
         const char               *channelName,
         LXtObjectID               hints);
 
         LXxMETHOD(  LxResult,
 UIValueHints) (
         LXtObjectID               self,
         const char               *channelName,
         void                    **ppvObj);
 
         LXxMETHOD(  LxResult,
 Cookie) (
         LXtObjectID               self,
         const char               *channelName,
         const char               *requestedFor,
         const char              **cookie);