I need some guidance

[Geert Janssens]

On Tuesday 24 February 2015 09:06:09 David Christopher wrote:
> New to Linux.  I just converted my computer to Mint 17.1 from the
> Windows OS.  I was learning to code in Visual Studio.  I want to work
> on GNUcash reports, for fun and to learn more about the program.
> 
> I have been learning to use Guile and Scheme, but here is my mental
> block.
> 
Hi David,

I can understand your confusion. I have been there as well a couple of years back.

> When you write code is Scheme script, are you literally building the
> Options, what I call a form, literally?

No, this is all heavily abstracted. The report system in gnucash is a mix of C code and scheme 
code. The parts that actually draw the form and even define which widget (graphical 
representation of an option on the form) to use  are in the C code.

The scheme code related to options is spread over several areas in gnucash.

First off there is src/app-utils/options.scm. This scheme file defines the data model for most 
options. Not how it is graphically represented, but what data can be stored in which kind of 
option. For example a text option can store a bit of text. A date option can store a date,... All 
this is in options.scm.

Building on that, the kind of option directly defines how it is represented visually to the user. As 
said these graphical representations are written in C, most can be found in
src/gnome-utils/dialog-options.c.

Lastly the reports don't define the options, nor the way to present them visually to the user. 
Simplified you could say the options section in the reports is more like an ingredient list. It 
merely tells which options you want for the report of what kind of data they represent. This 
section is called the "options-generator" in most reports.

The lower level code takes these "ingredients" and transform them into a form with option to 
show the user whenever this is requested.

However although you don't define the graphical representation of the options, you do have 
some limited control over their appearance in the form:
- the form is divided in tabs or sections. You can choose the section name in which your option 
is to be displayed. There are several predefined sections (like General) or you can invent your 
own if needed. This section name is passed as the first parameter in each of the gnc:make-
<xyz>-option calls.
- secondly within a section you can manipulate the display order on the form. Most reports use a 
single or double letter string to order the options. In the hello-world.scm report you can see 
these in each of the gnc:make-<xyz>-option calls as the third parameter.

> I have been looking at the
> Hello world .scm file while in a tutorial.  I understand I can change
> the text in a label, but how did the label get on the form, where did
> the form come from, and the buttons on the form?
> 
All this is set up in C code based on the option description you pass in the report code.

> Is there a small tutorial that shows how to make the form and put
> controls on it?  Is that even what is being done?
> 

Unfortunately I'm not aware of such a tutorial.

Hopefully my explanation helps you understand this somewhat better.

Regards,

Geert