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