### ----------------------------------------------------
### -- Gnome::Gtk3
### -- Licenses: Artistic-2.0
### -- Authors: Marcel Timmerman
### -- File: Design-docs/Design.md
### ----------------------------------------------------
### -- Chunk 2 of 2
, $ptr);
    f($format, |@args)
}

pera-int-f("Pera + Mela = %d + %d %s\n", 25, 12, "cippas");
```


# Memory
Notes from https://developer.gnome.org/gtk3/stable/gtk-question-index.html

### How does memory management work in GTK+? Should I free data returned from functions?

See the documentation for GObject and GInitiallyUnowned. For GObject note specifically g_object_ref() and g_object_unref(). GInitiallyUnowned is a subclass of GObject so the same points apply, except that it has a "floating" state (explained in its documentation).

For strings returned from functions, they will be declared "const" if they should not be freed. Non-const strings should be freed with g_free(). Arrays follow the same rule. If you find an undocumented exception to the rules, please report a bug on GitLab.

### Why does my program leak memory, if I destroy a widget immediately after creating it ?


If GtkFoo isn't a toplevel window, then
```
foo = gtk_foo_new ();
gtk_widget_destroy (foo);
```

is a memory leak, because no one assumed the initial floating reference. If you are using a widget and you aren't immediately packing it into a container, then you probably want standard reference counting, not floating reference counting.

To get this, you must acquire a reference to the widget and drop the floating reference (“ref and sink” in GTK+ parlance) after creating it:

```
foo = gtk_foo_new ();         # floating reference
g_object_ref_sink (foo);      # acquire a reference and drop floating ref
```

When you want to get rid of the widget, you must call gtk_widget_destroy() to break any external connections to the widget before dropping your reference:

```
gtk_widget_destroy (foo);     # get rid of the widget
g_object_unref (foo);         # drop reference
```

When you immediately add a widget to a container, it takes care of assuming the initial floating reference and you don't have to worry about reference counting at all ... just call gtk_widget_destroy() to get rid of the widget.

**Notes**
* gtk_foo_new -> floating reference if from **InitiallyUnowned**

# Internationalize
### How do I internationalize a GTK+ program?

Most people use GNU gettext, already required in order to install GLib. On a UNIX or Linux system with gettext installed, type info gettext to read the documentation.

The short checklist on how to use gettext is: call bindtextdomain() so gettext can find the files containing your translations, call textdomain() to set the default translation domain, call bind_textdomain_codeset() to request that all translated strings are returned in UTF-8, then call gettext() to look up each string to be translated in the default domain.

gi18n.h provides the following shorthand macros for convenience. Conventionally, people define macros as follows for convenience:

```
#define  _(x)     gettext (x)
#define N_(x)     x
#define C_(ctx,x) pgettext (ctx, x)
```

You use N_() (N stands for no-op) to mark a string for translation in a location where a function call to gettext() is not allowed, such as in an array initializer. You eventually have to call gettext() on the string to actually fetch the translation. _() both marks the string for translation and actually translates it. The C_() macro (C stands for context) adds an additional context to the string that is marked for translation, which can help to disambiguate short strings that might need different translations in different parts of your program.

Code using these macros ends up looking like this:

```
#include <gi18n.h>

static const char *global_variable = N_("Translate this string");

static void
make_widgets (void)
{
   GtkWidget *label1;
   GtkWidget *label2;

   label1 = gtk_label_new (_("Another string to translate"));
   label2 = gtk_label_new (_(global_variable));
...
```

Libraries using gettext should use dgettext() instead of gettext(), which allows them to specify the translation domain each time they ask for a translation. Libraries should also avoid calling textdomain(), since they will be specifying the domain instead of using the default.

With the convention that the macro GETTEXT_PACKAGE is defined to hold your libraries translation domain, gi18n-lib.h can be included to provide the following convenience:

```
#define _(x) dgettext (GETTEXT_PACKAGE, x)
```

### How do I use non-ASCII characters in GTK+ programs ?

GTK+ uses Unicode (more exactly UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a sequence of one to six bytes and has a number of nice properties which make it a good choice for working with Unicode text in C programs:

    ASCII characters are encoded by their familiar ASCII codepoints.

    ASCII characters never appear as part of any other character.

    The zero byte doesn't occur as part of a character, so that UTF-8 strings can be manipulated with the usual C library functions for handling zero-terminated strings.

More information about Unicode and UTF-8 can be found in the UTF-8 and Unicode FAQ for Unix/Linux. GLib provides functions for converting strings between UTF-8 and other encodings, see g_locale_to_utf8() and g_convert().

Text coming from external sources (e.g. files or user input), has to be converted to UTF-8 before being handed over to GTK+. The following example writes the content of a IS0-8859-1 encoded text file to stdout:

```
gchar *text, *utf8_text;
gsize length;
GError *error = NULL;

if (g_file_get_contents (filename, &text, &length, NULL))
  {
     utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",
                            NULL, NULL, &error);
     if (error != NULL)
       {
         fprintf ("Couldn't convert file %s to UTF-8\n", filename);
         g_error_free (error);
       }
     else
       g_print (utf8_text);
  }
else
  fprintf (stderr, "Unable to read file %s\n", filename);
```

For string literals in the source code, there are several alternatives for handling non-ASCII content:

* **direct UTF-8**: If your editor and compiler are capable of handling UTF-8 encoded sources, it is very convenient to simply use UTF-8 for string literals, since it allows you to edit the strings in "wysiwyg". Note that choosing this option may reduce the portability of your code.

**escaped UTF-8**: Even if your toolchain can't handle UTF-8 directly, you can still encode string literals in UTF-8 by using octal or hexadecimal escapes like \212 or \xa8 to encode each byte. This is portable, but modifying the escaped strings is not very convenient. Be careful when mixing hexadecimal escapes with ordinary text; "\xa8abcd" is a string of length 1 !

**runtime conversion**: If the string literals can be represented in an encoding which your toolchain can handle (e.g. IS0-8859-1), you can write your source files in that encoding and use g_convert() to convert the strings to UTF-8 at runtime. Note that this has some runtime overhead, so you may want to move the conversion out of inner loops.

Here is an example showing the three approaches using the copyright sign © which has Unicode and ISO-8859-1 codepoint 169 and is represented in UTF-8 by the two bytes 194, 169, or "\302\251" as a string literal:

```
g_print ("direct UTF-8: ©");
g_print ("escaped UTF-8: \302\251");
text = g_convert ("runtime conversion: ©", -1, "ISO-8859-1", "UTF-8", NULL, NULL, NULL);
g_print(text);
g_free (text);
```

If you are using gettext() to localize your application, you need to call bind_textdomain_codeset() to ensure that translated strings are returned in UTF-8 encoding.

# Design graphs

## Details at the top
Most classes at the top depend on TopLevelClassSupport. A few classes are independent.
```plantuml
'scale 0.7
set namespaceSeparator ::
skinparam packageStyle rectangle
skinparam stereotypeCBackgroundColor #80ffff
hide empty members

class Gnome::N::TopLevelClassSupport < Catch all class >
'interface Gnome::Gtk3::Buildable < Interface >

class Gnome::GObject::Type
class Gnome::Gtk3::Enums

Gnome::N::TopLevelClassSupport <|--- Gnome::Glib::Error

'Gnome::Gtk3::Buildable <|-- Gnome::Gtk3::Widget

Gnome::N::TopLevelClassSupport <|-- Gnome::GObject::Object
Gnome::N::TopLevelClassSupport <|-- Gnome::GObject::Boxed
Gnome::GObject::Object <|-- Gnome::GObject::InitiallyUnowned
Gnome::GObject::Boxed <|-- Gnome::GObject::Value
Gnome::GObject::Object *-left-> Gnome::GObject::Signal

Gnome::GObject::InitiallyUnowned <|-- Gnome::Gtk3::Widget
Gnome::GObject::InitiallyUnowned <|-- Gnome::Gtk3::Adjustment

'Gnome::N::TopLevelClassSupport <|-- Gnome::Gio::Application
Gnome::GObject::Object <|-- Gnome::Gio::Application
Gnome::Gio::Application <|-- Gnome::Gtk3::Application
```

## Dependency details between packages
```plantuml

scale 0.7
'title Dependency details between packages
allowmixing

!include <tupadr3/common>
!include <tupadr3/font-awesome/archive>
!include <tupadr3/font-awesome/cogs>


package Glib {
  FA_COGS(Glib) #e0e0ff
}
package GObject {
  FA_COGS(GObject) #e0e0ff
}
package Gio {
  FA_COGS(Gio) #e0e0ff
}
package Gtk {
  FA_COGS(Gtk) #e0e0ff
}
package Gdk {
  FA_COGS(Gdk) #e0e0ff
}
'package Pango {
'  FA_COGS(Pango) #e0e0ff
'}
'package Cairo {
'  FA_COGS(Cairo) #e0e0ff
'}


package Gnome::N {
  FA_COGS(RN)
}

package Gnome::Glib {
  FA_COGS(RGlib)
}
package Gnome::Gio {
  FA_COGS(RGio)
}
package Gnome::GObject {
  FA_COGS(RGObject)
}
package Gnome::Gdk3 {
  FA_COGS(RGdk3)
}
package Gnome::Gtk3 {
  FA_COGS(RGtk3)
}


Gnome::Gdk3 <.. Gnome::Gtk3
Gnome::Gio <.. Gnome::Gtk3
Gnome::GObject <... Gnome::Gtk3
Gnome::Glib <... Gnome::Gtk3
Gnome::N <... Gnome::Gtk3
Gtk <....... Gnome::Gtk3

Gnome::GObject <.... Gnome::Gdk3
Gnome::Glib <... Gnome::Gdk3
Gnome::N <... Gnome::Gdk3
Gdk <...... Gnome::Gdk3

Gnome::N <.. Gnome::Gio
Gnome::GObject <.. Gnome::Gio
Gnome::Glib <.. Gnome::Gio
Gio <.... Gnome::Gio

Gnome::N <.. Gnome::GObject
GObject <... Gnome::GObject

Gnome::N <.. Gnome::Glib
Glib <... Gnome::Glib

```


