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