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   props.name
  62   props.workbook
  63   props.rtl
  64   props.visibility
  65   props.display_formulas
  66   props.display_zeros
  67   props.display_grid
  68   props.display_column_header
  69   props.display_row_header
  70   props.display_outlines
  71   props.display_outlines_below
  72   props.display_outlines_right
  73   props.protected
  74   props.protected_allow_edit_objects
  75   props.protected_allow_edit_scenarios
  76   props.protected_allow_cell_formatting
  77   props.protected_allow_column_formatting
  78   props.protected_allow_row_formatting
  79   props.protected_allow_insert_columns
  80   props.protected_allow_insert_rows
  81   props.protected_allow_insert_hyperlinks
  82   props.protected_allow_delete_columns
  83   props.protected_allow_delete_rows
  84   props.protected_allow_select_locked_cells
  85   props.protected_allow_sort_ranges
  86   props.protected_allow_edit_auto_filters
  87   props.protected_allow_edit_pivottable
  88   props.protected_allow_select_unlocked_cells
  89   props.use_r1c1
  90   props.tab_foreground
  91   props.tab_background
  92   props.zoom_factor
  93   props.columns
  94   props.rows
  95
  96
  97 GnmCell: [Boxed structure] [2]
  98   name()
  99   get_value()
 100   get_entered_text()
 101   get_format()
 102   pos
 103
 104
 105 GnmSheetSize: [Simple structure]
 106   max_cols
 107   max_rows
 108
 109
 110 GnmValue: [Boxed union]
 111   new_int(int)
 112   new_bool(bool)
 113   new_float(double)
 114   new_string(string)
 115   new_empty()
 116   get_as_string()
 117   get_as_int()
 118   get_as_float()
 119   type_of()
 120   hash()
 121
 122
 123 GnmValueType: [Enum]
 124   EMPTY
 125   BOOLEAN
 126   FLOAT
 127   ERROR
 128   STRING
 129   CELLRANGE
 130   ARRAY
 131
 132
 133 GnmRange: [Simple structure]
 134   init(col,row,col,row)
 135   init_full_sheet(sheet)
 136   init_cols(sheet,start,end)
 137   init_rows(sheet,start,end)
 138   init_cellpos(sheet,cellpos)
 139   as_string()
 140   start
 141   end
 142
 143
 144 GnmCellPos: [Simple structure]
 145   col
 146   row
 147
 148
 149 GnmSheetVisibility: [Enum]
 150   VISIBLE
 151   HIDDEN
 152   VERY_HIDDEN
 153
 154
 155 PasteFlags: [Enum]
 156   CONTENTS
 157   AS_VALUES
 158   FORMATS
 159   COMMENTS
 160   OBJECTS
 161   OPER_ADD
 162   OPER_SUB
 163   OPER_MULT
 164   OPER_DIV
 165   TRANSPOSE
 166   LINK
 167   SKIP_BLANKS
 168   DONT_MERGE
 169   IGNORE_COMMENTS_AT_ORIGIN
 170   UPDATE_ROW_HEIGHT
 171   EXPR_LOCAL_RELOCATE
 172   NO_RECALC
 173   FLIP_H
 174   FLIP_V
 175   ALL_TYPES
 176   DEFAULT
 177
 178
 179 GnmStyle: [Boxed structure]
 180   new()
 181   new_default()
 182   is_complete()
 183   is_element_set()
 184   unset_element()
 185   set_pattern(int)
 186   get_pattern()
 187   set_font_name(string)
 188   get_font_name()
 189   set_font_bold(bool)
 190   get_font_bold()
 191   set_font_italic(bool)
 192   get_font_italic()
 193   set_font_uline(uline)
 194   get_font_uline()
 195   set_font_strike(bool)
 196   get_font_strike()
 197   set_font_script(script)
 198   get_font_script()
 199   set_font_size(pts)
 200   get_font_size()
 201   set_format(fmt)
 202   set_format_text(fmtstring)
 203   get_format()
 204   set_align_h(halign)
 205   get_align_h()
 206   set_align_v(valign)
 207   get_align_v()
 208   set_indent(int)
 209   get_indent()
 210   set_rotation(degs)
 211   get_rotation()
 212   set_text_dir(dir)
 213   get_text_dir()
 214   set_text_wrap(bool)
 215   get_text_wrap()
 216   set_shrink_to_fit(bool)
 217   get_shrink_to_fit()
 218   set_contents_locked(bool)
 219   get_contents_locked()
 220   set_contents_hidden(bool)
 221   get_contents_hidden()
 222   get_effective_text_wrap()
 223   visible_in_blank()
 224
 225
 226 GOFormat: [Boxed structure]
 227   new_from_XL(string)
 228   as_XL()
 229   general
 230   empty
 231   default_date
 232   default_time
 233   default_date_time
 234   default_percentage
 235   default_money
 236   default_accounting
 237   is_invalid
 238   is_general
 239   is_markup
 240   is_text
 241   is_var_width
 242   is_date
 243   is_time
 244   month_before_day
 245   has_hour
 246   has_minute
 247   inc_precision
 248   dec_precision
 249   toggle_1000sep
 250
 251
 252 GOIOContext: [GObject]
 253   new(cmdctx)
 254
 255
 256 GnmCmdContextStderr: [GObject]
 257   new()
 258
 259
 260 GOFileSaver: [GObject]
 261   get_default()
 262   for_file_name(filename_or_uri)
 263   for_mime_type(mimetype)
 264   for_id(saverid)
 265   props.id,
 266   props.mime_type
 267   props.extension
 268   props.description
 269   props.overwrite
 270   props.interactive_only
 271   props.format_level
 272   props.scope
 273
 274
 275 GOFileOpener: [GObject]
 276   get_suffixes()
 277   get_mimes()
 278   props.id,
 279   props.description
 280   props.interactive_only
 281
 282
 283 GOFileFormatLevel: [Enum]
 284   NONE
 285   WRITE_ONLY
 286   NEW
 287   MANUAL
 288   MANUAL_REMEMBER
 289   AUTO
 290   LAST
 291
 292
 293 Gnm (i.e., not in a class):
 294   clipboard_copy_range(sheet,range)
 295   plugins_init(cmdctx)
 296
 297
 298 GOffice (i.e., not in a class):
 299   filename_to_uri(filename)
 300   get_file_savers()
 301   get_file_openers()
 302
 303
 304
 305 Footnotes:
 306 [1] This function is not calling the obvious C function, but uses
 307     introspection's rename-to feature to present a better API.
 308 [2] Cells are owned by the sheet.  GnmCell's boxed type uses no-op
 309     copying and freeing.