\input texinfo @c -*- texinfo -*-
@c GNU Spread Sheet Widget documentation
@c Copyright (C) 2017, 2020  John Darrington
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3
@c or any later version published by the Free Software Foundation;
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c A copy of the license is included in the section entitled "GNU
@c Free Documentation License".

@c %**start of header
@setfilename spread-sheet-widget.info
@settitle Spread Sheet Widget

@include version.texi

@dircategory Development
@direntry
* SpreadSheetWidget: (ssw).             A Spread Sheet Widget
@end direntry

@copying
This manual is for GNU Spread Sheet Widget version @value{VERSION}.

Copyright @copyright{} 2017, 2020  John Darrington

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
@end quotation
@end copying

@titlepage
@title Spread Sheet Widget
@subtitle GNU Spread Sheet Widget
@subtitle Release @value{VERSION}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top GNU Spread Sheet Widget
@insertcopying
@end ifnottex


@chapter Introduction

@section About this Manual
This manual documents the capabilities and the programming interface of
GNU Spread Sheet Widget (version @value{VERSION}).
It assumes that the reader is already familiar with elementary computer usage,
the C programming language and with simple programming using Gtk+ version 3.


@section About Spread Sheet Widget
GNU Spread Sheet Widget is a library providing a Gtk+ widget which can be
used by applications to present numerical and alpha-numerical data in a
rectangular grid similar to that used by modern spread sheet applications.
It also provides a user interface to facilitate the creation of new data and
the manipulation and deletion of existing data by the application's user.

Spread Sheet Widget aspires to be as fast as possible and it avoids allocating
memory except when necessary.
This makes it suitable for use with very large amounts of data.

Spread Sheet Widget is not a spread sheet application.
It does not provide any facilities for arithmetic or other mathematical
operations on the data which it displays.

@chapter Programming with Spread Sheet Widget.

@section Installing the Spread Sheet Widget Library

Clearly, before one can start programming with the library it has to be
installed.

If your operating system has already installed Spread Sheet Widget, then you
need not bother installing it yourself.
Note however that many popular operating systems provide separate @dfn{runtime} and
@dfn{development}
packages; the development package often denoted with the prefix/suffix ``-dev'' or ``-devel''.
In order to write code using the library one needs the development version.

Otherwise, you may install the library as you would with any other:
@example
./configure
make
# become root
make install
@end example
@noindent
This process is described in excruciating detail in @file{INSTALL} and will
not be further discussed here.

@section Getting Started

A simple program using Spread Sheet Widget is as follows:
@example
@verbatiminclude prog1.c-enum
@end example
@noindent
On a standard GNU/Linux system you can compile this program with a command
such as @samp{gcc $(pkg-config --libs --cflags spread-sheet-widget) prog1.c}.

Except for lines 2 and 13, all code in this program are standard Gtk+.
Line 2 includes the header file @file{ssw-sheet.h} which is necessary in
order to call @code{ssw_sheet_new} at line 13.
The function @code{ssw_sheet_new} creates a new widget which is a Spread
Sheet Widget to be displayed.
Subsequent lines add the widget to the window and display it.



If you compile and run the program you will see an empty sheet without
any data in its cells.
As written, this program cannot display any data because there is no
@dfn{data model} associated with the @code{SswSheet}.
The data model is a @code{GObject} which implements the @code{GtkTreeModel}
interface.
One simple implementation of @code{GtkTreeModel} is the @code{GtkListStore} object
and the following example creates such an object and sets it as the
data model for our sheet:
@example
@verbatiminclude prog2.c-enum
@end example
In this example, the function @code{create_data_model} creates a model with
3 columns and 4 rows.
@code{GtkListStore} is designed to store all its data in memory.
This is fine for small data models, but would not be suitable
if there are a very large number of rows or columns.
In that case you would be well advised not to use @code{GtkListStore} but
to create your own @code{GObject} implementing @code{GtkTreeModel} and storing
its data in secondary memory.

You inform the sheet about the data model to use, by way of
the @code{data-model} property of @code{SswSheet}.  This is done in line 34 of the
above example.


If you run the above example, you should see a sheet with 3 columns of data
and 4 rows.
Each datum is in a @dfn{cell}.
Using the computer's arrow keys you can select any  cell.
To indicate that a cell is selected, its border is highlighted.
However you will not be able to edit any data, nor add any new data.
If you try to type anything your keystrokes will be ignored.

This is because the sheet's @samp{editable} property defaults to false.
In order to allow the user to add, delete or mutate data which the
sheet is displaying, you must set the @samp{editable} property to true.
The typical way of doing this is
@code{g_object_set (sheet, "editable", TRUE, NULL);}.
If you do this, and rerun the program, then you will be able to type
characters into a selected cell.
When you hit the @key{Enter}, --- @emph{What?} the cell returns to its
previous value!!   What went wrong?

This is because the spread sheet widget is designed to be independent
of how the data is stored.  It does not and cannot know how to update
data.  It is the programmer's responsibility to do this.




@bye
