/// \mainpage
/// Nictk (formerly Ntk) is a wrapper for **tkinter** written by Nicola Cassetta with the aim of simplifying its use for building graphical interfaces with Python.
///
/// As is known, **tkinter** is the Python standard library already included in the language distribution; it derives from **Tcl/Tk** and maintains its nomenclature and conventions in names and parameters of the functions, so they are often difficult to remember. It also has three different geometry managers (_pack_, _grid_ and _place_) for placing widgets, which can be confusing. One of the most popular features is its ability to easily resize widgets when the main window is resized, but this often leads to strange behavior. For example, the standard behavior of an Entry object (the text field widget) is to grow larger as we type text into it. If we packed other widgets to its right all of them will move. Another problem arises for widget dimensions, which are in pixel for some of them (for example Button, Canvas) and in charachters for other (Label, Entry).
///
/// These things make **tkinter** not very easy to learn for people starting out in designing graphical interfaces with Python. So I tried to simplify these problems by adopting some general principles: 
/// - All widgets have a similar constructor, which enable the user to easily position them, with sizes always specified in pixels (as in **tkinter**, widgets can change their position and size when the main window is resized).
/// - Many options for the widget **config()** method have been renamed in a way that is easier to remember, and some of them have been replaced by dedicated methods. Also the almost infinite series of **winfo_...** methods have been packed into the unique **get_winfo()** method, with a string parameter.
/// - I renamed also some functions, trying to mantain the _xxxx_yyyy_ scheme recommended in PEP 8 (this, however, is not complete).
/// - I simplified the binding of events to callback functions, introducing in many widgets a _command_ parameter in the constructor and standardizing the callback paradigm.
/// - I simplified also the use of IntVar, StringVar, etc.
/// - From ver 2.2.0 I introduced scrolling frames, containers in which you can scroll the internal area.
///
/// You can start learning Nictk by reading the \ref OVERVIEW section.
///


/// \page OVERVIEW Overview
///
/// Getting started with Nictk.
///
/// + \subpage INSTALL
/// + \subpage SIMPLE_EXAMPLE
/// + \subpage CONSTRUCTORS
/// + \subpage WIDGETS
/// + \subpage PLACING_WIDGETS
/// + \subpage ATTRIBUTES
/// + \subpage WIDGET_INFO
/// + \subpage EVENTS
/// + \subpage VARIABLES
/// + \subpage DIALOGS



/// \page INSTALL How to install
///
/// Nictk consist only of the two files \__init__.py and constants.py in the folder /Nictk. If you want to try it without installing you can:
/// + create your own folder
/// + copy in it (as subfolders) the /Nictk and /Examples folders
/// + create your own files in your folder (files in /Example folder import a _setup module which sets the path for import)
///
/// For installing it you can download the _wheel_ or _tar.gz_ files from the /dist folder and istall them with _pip_. Enter the folder in which the file have been downloaded and type (for mac/linux users):
/// \code
/// python3 -m pip install nictk_pkg_python_gui-2.0.0-py3-none-any.whl
/// \endcode
///
/// or
/// \code
/// python3 -m pip install nictk-pkg-python-gui-2.0.0.tar.gz
/// \endcode
///
/// the two methods are equivalent, but (according to Python documentation) installing from .whl file should be preferred.
///
/// Windows users should open a cmd console and substitute _python3_ with _python_.
///
/// Moreover you can also unzip the _tar.gz_ file and experiment with the example files (in the /Examples folder).



/// \page SIMPLE_EXAMPLE A simple example
///
/// When using Nictk I suggest to put at the beginning of the file these import statements:
/// \code{.py}
/// import Nictk as Ntk
/// from Nictk.constants import *
/// \endcode
///
/// so you can use the various aliases as END, FILL, PACK without prepending them with the package name. This
/// is used in all example files.
///
/// Here is a simple example of the usage of Nictk:
///
/// \include Hello.py
///
/// This creates a label and a button which hides and shows it. In a widget constructor the first argument is the parent widget, then follow its dimensions (x position, y, position, width and height), and other arguments specific for the widget (for button and label the text, for the button also the associated callback). For the various modes in which you can position a widget see \ref PLACING_WIDGETS.
/// This file is the \ref Hello.py in the Examples folder.


/// \page CONSTRUCTORS Constructors
///
/// All Nictk widgets have a common scheme for their constructor:
///
/// \code{.py}
///
///Widget_name(parent, x, y, w, h, pad=0, **kw)
///
/// \endcode
///
/// Where:
/// + **parent** is the parent widget (a window or a frame) which contains the widget to be constructed
/// + **x**, **y** determine the position of the upper left corner of the widget
/// + **w**, **h** determine the width and height of the widget
/// + **pad** is a padding parameter which allows to leave some space between widgets
/// + ** **kw** are other keyword parameters specific for the widget
///
/// The constructor allows to create and place the widget with a single instruction. There are no separate instructions for creating and placing (and no different geometry managers) like in **tkinter**. Parameters **x**, **y**, **w**, **h** are always relative to the parent widget, and (when numeric) expressed in pixels. You have however many options to indicate the position and the size: you can set them to absolute or relative values, or pack the widget with respect to previously constructed. These options will determine also if the widget dimension are updated when the parent is resized. For details see \ref PLACING_WIDGETS.
///
/// The constructor, on the other hand, generally allows you to set only a few fundamental properties of the widget. The setting of the various attributes (such as color, font, etc.) is generally left to the Nictk.Widget.config() method (but this can be abbreviated for containers with the Nictk.Container.config_children() method which acts on all children when they are constructed). This will be explained in detail in the \ref ATTRIBUTES section.
///


/// \page WIDGETS Available widgets
///
/// This is a list of the available widgets in the library; all of them are subclasses of **tkinter** or **ttk** widgets. I however renamed some of them to get a better clarity.
///
///
///
/// ## Windows ##
///
/// In your app you must create a unique main window (i.e. a **Main** object), then you can create and destroy any number of **Window** objects (the Toplevel object in **tkinter**).
///
/// <table>
///   <tr>
///     <th>**Object**</th>
///     <th>Notes</th>
///   </tr><tr>
///     <td>class Nictk.Main</td>
///     <td>The main window of the app (derived from the **tkinter** **Tk** class)</td>
///   </tr><tr>
///     <td>class Nictk.Window</td>
///     <td>A common window (derived from the **tkinter** **Toplevel** class). It can be a normal, modal or persistent window</td>
///   </tr>    
/// </table>
///
///
///
/// ## Frames ##
///
/// Frames are another type of container. They are initialized with no border and the same color of their parent, so they are invisible and you can use them for layout purposes (grouping children widgets horizontally or vertically). However, as they are derived from the **tkinter** **LabelFrame** widget, you can set a border and a label for them (this reduces the available space in the frame). In their constructors the pad parameter is present but is ignored (it is always fixed to 0 in all directions).
///
/// From version 2.2.0 I introduced scrollable frames, in which you can add internal widgets exceeding the frame height: if you do this a scrollbar appears automatically.
///
/// <table>
///   <tr>
///     <th>**Object**</th>
///     <th>Notes</th>
///   </tr><tr>
///     <td>class Nictk.HorFrame</td>
///     <td>A frame in which you can stack children widgets horizontally</td>
///   </tr><tr>
///     <td>class Nictk.VerFrame</td>
///     <td>A frame in which you can stack children widgets vertically</td>
///   </tr><tr>
///     <td>class Nictk.RowFrame</td>
///     <td>A frame which you can divide in rows vertically. Each row behaves like a HorFrame, allowing to stack children widgets horizontally. This allows to place widgets as in a matrix.</td>
///   </tr><tr>
///     <td>class Nictk.VerScrollFrame</td>
///     <td>Similar to the VerFrame. You can stack widgets exceeding the height of the internal area, in this case a vertical scrollbar appears automatically.</td>
///   </tr><tr>
///     <td>class Nictk.RowScrollFrame</td>
///     <td>Similar to the RowFrame. You can stack widgets exceeding the height of the internal area, in this case a vertical scrollbar appears automatically.</td>
///   </tr>
/// </table>
///        
/// 
///
/// ## Widgets ##
///
/// These are the other widgets defined in Nictk.
///
/// <table>
///   <tr>
///     <th>**Object**</th>
///     <th>Notes</th>
///   </tr><tr>
///     <td>class Nictk.Button</td>
///     <td>Button widget</td>
///   </tr><tr>
///     <td>class Nictk.Canvas</td>
///     <td>Canvas widget to display graphical elements like lines or text</td>
///   </tr><tr>
///     <td>class Nictk.Checkbutton</td>
///     <td>Checkbutton widget which is either in on or off state</td>
///   </tr><tr>
///     <td>class Nictk.Combobox</td>
///     <td>Combobox which allows the user to select a value from a menu. It is the equivalent (renamed) of the OptionMenu class in **tkinter**</td>
///   </tr><tr>
///     <td>class Nictk.Entry</td>
///     <td>Entry widget which allows editing and displaying simple text</td>
///   </tr><tr>
///     <td>class Nictk.Label</td>
///     <td>Label widget which can display text and bitmaps</td>
///   </tr><tr>
///     <td>class Nictk.Listbox</td>
///     <td>Listbox widget which can display a list of strings, allowing simple and multiple selection</td>
///   </tr><tr>
///     <td>class Nictk.Menu</td>
///     <td>Menu widget which allows displaying menu bars, pull-down menus and pop-up menus</td>
///   </tr><tr>
///     <td>class Nictk.Radiobutton</td>
///     <td>Radiobutton widget which can be grouped, showing only one of several buttons in on state</td>
///   </tr><tr>
///     <td>class Nictk.Scale</td>
///     <td>Scale widget which can display a cursor sliding on a numerical scale</td>
///   </tr><tr>
///     <td>class Nictk.Scrollbar</td>
///     <td>Scrollbar widget</td>
///   </tr><tr>
///     <td>class Nictk.Spinbox</td>
///     <td>Spinbox widget which allows selecting one of various options by mean of arrow keys or inserting a new one</td>
///   </tr><tr>
///     <td>class Nictk.Text</td>
///     <td>Text widget which can edit and display formatted text</td>
///   </tr><tr>
///     <td>class Nictk.Notebook</td>
///     <td>Notebook widget which manages a collection of windows and displays a single one at a time. It derives from the ttk.Notebook widget</td>
///   </tr>
///  </table>
///


/// \page PLACING_WIDGETS Placing the widgets
/// 
/// As we have seen the widget constructor always has the form
/// \code
///Widget_name(parent, x, y, w, h, pad=0, **kw)
/// \endcode
/// where **parent** is the parent widget, **x**, **y** determine its position and **w**, **h** its size.
/// We emphasize that:
/// + The position and size always are relative to the parent widget and (when numeric) expressed in pixels;
/// + The parameters you provide are relative to the **bounding box** of the widget, which coincides with it if the pad parameter is set to 0. The pad can be set to a value other than zero, thus leaving some space for left, right up and down. **However, this reduces the actual size of the widget**;
/// + The library provides some containers that facilitate the placement of widgets, making it possible to obtain complex layouts with few code lines.
///
/// These are the various options you have to indicate the position and size of the widget.
///
/// Values for x, y
/// ---------------
///
/// As said above, these determine the position of the topleft corner of the widget bounding box.
///
/// <table>
///   <tr>
///     <th>Value</th>
///     <th>Meaning</th>
///     <th>Notes</th>
///   </tr><tr>
///     <td>**positive int**</td>
///     <td>Absolute positioning from left/top</td>
///     <td>The topleft will placed in the exact position x or y with respect to parent widget left (or top). If the parent is resized the coordinate will not change</td>
///   </tr><tr>
///     <td>**negative int**</td>
///     <td>Absolute positioning from right/bottom</td>
///     <td>The topleft will be placed in the exact position x or y before the parent widget right (or bottom). If the parent is resized the coordinate will be updated</td>
///   </tr><tr>
///     <td>**string as "20%"**</td>
///     <td>Relative positioning from left/top</td>
///     <td>The topleft will be placed in the relative (in percent) position x or y with respect to parent widget left (or top). If the parent is resized the coordinate will be updated</td>
///   </tr><tr>
///     <td><b>"pack" (or constant PACK)</b></td>
///     <td>Relative positioning respect a widget</td>
///     <td>The widget box will be stacked after the last widget already placed in the container. If the adiacent widget is resized the coordinate will be updated. See <a href="#packuse">Note on the use of PACK</a> for details.</td>
///   </tr><tr>
///     <td><b>"center" (or constant CENTER)</b></td>
///     <td>Widget centered</td>
///     <td>The widget box will be centered (horizontally or vertically) in the parent widget</td>
///   </tr>
/// </table>
///
/// Values for w, h
/// ---------------
/// These also determine the dimensions of the widget bounding box, which may not coincide with the widget coordinates.
///
/// <table>
///   <tr>
///     <th>Value</th>
///     <th>Meaning</th>
///     <th>Notes</th>
///   </tr><tr>
///     <td>**positive int**</td>
///     <td>Absolute size</td>
///     <td>The widget box has fixed width/height. If the parent is resized it will not change.</td>
///   </tr><tr>
///     <td>**negative int**</td>
///     <td>Absolute size with respect to right/bottom</td>
///     <td>The widget box width/height will be adjusted so that its right/bottom side is w/h pixels far from the right/bottom side of the parent widget. If the parent is resized the size will be updated.</td>
///   </tr><tr>
///     <td>**string as "20%"**</td>
///     <td>Relative width/height</td>
///     <td>The widget box has relative (in percent) width/height with respect to parent widget. If the parent is resized the size will be updated.</td>
///   </tr><tr>
///     <td><b>"fill" (or constant FILL)</b></td>
///     <td>Fill the parent</td>
///     <td>The widget box width/height is the same of the parent widget. If the parent is resized the size will be updated.</td>
///   </tr>
/// </table>
///
/// Values for pad
/// ---------------
///
/// The pad parameter allows to leave some space between the widget bounding box and the actual widget.
/// <table>
///   <tr>
///     <th>Value</th>
///     <th>Meaning</th>
///     <th>Notes</th>
///   </tr><tr>
///     <td>**0 (default)**</td>
///     <td>No padding</td>
///     <td>The widget has same dimensions as its bounding box.</td>
///   </tr><tr>
///     <td>**positive int**</td>
///     <td>Same padding in all directions</td>
///     <td>The given value is the padding amount for left, right, up and down.</td>
///   </tr><tr>
///     <td>**A duple of positive int**</td>
///     <td>Same padding for left/right and for up/down</td>
///     <td>The first int is the padding amount for left and right, the second for up and down.</td>
///   </tr><tr>
///     <td>**A quadruple of positive int**</td>
///     <td>Different padding for the four directions</td>
///     <td>The provided numbers are the amounts respectively for left, up, right, down directions.</td>
///   </tr>
/// </table>
///
/// Here are some examples
/// \code{.py}
/// import Nictk as Ntk
///from Nictk.constants import *
///
///  .  .  .
///
///# absolute positioning (x=10, y=10, w=80, h=30), no padding
///w = Ntk.Entry(parent, 10, 10, 80, 30)
///
///# absolute positioning, pad of 5 pixel left/right and 10 pixels up/down
///w = Ntk.Entry(parent, 10, 10, 80, 20, pad=(5, 10))
///
///# right side is 10 pixels far from parent one, pad of 5 pixel in all directions
///w = Ntk.Entry(parent, 0, 0, -10, 30, pad=5)
///   
///# the widget width is 80 pixels and it is centered horizontally, the widget
///# height fills the parent, different pad for each directions
///# left = 5, up = 10, right = 0, down = 5)
///w = Ntk.Entry(parent, CENTER, 0, 80, FILL, pad=(5, 10, 0, 5))
///
/// \endcode
///
/// Note on the use of PACK
/// -----------------------
///
/// <a name="packuse">The meaning of the "pack" parameter (aliased by PACK) differs depending on the type of container in which the widget will be placed.
///
/// In an Nictk.VerFrame, Nictk.VerScrollFrame, Nictk.Main, or Nictk.Window the widgets are stacked from top to bottom and the parent keeps track of the last widget placed on the stack. So PACK is effective only for the y coordinate, while for the x you will always get a widget positioned to the left (i.e. with x coordinate = 0). Conversely, in an Nictk.HorFrame or in a row of an Nictk.RowFrame, Nictk.RowScrollFrame the widgets are stacked from left to right, so you can use the PACK for the x, while for the y you will get a widget positioned at the top (y = 0).
/// Here are two example you can try:
///
/// \code{.py}
///import Nictk as Ntk
///from Nictk.constants import *
///
///winMain = Ntk.Main(100, 100, 400, 300)
///
///# Ntk.Entry(PACK, PACK, 90 40, pad=5) would be equivalent
///ent1 = Ntk.Entry(0, 0, 90, 40, pad=5)
///# ent2 will be placed below ent1
///ent2 = Ntk.Entry(0, PACK, 90, 40, pad=5)
///#ent3 will be placed below ent1. PACK for the x is the same for 0
///ent3 = Ntk.Entry(PACK, PACK, 90, 40, pad=5)
///#ent4 is below ent3, but displaced horizontally
///ent4 = Ntk.Entry(40, PACK, 90, 40, pad=5)
///
///Ntk.mainloop()
/// \endcode
///
/// Second example
///
/// \code{.py}
///import Nictk as Ntk
///from Nictk.constants import *
///
///winMain = Ntk.Main(100, 100, 400, 300)
///
///# we fill the window with an horizontal frame
///hfr1 = Ntk.HorFrame(0, 0, FILL, FILL)
///# lab1 will be placed on the left
///lab1 = Ntk.Label(0, CENTER, 90, 40, pad=5)
///#ent1 will be placed right to  lab1.
///ent1 = Ntk.Entry(PACK, CENTER, 90, 40, pad=5)
///#ent2 is right to ent1, but displaced vertically
///(at the bottom of the window)
///ent2 = Ntk.Entry(PACk, -40, 90, 40, pad=5)
///
///Ntk.mainloop()
/// \endcode
///
/// Querying widgets dimensions
/// ---------------------------
///
/// See \ref dimensions "here" to get documentation about the methods for retrieving widgets dimensions.
///
/// See also the example files \ref WidgetPosition.py and \ref RowFrame.py.
///