COMList-class          package:RDCOMClient          R Documentation

_C_O_M_L_i_s_t  _c_o_l_l_e_c_t_i_o_n _t_y_p_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     The COMList type is used in R to represent a COM type which has
     both a Count() and Item() method. Such a type arises frequentyly
     in Office applications such as Excel and Word for representing
     collections or orderd lists of COM objects.  For example,
     Workbooks is a list of Workbook objects, Worksheets is a
     collection of Worksheet objects, and Addins is a collection of
     Addin objects. This class provides a way to treat such a container
     as an R list with methods to compute the length, access elements
     by index, and iterate over the elements using the s/lapply
     functions. For each of these, we never convert the list to an R
     list, but perform the computations via the COM methods.

     The 'COMTypedList-class' class is an extension of COMList and
     should be considered a virtual class. (It is not for
     implementation reasons only.) This class has the property that
     when one extracts individual elements from the container in R, the
     class of that  resulting R object is determined from the class of
     the COMTypedList.  This is done in a very simple fashion by
     translating the name of the COMTypedList to its singular form (in
     English). So for a COMTypedList of class 'Workbooks', say, the
     expression  'x[[1]]' would result in an object of class
     'Workbook'. It does this computation dynamically. An extension of
     the class could compute this value at the time of definition and
     use that explicitly.  This is an example of the utility for class
     slots.

     The COMTypedList should be treated as virtual. One should define
     an extension of this and the associated class for the elements in
     tandem, e.g. 'setClass("Workbooks", contains = "COMTypedList")'
     and 'setClass("Workbook", contains = "COMIDispatch")'.

_O_b_j_e_c_t_s _f_r_o_m _t_h_e _C_l_a_s_s:

     The constructor function   'COMList' should be used to create
     objects of either of these types. Alternatively, one can use the
     canonical form 'new("COMList", comObject)'.

_S_l_o_t_s:


     '_r_e_f': Object of class '"externalptr"'. This is inherited from the
          base class 'COMIDispatch-class'.

_E_x_t_e_n_d_s:

     Class '"COMIDispatch"', directly. Class '"IUnknown"', by class
     '"COMIDispatch"'.

_M_e_t_h_o_d_s:


     [[ 'signature(x = "COMList", i = "numeric")': this is the method
          to access an individual element in the COM container.  This
          amounts to a call to the method 'Item' in the COM object.

     [[<- 'signature(x = "COMList", i = "numeric")': this sets the
          value of an individual element in the COM container. In
          general, this does nothing except return the 'COMList' object
          so that we can  make inline'd assigments of the form
          'docs[[1]][["Range"]][["Text"]] = "Some text"' and have the
          'docs[[1]]' perform correctly.

     _l_a_p_p_l_y 'signature(X = "COMList")': this iterates over the elements
          of the list and invokes the specified function with that
          element as the first argument.  See 'lapply'

     _s_a_p_p_l_y 'signature(X = "COMList")': a version of 'sapply' that we
          currently need to copy to here. 

     _l_e_n_g_t_h 'signature(x = "COMList")': computes the number of elements
          currently in the container.

_A_u_t_h_o_r(_s):

     Duncan Temple Lang <duncan@wald.ucdavis.edu>

_R_e_f_e_r_e_n_c_e_s:

     Excel types. <URL: http://www.omegahat.org/RDCOMClient>

_S_e_e _A_l_s_o:

     'COMList'   '.COM' 'COMTypedList-class'  
     'COMTypedNamedList-class'

_E_x_a_m_p_l_e_s:

     ## Not run: 
       e = COMCreate("Excel.Application")
       e$Workbooks()$Add()
       e$Workbooks()$Add()

       l = COMList(e$Workbooks())
       length(l)  # should be 2
       l[[1]]  # First Workbook

       setClass("Workbooks", contains = "COMTypedList")
       setClass("Workbook", contains = "COMIDispatch")

       l = COMList(e$Workbooks, "Workbooks")
       l[[1]]  # class is "Workbook"
     ## End(Not run)

