treeview (lx_treeview.hpp)

From The Foundry MODO SDK wiki
Jump to: navigation, search
There are security restrictions on this page


ILxTreeView

This interace defines a TreeView client, which is able to use Python calls (or whatever) to set up a TreeView-based interface.

Objects with the ILxTreeView interface rely on the ILxTree interface as well. If both aren't available, no viewport will be defined for that server.

(1) SDK: Declarations
 #define LXu_TREEVIEW                    "8307d6f1-c30b-48e7-a0ee-aab0a45bcf1d"
 #define LXa_TREEVIEW                    "treeview"

Servers are expected to expose tags that define their viewport type. These allow them to show up as first-class viewports. Without these tags, no viewport will be defined for the server.

(2) SDK: Declarations
 #define LXsTREEVIEW_TYPE                "TreeViewType"
 #define LXsTREEVIEW_EMBEDABILITY        "TreeViewEmbedability"
 #define LXsTREEVIEW_OPTIONS_FORM        "TreeViewOptionsForm"

TYPE
This tag consists of four space-delimited strings: - The class of the viewport, mostly for organizational purposes. Options include: vp3dEdit, vptoolbars, vpproperties, vpdataLists, vpinfo, vpeditors, vputility, and vpapplication. - Exactly four characters representing the viewport's type as an LXtID4. - An internal string representing the viewport's type as a name. - A message table lookup in the form of "@table@message@"

For example: "vpapplication MYVP myViewportTypeName @myViewportTypeTable@myViewportTypeUsername@"

EMBEDABILITY
Determines how the viewport can be embedded into a Form View. Thre are three options: - "normal", which is the default mode if this tag isn't set, indicates that the viewport doesn't specifically support embedding. These can still be embedded via viewport presets, but they may not display properly. - "embedAware", meaning that the viewport knows how to handle embedding. - "embedOnly", meaning the viewport can only be embedded and cannot be used in normal layouts.
OPTIONS_FORM
A string representing the hash of a form to display when the user clicks the gear widget for the viewport. If not set, there are no options for the viewport.

These methods are called to load or save any per-instance state for the pane provided. Such state is commonly stored in the application's config.

(3) SDK: ILxTreeView interface
         LXxMETHOD(  LxResult,
 StoreState) (
         LXtObjectID              self,
         const char              *uid );
 
         LXxMETHOD(  LxResult,
 RestoreState) (
         LXtObjectID              self,
         const char              *uid );

These methods are used for controlling what columns are present in the tree view and some of their properties. ColumnCount() returns the total number of columns.

(4) SDK: ILxTreeView interface
         LXxMETHOD( LxResult,
 ColumnCount) (
         LXtObjectID              self,
         unsigned*                colCount);

This method defines the column and sets its title and width.

'buf' is a simple character buffer of length 'len' that is to be set to the human-readable title displayed in the column header, usually in the form of a "@table@msg" message table lokoup. Titles support message alternates, where the longest of the available messages that will fit is displayed in the title. The longest title is also displed in the hide/show column context menu (when you've also set an internal name with ColumnSetInternalName()). For this reason you should not encode icons in your title, instead specifying them separately via ColumnSetIconResource();

'columnWidth' returns the width of the column. Positive numbers define the width in pixels, while negative numbers will set a column's width to its relative fraction of the total remaining space. For example, two columns with widths -2 and -3 would get 2/5th and 3/5th of the width remaining in the pane after the fixed width columns are subtracted. A width of zero behaves the same as -1.

(5) SDK: ILxTreeView interface
         LXxMETHOD( LxResult,
 ColumnByIndex) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         char                    *buf,
         unsigned                 len,
         int                     *columnWidth);

nexus 10.1 introduces new column defintions that enchance the behavior of trees: - Defining any column icon separately from the title. - Column widths are remembered for you between sessions in the config. - The user can hide and show columns by right clicking in the column header. - The user can drag and drop the column headers to reorder the columns. - Column justification.

The internal name is used to store the column properties in the config in a localization-netural manner. This includes the column width, column position relative to the other columns, and if the column is hidden or visible.

It is very important that you set this for every column, or else you won't get any of those features.

(6) SDK: ILxTreeView interface
         LXxMETHOD( LxResult,
 ColumnInternalName) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         char                    *buf,
         unsigned                 len);

An optional icon resource name can also be set for the column. This will be displayed in place of the column's title if the column is too narrow for it to fit. The icon should be 13x13 pixels.

(7) SDK: ILxTreeView interface
         LXxMETHOD( LxResult,
 ColumnIconResource) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         char                    *buf,
         unsigned                 len);

This changes the justfication of the contents of the column. The primary column is always left justified, but the other columns can be centered or right justified if desired.

(8) SDK: Declarations

(9) SDK: ILxTreeView interface
         LXxMETHOD( LxResult,
 ColumnJustification) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         int                     *justification);

The final method of the treeview setup functionality is PrimaryColumnPosition. This allows you to change where in the treeview the primary column (the one with index 0 that contains the nesting) is displayed. 0 leaves it where it is, and other number pushing it that number of columns to the right.

(10) SDK: ILxTreeView interface
         LXxMETHOD( LxResult,
 PrimaryColumnPosition) (
         LXtObjectID              self,
         unsigned                *index);

Selection methods. ToPrimary should set the current referenced item to be the primary selection, and IsSelected returns LXe_TRUE or LXe_FALSE to determine whether the current item is selected or not.

Select is called when a new primary selection is made, or when additional selections are added or removed. It is up to the client to maintain the list of selected items.

(11) SDK: ILxTreeView interface
 
         LXxMETHOD(  LxResult,
 ToPrimary) (
         LXtObjectID     self);
 
         LXxMETHOD(  LxResult,
 IsSelected) (
         LXtObjectID     self);
 
         LXxMETHOD(  LxResult,
 Select) (
         LXtObjectID     self,
         unsigned        mode);

(12) SDK: Declarations

(13) SDK: ILxTreeView interface
         LXxMETHOD( LxResult,
 CellCommand) (
         LXtObjectID     self,
         unsigned        columnIndex,
         char           *buf,
         unsigned        len);
 
         LXxMETHOD( LxResult,
 BatchCommand) (
         LXtObjectID     self,
         unsigned        columnIndex,
         char           *buf,
         unsigned        len);

ToolTip can be implemented to populate a tooltip string for the curent cell.

(14) SDK: ILxTreeView interface
         LXxMETHOD( LxResult,
 ToolTip) (
         LXtObjectID     self,
         unsigned        columnIndex,
         char           *buf,
         unsigned        len);

There are 3 different badge types supported by ILxTreeView: Info badges, which are simply there or not in order to indicate state, toggle badges which can be on or off and are togglable through user selection, and star rating badges. BadgeType returns the type of badge we're dealing with with an incrementing badgeIndex. Returning zero indicates there are no further badges for the current cell.

If a badge is defined for the current cell and badgeIndex combination, BadgeDetail is then called to obtain information about that badge. ICON_ON and ICON_OFF should return a reference relevant 13x13 icons to be used by the badge. Action should return a command string that is executed when the user clicks the badge. In the case of a star badge this should be a query command that returns an integer indicating the star rating.

(15) SDK: ILxTreeView interface
         LXxMETHOD( LxResult,
 BadgeType) (
         LXtObjectID      self,
         unsigned         columnIndex,
         unsigned         badgeIndex,
         unsigned        *badgeType);
 
         LXxMETHOD( LxResult,
 BadgeDetail) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         unsigned                 badgeIndex,
         unsigned                 badgeDetail,
         char                    *buf,
         unsigned                 len);

(16) SDK: Declarations

This is used by trees containing an input map based regions. If the given cell corresponds to a region at this location, the function should return LXe_TRUE. This allows regions to be restricted to specific items, types and/or columns. Selection and command execution will automatically be performed as necessary.

(17) SDK: ILxTreeView interface
         LXxMETHOD( LxResult,
 IsInputRegion) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         unsigned                 regionID);

The following methods implement the new ILxDrop approach to drag and drop functionality. Details of the ILxDrop system can be found in awin_sdk.html

SupportedDragDropSourceTypes returns a space-seperated string of source type tags supported by the identified cell, with the GetDragDrop methods providing the source and destination COM objects for the ILxDrop system.

(18) SDK: ILxTreeView interface
         LXxMETHOD( LxResult,
 SupportedDragDropSourceTypes) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         char                    *buf,
         unsigned                 len);
 
         LXxMETHOD( LxResult,
 GetDragDropSourceObject) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         const char              *type,
         void                    **ppvObj);
 
         LXxMETHOD( LxResult,
 GetDragDropDestinationObject) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         unsigned                 location,
         void                    **ppvObj);

Empty user class.

(19) User Class: TreeView method

Empty TreeView Python user class.

(20) PY: TreeView method
 pass

ILxTreeView1 (Legacy Interface)

This interface was retired in after 901, and was replaced with an updated one that adds drop position.

(21) SDK: Declarations
 #define LXu_TREEVIEW1           "e4b1f6b4-fed6-4668-9b6b-9526b59cd9ee"

(22) SDK: ILxTreeView1 interface
         LXxMETHOD(  LxResult,
 StoreState) (
         LXtObjectID              self,
         const char              *uid );
 
         LXxMETHOD(  LxResult,
 RestoreState) (
         LXtObjectID              self,
         const char              *uid );
 
         LXxMETHOD( LxResult,
 ColumnCount) (
         LXtObjectID              self,
         unsigned*                colCount);
 
         LXxMETHOD( LxResult,
 ColumnByIndex) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         char                    *buf,
         unsigned                 len,
         int                     *columnWidth);
 
         LXxMETHOD(  LxResult,
 ToPrimary) (
         LXtObjectID     self);
 
         LXxMETHOD(  LxResult,
 IsSelected) (
         LXtObjectID     self);
 
         LXxMETHOD(  LxResult,
 Select) (
         LXtObjectID     self,
         unsigned        mode);
 
         LXxMETHOD( LxResult,
 CellCommand) (
         LXtObjectID     self,
         unsigned        columnIndex,
         char           *buf,
         unsigned        len);
 
         LXxMETHOD( LxResult,
 BatchCommand) (
         LXtObjectID     self,
         unsigned        columnIndex,
         char           *buf,
         unsigned        len);
 
         LXxMETHOD( LxResult,
 ToolTip) (
         LXtObjectID     self,
         unsigned        columnIndex,
         char           *buf,
         unsigned        len);
 
         LXxMETHOD( LxResult,
 BadgeType) (
         LXtObjectID      self,
         unsigned         columnIndex,
         unsigned         badgeIndex,
         unsigned        *badgeType);
 
         LXxMETHOD( LxResult,
 BadgeDetail) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         unsigned                 badgeIndex,
         unsigned                 badgeDetail,
         char                    *buf,
         unsigned                 len);
 
         LXxMETHOD( LxResult,
 IsInputRegion) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         unsigned                 regionID);
 
         LXxMETHOD( LxResult,
 SupportedDragDropSourceTypes) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         char                    *buf,
         unsigned                 len);
 
         LXxMETHOD( LxResult,
 GetDragDropSourceObject) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         const char              *type,
         void                    **ppvObj);
 
         LXxMETHOD( LxResult,
 GetDragDropDestinationObject) (
         LXtObjectID              self,
         unsigned                 columnIndex,
         void                    **ppvObj);

(23) Startup: Register COM translators
 {
         IxVTABLE_TreeView (TreeView1Tr, vt)
         XCOMAddTranslator  (GUIDLookup( LXu_TREEVIEW1 ), GUIDLookup( LXu_TREEVIEW ), &vt, XCOMv_IMPORT_NEW);
 }

(24) PRIV: Functions
 IxDECL_TreeView_StoreState (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->StoreState (i1, uid);
 }
 
 IxDECL_TreeView_RestoreState (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->RestoreState (i1, uid);
 }
 
 IxDECL_TreeView_ColumnCount (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->ColumnCount (i1, colCount);
 }
 
 IxDECL_TreeView_ColumnByIndex (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->ColumnByIndex (i1, columnIndex,buf,len,columnWidth);
 }
 
 IxDECL_TreeView_ColumnInternalName (TreeView1Tr)
 {
         return LXe_NOTIMPL;
 }
 
 IxDECL_TreeView_ColumnIconResource (TreeView1Tr)
 {
         return LXe_NOTIMPL;
 }
 
 IxDECL_TreeView_ColumnJustification (TreeView1Tr)
 {
         return LXe_NOTIMPL;
 }
 
 IxDECL_TreeView_PrimaryColumnPosition (TreeView1Tr)
 {
         *index = 0;
         return LXe_OK;
 }
 
 IxDECL_TreeView_ToPrimary (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->ToPrimary (i1);
 }
 
 IxDECL_TreeView_IsSelected (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->IsSelected (i1);
 }
 
 IxDECL_TreeView_Select (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->Select (i1,mode);
 }
 
 IxDECL_TreeView_CellCommand (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->CellCommand (i1,columnIndex,buf,len);
 }
 
 IxDECL_TreeView_BatchCommand (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->BatchCommand (i1,columnIndex,buf,len);
 }
 
 IxDECL_TreeView_ToolTip (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->ToolTip (i1,columnIndex,buf,len);
 }
 
 IxDECL_TreeView_BadgeType (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->BadgeType (i1,columnIndex,badgeIndex,badgeType);
 }
 
 IxDECL_TreeView_BadgeDetail (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->BadgeDetail (i1,columnIndex,badgeIndex,badgeDetail,buf,len);
 }
 
 IxDECL_TreeView_IsInputRegion (TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->IsInputRegion (i1,columnIndex,regionID);
 }
 
 IxDECL_TreeView_SupportedDragDropSourceTypes(TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->SupportedDragDropSourceTypes (i1,columnIndex,buf,len);
 }
 
 IxDECL_TreeView_GetDragDropSourceObject(TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->GetDragDropSourceObject (i1,columnIndex,type,ppvObj);
 }
 
 IxDECL_TreeView_GetDragDropDestinationObject(TreeView1Tr)
 {
         ILxTreeView1ID           i1 = XTransOther (xobj);
 
         return i1[0]->GetDragDropDestinationObject (i1,columnIndex,ppvObj);
 }