introspection/README

   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_CELL
 193   ALL_SHEET
 194   DEFAULT
 195
 196
 197 GnmStyle: [Boxed structure]
 198   new()
 199   new_default()
 200   is_complete()
 201   is_element_set()
 202   unset_element()
 203   set_pattern(int)
 204   get_pattern()
 205   set_font_name(string)
 206   get_font_name()
 207   set_font_bold(bool)
 208   get_font_bold()
 209   set_font_italic(bool)
 210   get_font_italic()
 211   set_font_uline(uline)
 212   get_font_uline()
 213   set_font_strike(bool)
 214   get_font_strike()
 215   set_font_script(script)
 216   get_font_script()
 217   set_font_size(pts)
 218   get_font_size()
 219   set_format(fmt)
 220   set_format_text(fmtstring)
 221   get_format()
 222   set_align_h(halign)
 223   get_align_h()
 224   set_align_v(valign)
 225   get_align_v()
 226   set_indent(int)
 227   get_indent()
 228   set_rotation(degs)
 229   get_rotation()
 230   set_text_dir(dir)
 231   get_text_dir()
 232   set_text_wrap(bool)
 233   get_text_wrap()
 234   set_shrink_to_fit(bool)
 235   get_shrink_to_fit()
 236   set_contents_locked(bool)
 237   get_contents_locked()
 238   set_contents_hidden(bool)
 239   get_contents_hidden()
 240   get_effective_text_wrap()
 241   visible_in_blank()
 242
 243
 244 GOFormat: [Boxed structure]
 245   new_from_XL(string)
 246   as_XL()
 247   general
 248   empty
 249   default_date
 250   default_time
 251   default_date_time
 252   default_percentage
 253   default_money
 254   default_accounting
 255   is_invalid
 256   is_general
 257   is_markup
 258   is_text
 259   is_var_width
 260   is_date
 261   is_time
 262   month_before_day
 263   has_hour
 264   has_minute
 265   inc_precision
 266   dec_precision
 267   toggle_1000sep
 268
 269
 270 GOIOContext: [GObject]
 271   new(cmdctx)
 272
 273
 274 GnmCmdContextStderr: [GObject]
 275   new()
 276
 277
 278 GOFileSaver: [GObject]
 279   get_default()
 280   for_file_name(filename_or_uri)
 281   for_mime_type(mimetype)
 282   for_id(saverid)
 283   props.id,
 284   props.mime_type
 285   props.extension
 286   props.description
 287   props.overwrite
 288   props.interactive_only
 289   props.format_level
 290   props.scope
 291
 292
 293 GOFileOpener: [GObject]
 294   get_suffixes()
 295   get_mimes()
 296   props.id,
 297   props.description
 298   props.interactive_only
 299
 300
 301 GOFileFormatLevel: [Enum]
 302   NONE
 303   WRITE_ONLY
 304   NEW
 305   MANUAL
 306   MANUAL_REMEMBER
 307   AUTO
 308   LAST
 309
 310
 311 Gnm (i.e., not in a class):
 312   clipboard_copy_range(sheet,range)
 313   plugins_init(cmdctx)
 314
 315
 316 GOffice (i.e., not in a class):
 317   filename_to_uri(filename)
 318   get_file_savers()
 319   get_file_openers()
 320
 321
 322
 323 Footnotes:
 324 [1] This function is not calling the obvious C function, but uses
 325     introspection's rename-to feature to present a better API.
 326 [2] Cells are owned by the sheet.  GnmCell's boxed type uses no-op
 327     copying and freeing.