home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format 114 / af114sub.adf / GadToolsBox3.lzx / GadToolsBox3 / Developers / listview.gadget / autodocs / listview_gc.doc
Encoding:
Text File  |  1998-06-08  |  16.6 KB  |  507 lines
  1. TABLE OF CONTENTS
  2.  
  3. listview.gadget/GetListViewClass
  4. listview.gadget/listview.gadget
  5. listview.gadget/Tree_AddHead
  6. listview.gadget/Tree_AddSubHead
  7. listview.gadget/Tree_AddSubTail
  8. listview.gadget/Tree_AddTail
  9. listview.gadget/Tree_Insert
  10. listview.gadget/Tree_NewList
  11. listview.gadget/Tree_NextNode
  12. listview.gadget/Tree_NextSubNode
  13. listview.gadget/Tree_RemHead
  14. listview.gadget/Tree_Remove
  15. listview.gadget/Tree_RemSubHead
  16. listview.gadget/Tree_RemSubTail
  17. listview.gadget/Tree_RemTail
  18. listview.gadget/GetListViewClass             listview.gadget/GetListViewClass
  19.  
  20.    NAME   
  21.         GetListViewClass -- creates listview class (V37)
  22.  
  23.    SYNOPSIS
  24.         listview_class = GetListViewClass();
  25.         D0
  26.  
  27.         Class *GetListViewClass( void );
  28.  
  29.    FUNCTION
  30.         Obtains pointer to listview.gadget class for use with
  31.         intuition.library/NewObject(). Call this function only at start
  32.         of program.
  33.  
  34.    RESULT
  35.         listview_class - pointer to listview class
  36.  
  37.    SEE ALSO
  38.  
  39. listview.gadget/listview.gadget               listview.gadget/listview.gadget
  40.  
  41.    NAME   
  42.         listview.gadget -- create enchanced listview gadget (V37)
  43.  
  44.    FUNCTION
  45.         The listview class provides capability to create tree and multi
  46.         column lists and show them in BOOPSI listview gadget. Tree lists are
  47.         similiar to standard exec lists, but some changes has been made. You
  48.         can use them on standard listview gadget but then you can't use all
  49.         features of tree nodes. To browse through tree list you should use
  50.         Tree_NextNode(). This function can easly give you next open node in
  51.         tree (hidden nodes are NOT processed!). If you want browse thru all
  52.         nodes do it as in standard lists but you must check for parent nodes
  53.         (leafs are terminated by pointer to parent node). Tree node looks
  54.         like this:
  55.         
  56.             struct LVNode
  57.             {
  58.               struct LVNode *ln_Succ;  // Pointer to next node in the list.
  59.                                // If this is last node in the leaf it points
  60.                                // to the parent node, otherwise it points to
  61.                                // lh_Tail in list structure.
  62.               struct LVNode *ln_Pred;  // Pointer to previous node in the
  63.                                // list. If this is first node in tree it
  64.                                // points to the parent node, otherwise it
  65.                                // points to NULL
  66.               UWORD ln_Flags;  // Flags of the node. LV_SELECT is set if node
  67.                                // is selected. LV_OPEN is set if leaf is
  68.                                // open.
  69.               STRPTR ln_Name;  // Pointer to NULL terminated string. In
  70.                                // multicolumn lists collumns are separated
  71.                                // by special character defined in NewObject()
  72.               struct LVNode *ln_Sub;   // Pointer to sub node in the list.
  73.                                // NULL if there are no sub nodes.
  74.               struct LVNode *ln_Parent; // Pointer to parent node. NULL if
  75.                                // there is no parent nodes
  76.               UBYTE ln_Indent; // Private! Don't change. This is indent of
  77.                                // sub nodes.
  78.             };
  79.  
  80.         Why tree node linking is so strange? And why I simply don't use list
  81.         structures for sub nodes? It's easy to understand. Creating for every
  82.         leaf new list is hard to make, you need a lot of NewList()
  83.         initializations. Also, when entering to leafs you must remember
  84.         parent node. With this style of lists you can browse tree list like
  85.         normal lists (you can indicate a new leaf by checking ln_Indent
  86.         field), it's faster and easier to make such lists. Unfortunately you
  87.         need a new functions for list management. Root list is compatible
  88.         with exec list, but use Tree_#?() functions instead. You can also use
  89.         a functions designed for sub nodes on root list.
  90.         ln_Name and LIST_Format strings have basic support of formatting:
  91.         ESCc - center, ESCl - left, ESCr - right, ESC<num> - pen number (only
  92.         0 to 9), ESCp - plain, ESCb - bold, ESCi - italic, ESCu - underline.
  93.  
  94.  
  95.    TAGS
  96.         LIST_Labels (struct LVList *) - Pointer to the list of nodes.
  97.             Don't try to supply standard lists.
  98.             Default for this tag is NULL. Applicability is (IS). (V37)
  99.  
  100.         LIST_Top (ULONG) - Number of top shown node.
  101.             Default for this tag is 0. Applicability is (ISG). (V37)
  102.  
  103.         LIST_ReadOnly (BOOL) - Make listview gadget read only.
  104.             Default for this tag is FALSE. Applicability is (I). (V37)
  105.  
  106.         LIST_Border (BOOL) - Set it to FALSE if you don't want a
  107.             border around listview gadget.
  108.             Default for this tag is TRUE. Applicability is (I). (V37)
  109.  
  110.         LIST_Selected (struct LVNode *) - Returns pointer to currently
  111.             selected node in the list. In multiselect lists use LV_SELECT
  112.             flag in ln_Flags field instead.
  113.             Default for this tag is NULL. Applicability is (G). (V37)
  114.  
  115.         LIST_Columns (ULONG) - Number of columns in listview gadget.
  116.             Default for this tag is 1. Applicability is (I). (V37)
  117.  
  118.         LIST_TextFont (struct TextFont *) - Font used for rendering all
  119.             texts.
  120.             Default for this tag is NULL. Applicability is (I). (V37)
  121.  
  122.         LIST_ShowTreeLines (BOOL) - If you want lines in tree gadget set it
  123.             to TRUE.
  124.             Default for this tag is FALSE. Applicability is (IG). (V37)
  125.  
  126.         LIST_TabChar (STRPTR) - Character used to separate columns.
  127.             Default for this tag is '\t'. Applicability is (I). (V37)
  128.  
  129.         LIST_Format (STRPTR) - Pointer to titles of columns. Titles are
  130.             separated by '|' character. Set to NULL if you don't want
  131.             titles. Strings can be formatted.
  132.             Default for this tag is NULL. Applicability is (I). (V37)
  133.  
  134.         LIST_Visible (ULONG) - Number of visible lines.
  135.             Applicability is (G). (V37)
  136.  
  137.         LIST_Total (ULONG) - Number of all open nodes in the list.
  138.             Applicability is (G). (V37)
  139.  
  140.         LIST_IsTree (BOOL) - You must set this to TRUE if you use tree
  141.             lists.
  142.             Applicability is (IG). (V37)
  143.  
  144.         LIST_HookSub (struct Hook *) - Callback routine called when
  145.             leaf is opened (TLV_OPENSUB, TLVSubMsg) or closed
  146.             (TLV_CLOSESUB, TLVSubMsg). You can use this callback
  147.             to use dynamicially generated trees like directory list.
  148.             Remember: sub nodes must have at least one node (make
  149.             dummy node for this). Callback must return TLVCB_OK when
  150.             message was processed.
  151.             Applicability is (ISG). (V37)
  152.  
  153.         LIST_HookDraw (struct Hook *) - Callback routine called when
  154.             node is rendered (TLV_DRAW, TLVDrawmsg). Callback must
  155.             return TLVCB_OK when message was processed.
  156.             Applicability is (ISG). (V37)
  157.  
  158.         LIST_HookEdit (struct Hook *) - Callback routine called when
  159.             node is going to be edited and when was edited. First
  160.             TLV_DOEDIT (TLVEditMsg) method is called, you must check
  161.             tlvm_Column field end tell to listview that you want to edit
  162.             this column or not. Return TLVCB_OK to not edit column or
  163.             TLVCB_UNKNOWN to edit column.
  164.             After the node was edited TLV_EDIT method is called. You
  165.             need to manually replace tlvm_Node->ln_Name with new string
  166.             in tlvm_String adding strings from other columns. Callback
  167.             must return TLVCB_OK when message was processed.
  168.             Setting this hook makes listview editable by user.
  169.             Edit string gadget is created and added at the end of list of
  170.             all gadgets. So, use it carefully because you can remove
  171.             listview from window but string can stay in the list of
  172.             gadgets (it's only invisble for you). String is removed and
  173.             disposed when listview is disposed.
  174.             Applicability is (ISG). (V37)
  175.  
  176.         LIST_ColumnsPos (UWORD *) - Table of column positions. Column 0
  177.             has position always equal to 0 and last column always equal
  178.             to width of gadget. Two columned listview has three positions.
  179.             Applicability is (ISG). (V37)
  180.  
  181.   SEE ALSO
  182.         gadgets/listview.h
  183.  
  184. listview.gadget/Tree_AddHead                     listview.gadget/Tree_AddHead
  185.  
  186.    NAME   
  187.         Tree_AddHead -- insert node at the head of a list (V37)
  188.  
  189.    SYNOPSIS
  190.         Tree_AddHead(list,node);
  191.                      A0   A1
  192.  
  193.         void Tree_AddHead(struct LVList *,struct LVNode *);
  194.  
  195.    FUNCTION
  196.         Add a node to the head of a doubly linked list.
  197.  
  198.    INPUTS
  199.         list - a pointer to list to the target list header
  200.         node - the node to insert at head
  201.  
  202.    SEE ALSO
  203.         Tree_AddTail, Tree_Insert, Tree_Remove, Tree_RemHead,
  204.         Tree_RemTail
  205.  
  206. listview.gadget/Tree_AddSubHead               listview.gadget/Tree_AddSubHead
  207.  
  208.    NAME   
  209.         Tree_AddSubHead -- insert node at the head of a sub list (V37)
  210.  
  211.    SYNOPSIS
  212.         Tree_AddSubHead(list,parent,node);
  213.                         A0   A1     A2
  214.  
  215.         void Tree_AddSubHead(struct LVList *,struct LVNode *,struct LVNode *)
  216. ;
  217.  
  218.    FUNCTION
  219.         Add a node to the head of a sub list.
  220.  
  221.    INPUTS
  222.         list - a pointer to list to the target list header
  223.         parent - a parent node of the sub list to insert the node to
  224.                  May be NULL.
  225.         node - the node to insert at head
  226.  
  227.    SEE ALSO
  228.         Tree_AddSubTail, Tree_Insert, Tree_Remove, Tree_RemSubHead,
  229.         Tree_RemSubTail
  230.  
  231. listview.gadget/Tree_AddSubTail               listview.gadget/Tree_AddSubTail
  232.  
  233.    NAME   
  234.         Tree_AddSubTail -- append node to tail of a sub list (V37)
  235.  
  236.    SYNOPSIS
  237.         Tree_AddSubTail(list,parent,node);
  238.                         A0   A1     A2
  239.  
  240.         void Tree_AddSubTail(struct LVList *,struct LVNode *,struct LVNode *)
  241. ;
  242.  
  243.    FUNCTION
  244.         Add a node to the tail of a sub list.
  245.  
  246.    INPUTS
  247.         list - a pointer to the target list header
  248.         parent - a parent node of the sub list to append the node to.
  249.                  May be NULL.
  250.         node - a pointer to the node to insert at tail of the sub list
  251.  
  252.    SEE ALSO
  253.         Tree_AddSubHead, Tree_Insert, Tree_Remove, Tree_RemSubHead,
  254.         Tree_RemSubTail
  255.  
  256. listview.gadget/Tree_AddTail                     listview.gadget/Tree_AddTail
  257.  
  258.    NAME   
  259.         Tree_AddTail -- append node to tail of a list (V37)
  260.  
  261.    SYNOPSIS
  262.         Tree_AddTail(list,node);
  263.                      A0   A1
  264.  
  265.         void Tree_AddTail(struct LVList *,struct LVNode *);
  266.  
  267.    FUNCTION
  268.         Add a node to the tail of a doubly linked list.
  269.  
  270.    INPUTS
  271.         list - a pointer to the target list header
  272.         node - a pointer to the node to inser at tail of the list
  273.  
  274.    SEE ALSO
  275.         Tree_AddHead, Tree_Insert, Tree_Remove, Tree_RemHead,
  276.         Tree_RemTail
  277.  
  278. listview.gadget/Tree_Insert                       listview.gadget/Tree_Insert
  279.  
  280.  
  281.    NAME
  282.         Tree_Insert -- insert a node into a list or sub list (V37)
  283.  
  284.    SYNOPSIS
  285.         Tree_Insert(list, node, listNode)
  286.                     A0    A1    A2
  287.  
  288.         void Tree_Insert(struct LVList *, struct LVNode *, struct LVNode *);
  289.  
  290.    FUNCTION
  291.         Insert a node into a doubly linked list AFTER a given node
  292.         position.  Insertion at the head of a list is possible by passing a
  293.         zero value for listNode, though the AddHead function is slightly
  294.         faster for that special case.
  295.  
  296.    INPUTS
  297.         list - a pointer to the target list header
  298.         node - the node to insert
  299.         listNode - the node after which to insert
  300.  
  301.     SEE ALSO
  302.         Tree_AddHead, Tree_AddSubHead, Tree_AddSubTail, Tree_AddTail,
  303.         Tree_RemHead, Tree_Remove, Tree_RemSubHead, Tree_RemSubTail,
  304.         Tree_RemTail
  305.  
  306. listview.gadget/Tree_NewList                     listview.gadget/Tree_NewList
  307.  
  308.    NAME   
  309.         Tree_NewList -- initialize list for use (V37)
  310.  
  311.    SYNOPSIS
  312.         Tree_NewList(list);
  313.                      A0
  314.  
  315.         void Tree_NewList(struct LVList *);
  316.  
  317.    FUNCTION
  318.         Initializes list structure to use.
  319.  
  320.    INPUTS
  321.         list - a pointer to the list
  322.  
  323.    SEE ALSO
  324.  
  325. listview.gadget/Tree_NextNode                   listview.gadget/Tree_NextNode
  326.  
  327.    NAME   
  328.         Tree_NextNode -- get pointer to next node (V37)
  329.  
  330.    SYNOPSIS
  331.         nextnode = Tree_NextNode(node);
  332.         D0                       A0
  333.  
  334.         struct LVNode *Tree_NextNode(struct LVNode *);
  335.  
  336.    FUNCTION
  337.         Returns pointer to next node in the list. If node is open
  338.         it will enter in it and process sub nodes otherwise sub nodes
  339.         will be skipped.
  340.         You can simply process all open nodes using for() instruction:
  341.  
  342.         for(node=list.lh_Head;Tree_NextNode(node);node=Tree_NextNode(node))
  343.         {
  344.           // do here something with node
  345.         } 
  346.  
  347.    INPUTS
  348.         node - a pointer to the node
  349.  
  350.    RESULT
  351.         nextnode - a pointer to the next node or NULL if there is no more
  352.                    nodes
  353.  
  354.    SEE ALSO
  355.         Tree_NextSubNode
  356.  
  357. listview.gadget/Tree_NextSubNode             listview.gadget/Tree_NextSubNode
  358.  
  359.    NAME   
  360.         Tree_NextSubNode -- get pointer to next node or sub node (V37)
  361.  
  362.    SYNOPSIS
  363.         nextnode = Tree_NextSubNode(node);
  364.         D0                          A0
  365.  
  366.         struct LVNode *Tree_NextSubNode(struct LVNode *);
  367.  
  368.    FUNCTION
  369.         Returns pointer to next node in the list.
  370.         You can simply process all nodes using for() instruction:
  371.  
  372.         for(node=list.lh_Head;Tree_NextSubNode(node); \
  373.                               node=Tree_NextSubNode(node))
  374.         {
  375.           // do here something with node
  376.         } 
  377.  
  378.    INPUTS
  379.         node - a pointer to the node
  380.  
  381.    RESULT
  382.         nextnode - a pointer to the next node or NULL if there is no more
  383.                    nodes
  384.  
  385.    SEE ALSO
  386.         Tree_NextNode
  387.  
  388. listview.gadget/Tree_RemHead                     listview.gadget/Tree_RemHead
  389.  
  390.    NAME   
  391.         Tree_RemHead -- remove the head node from a list (V37)
  392.  
  393.    SYNOPSIS
  394.         node = Tree_RemHead(list);
  395.         D0                  A0
  396.  
  397.         struct LVNode *Tree_RemHead(struct LVList *);
  398.  
  399.    FUNCTION
  400.         Get a pointer to the head node and remove it from the list.
  401.  
  402.    INPUTS
  403.         list - a pointer to the target list header
  404.  
  405.    RESULT
  406.         node - the node removed or zero when empty list
  407.  
  408.    SEE ALSO
  409.         Tree_AddHead, Tree_AddTail, Tree_Insert, Tree_Remove,
  410.         Tree_RemTail
  411.  
  412. listview.gadget/Tree_Remove                       listview.gadget/Tree_Remove
  413.  
  414.    NAME   
  415.         Tree_Remove -- remove a node from a list (V37)
  416.  
  417.    SYNOPSIS
  418.         Tree_Remove(node);
  419.                     A0
  420.  
  421.         void Tree_Remove(struct LVNode *);
  422.  
  423.    FUNCTION
  424.         Unlink a node with all sub nodes whatever list it is in.
  425.         Nodes that are not part of a list must not be passed to this
  426.         function!
  427.  
  428.    INPUTS
  429.         node - the node to remove
  430.  
  431.    SEE ALSO
  432.         Tree_AddHead, Tree_AddTail, Tree_Insert, Tree_RemHead,
  433.         Tree_RemTail
  434.  
  435. listview.gadget/Tree_RemSubHead               listview.gadget/Tree_RemSubHead
  436.  
  437.    NAME   
  438.         Tree_RemSubHead -- remove the head node from a sub list (V37)
  439.  
  440.    SYNOPSIS
  441.         node = Tree_RemSubHead(node);
  442.         D0                     A0
  443.  
  444.         struct LVNode *Tree_RemSubHead(struct LVNode *);
  445.  
  446.    FUNCTION
  447.         Get a pointer to the head sub node and remove it from the list.
  448.  
  449.    INPUTS
  450.         node - a pointer to the target node header
  451.  
  452.    RESULT
  453.         node - the node removed or zero when empty list
  454.  
  455.    SEE ALSO
  456.         Tree_AddSubHead, Tree_AddSubTail, Tree_Insert, Tree_Remove,
  457.         Tree_RemSubTail
  458.  
  459. listview.gadget/Tree_RemSubTail               listview.gadget/Tree_RemSubTail
  460.  
  461.    NAME   
  462.         Tree_RemSubTail -- remove the tail node from a sub list (V37)
  463.  
  464.    SYNOPSIS
  465.         node = Tree_RemSubTail(node);
  466.         D0                     A0
  467.  
  468.         struct LVNode *Tree_RemSubTail(struct LVNode *);
  469.  
  470.    FUNCTION
  471.         Get a pointer to the tail sub node and remove it from the list.
  472.  
  473.    INPUTS
  474.         node - a pointer to the target node header
  475.  
  476.    RESULT
  477.         node - the node removed or zero when empty list
  478.  
  479.    SEE ALSO
  480.         Tree_AddSubHead, Tree_AddSubTail, Tree_Insert, Tree_Remove,
  481.         Tree_RemSubHead
  482.  
  483. listview.gadget/Tree_RemTail                     listview.gadget/Tree_RemTail
  484.  
  485.    NAME   
  486.         Tree_RemTail -- remove the tail node from a list (V37)
  487.  
  488.    SYNOPSIS
  489.         node = Tree_RemTail(list);
  490.         D0                  A0
  491.  
  492.         struct LVNode *Tree_RemTail(struct LVList *);
  493.  
  494.    FUNCTION
  495.         Get a pointer to the tail node and remove it from the list.
  496.  
  497.    INPUTS
  498.         list - a pointer to the target list header
  499.  
  500.    RESULT
  501.         node - the node removed or zero when empty list
  502.  
  503.    SEE ALSO
  504.         Tree_AddHead, Tree_AddTail, Tree_Insert, Tree_Remove,
  505.         Tree_RemHead
  506.  
  507.