README-introspection

   1 Today is 20180412.  If that seems a long time ago, this document might
   2 be outdated.
   3
   4 Note: For tests you must either "make install" first or else run the
   5 python script via the corresponding *.pl file.
   6
   7 test/t3001-introspection-simple.py shows a sample of using introspection
   8 to work with a spreadsheet.
   9
  10 test/t3002-introspection-io.py shows a sample of using introspection
  11 to load and save files.
  12
  13
  14 The following is a list of types and the API that is expected to both
  15 be useful in this setting and actually work.
  16
  17 This is incomplete.  In particular, I'll have to look at
  18 * Expressions other than via text
  19 * Installing a gi override module for more pythony structure handling
  20
  21 -----------------------------------------------------------------------------
  22 Note: the Python version of type names excludes the Gnm prefix.
  23
  24 Workbook: [GObject, derived from GODoc]
  25   new_with_sheets(count)
  26   sheet_by_index(no)
  27   sheet_by_name(string)
  28   recalc()
  29   recalc_all()
  30   cells(qcomments,visibility)
  31   props.recalc_mode
  32
  33
  34 GODoc: [GObject]
  35   props.uri
  36   props.dirty
  37   props.pristine
  38
  39
  40 WorkbookView: [GObject]
  41   new_from_uri(uri,opener,iocontext,encoding)
  42   save(cmdctx)
  43   save_as(uri,saver,cmdctx)
  44   props.workbook
  45   props.preferred_width
  46   props.preferred_height
  47
  48
  49 Sheet: [GObject]
  50   get_size()
  51   cell_set_value(col,row,value)      [1]
  52   cell_set_text(col,row,string)      [1]
  53   cell_get_value(col,row)
  54   cell_get(col,row)
  55   cell_fetch(col,row)
  56   cells(range)
  57   cells_count()
  58   is_cell_empty(col,row)
  59   apply_style(range,style)           [1]
  60   style_get(col,row)
  61   col_is_hidden(col)
  62   row_is_hidden(row)
  63   col_get_info(col)
  64   row_get_info(row)
  65   col_set_size_pts(col,pts)
  66   row_set_size_pts(row,pts)
  67   col_set_size_pixels(col,pix)
  68   row_set_size_pixels(row,pix)
  69   col_size_fit_pixels(col,startrow,endrow,ignorestrings)
  70   row_size_fit_pixels(row,startcol,endcol,ignorestrings)
  71   props.name
  72   props.workbook
  73   props.rtl
  74   props.visibility
  75   props.display_formulas
  76   props.display_zeros
  77   props.display_grid
  78   props.display_column_header
  79   props.display_row_header
  80   props.display_outlines
  81   props.display_outlines_below
  82   props.display_outlines_right
  83   props.protected
  84   props.protected_allow_edit_objects
  85   props.protected_allow_edit_scenarios
  86   props.protected_allow_cell_formatting
  87   props.protected_allow_column_formatting
  88   props.protected_allow_row_formatting
  89   props.protected_allow_insert_columns
  90   props.protected_allow_insert_rows
  91   props.protected_allow_insert_hyperlinks
  92   props.protected_allow_delete_columns
  93   props.protected_allow_delete_rows
  94   props.protected_allow_select_locked_cells
  95   props.protected_allow_sort_ranges
  96   props.protected_allow_edit_auto_filters
  97   props.protected_allow_edit_pivottable
  98   props.protected_allow_select_unlocked_cells
  99   props.use_r1c1
 100   props.tab_foreground
 101   props.tab_background
 102   props.zoom_factor
 103   props.columns
 104   props.rows
 105
 106
 107 GnmCell: [Boxed structure] [2]
 108   name()
 109   get_value()
 110   get_entered_text()
 111   get_format()
 112   pos
 113
 114
 115 ColRowInfo: [Boxed structure]
 116   is_default()
 117   is_empty()
 118
 119 GnmSheetSize: [Simple structure]
 120   max_cols
 121   max_rows
 122
 123
 124 GnmValue: [Boxed union]
 125   new_int(int)
 126   new_bool(bool)
 127   new_float(double)
 128   new_string(string)
 129   new_empty()
 130   get_as_string()
 131   get_as_int()
 132   get_as_float()
 133   type_of()
 134   hash()
 135
 136
 137 GnmValueType: [Enum]
 138   EMPTY
 139   BOOLEAN
 140   FLOAT
 141   ERROR
 142   STRING
 143   CELLRANGE
 144   ARRAY
 145
 146
 147 GnmRange: [Simple structure]
 148   init(col,row,col,row)
 149   init_full_sheet(sheet)
 150   init_cols(sheet,start,end)
 151   init_rows(sheet,start,end)
 152   init_cellpos(sheet,cellpos)
 153   is_singleton()
 154   is_full(sheet,horiz)
 155   contained(other)
 156   as_string()
 157   start
 158   end
 159
 160
 161 GnmCellPos: [Simple structure]
 162   col
 163   row
 164
 165
 166 GnmSheetVisibility: [Enum]
 167   VISIBLE
 168   HIDDEN
 169   VERY_HIDDEN
 170
 171
 172 PasteFlags: [Enum]
 173   CONTENTS
 174   AS_VALUES
 175   FORMATS
 176   COMMENTS
 177   OBJECTS
 178   OPER_ADD
 179   OPER_SUB
 180   OPER_MULT
 181   OPER_DIV
 182   TRANSPOSE
 183   LINK
 184   SKIP_BLANKS
 185   DONT_MERGE
 186   IGNORE_COMMENTS_AT_ORIGIN
 187   UPDATE_ROW_HEIGHT
 188   EXPR_LOCAL_RELOCATE
 189   NO_RECALC
 190   FLIP_H
 191   FLIP_V
 192   ALL_TYPES
 193   DEFAULT
 194
 195
 196 GnmStyle: [Boxed structure]
 197   new()
 198   new_default()
 199   is_complete()
 200   is_element_set()
 201   unset_element()
 202   set_pattern(int)
 203   get_pattern()
 204   set_font_name(string)
 205   get_font_name()
 206   set_font_bold(bool)
 207   get_font_bold()
 208   set_font_italic(bool)
 209   get_font_italic()
 210   set_font_uline(uline)
 211   get_font_uline()
 212   set_font_strike(bool)
 213   get_font_strike()
 214   set_font_script(script)
 215   get_font_script()
 216   set_font_size(pts)
 217   get_font_size()
 218   set_format(fmt)
 219   set_format_text(fmtstring)
 220   get_format()
 221   set_align_h(halign)
 222   get_align_h()
 223   set_align_v(valign)
 224   get_align_v()
 225   set_indent(int)
 226   get_indent()
 227   set_rotation(degs)
 228   get_rotation()
 229   set_text_dir(dir)
 230   get_text_dir()
 231   set_text_wrap(bool)
 232   get_text_wrap()
 233   set_shrink_to_fit(bool)
 234   get_shrink_to_fit()
 235   set_contents_locked(bool)
 236   get_contents_locked()
 237   set_contents_hidden(bool)
 238   get_contents_hidden()
 239   get_effective_text_wrap()
 240   visible_in_blank()
 241
 242
 243 GOFormat: [Boxed structure]
 244   new_from_XL(string)
 245   as_XL()
 246   general
 247   empty
 248   default_date
 249   default_time
 250   default_date_time
 251   default_percentage
 252   default_money
 253   default_accounting
 254   is_invalid
 255   is_general
 256   is_markup
 257   is_text
 258   is_var_width
 259   is_date
 260   is_time
 261   month_before_day
 262   has_hour
 263   has_minute
 264   inc_precision
 265   dec_precision
 266   toggle_1000sep
 267
 268
 269 GOIOContext: [GObject]
 270   new(cmdctx)
 271
 272
 273 GnmCmdContextStderr: [GObject]
 274   new()
 275
 276
 277 GOFileSaver: [GObject]
 278   get_default()
 279   for_file_name(filename_or_uri)
 280   for_mime_type(mimetype)
 281   for_id(saverid)
 282   props.id,
 283   props.mime_type
 284   props.extension
 285   props.description
 286   props.overwrite
 287   props.interactive_only
 288   props.format_level
 289   props.scope
 290
 291
 292 GOFileOpener: [GObject]
 293   get_suffixes()
 294   get_mimes()
 295   props.id,
 296   props.description
 297   props.interactive_only
 298
 299
 300 GOFileFormatLevel: [Enum]
 301   NONE
 302   WRITE_ONLY
 303   NEW
 304   MANUAL
 305   MANUAL_REMEMBER
 306   AUTO
 307   LAST
 308
 309
 310 Gnm (i.e., not in a class):
 311   clipboard_copy_range(sheet,range)
 312   plugins_init(cmdctx)
 313
 314
 315 GOffice (i.e., not in a class):
 316   filename_to_uri(filename)
 317   get_file_savers()
 318   get_file_openers()
 319
 320
 321
 322 Footnotes:
 323 [1] This function is not calling the obvious C function, but uses
 324     introspection's rename-to feature to present a better API.
 325 [2] Cells are owned by the sheet.  GnmCell's boxed type uses no-op
 326     copying and freeing.