GtkAda Contributions
version 3.32

Dmitry A. Kazakov	and	Maxim Reznik
(mailbox@dmitry-kazakov.de)

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

As a special exception, if other files instantiate generics from this unit, or you link this unit with other files to produce an executable, this unit does not by itself cause the resulting executable to be covered by the GNU General Public License. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU Public License.

						ARM		Intel
Download GtkAda Contributions				Platform:		64-	32-	64-	32bit
Fedora packages			precompiled and packaged using RPM
CentOS packages			precompiled and packaged using RPM
Debian packages			precompiled and packaged for dpkg
Ubuntu packages			precompiled and packaged for dpkg
Source distribution (any platform)			gtkada_contributions_3_32.tgz (tar + gzip, Windows users may use WinZip)
Download XPM to GtkAda converter (embedding images into GtkAda applications see)						64-	32-	64-	32bit
Windows i686			xpm2gtkada.exe.gz (gzip compressed, Windows users may use WinZip)
Fedora packages			is a part of the developing package (has devel suffix)
CentOS packages			is a part of the developing package (has devel suffix)
Debian packages			is a part of the developing package (has dev suffix)
Ubuntu packages			is a part of the developing package (has dev suffix)

See also:

• Additional GTK packages for Windows;
• GtkAda packages for Fedora;
• GtkAda packages for Debian.

The described here packages are proposed as a contribution to GtkAda, an Ada bindings to GTK+. It deals with the following issues:

• Tasking support;
• Custom models for tree view widget;
• Custom cell renderers for tree view widget;
• Multi-columned derived model;
• Extension derived model (to add columns to an existing model);
• Abstract caching model for directory-like data;
• Tree view and list view widgets for navigational browsing of abstract caching models;
• File system navigation widgets with wildcard filtering;
• Resource styles;
• Capturing resources of a widget;
• Embeddable images;
• Some missing subprograms and bug fixes;
• Measurement unit selection widget and dialogs;
• Improved hue-luminance-saturation color model;
• Simplified image buttons and buttons customizable by style properties;
• Controlled Ada types for GTK+ strong and weak references;
• Simplified means to create lists of strings;
• Spawning processes synchronously and asynchronously with pipes;
• Capturing asynchronous process standard I/O by Ada tasks and by text buffers;
• Source view widget support;
• SVG images support.

See also changes log. 

1. Tasking with GTK+

The package Gtk.Main.Router provides a synchronization mechanism to use GTK+ framework with Ada tasks. GTK+ is known to be task unsafe. In particular, all calls need to be made from the same task (thread). Further GTK+ has a callback-based architecture which makes it difficult to use Ada's entry points for synchronization, because callback subprograms cannot act as entries. This package allows Ada tasks triggering some GTK+ actions to synchronize on a protected object with the task handling GTK+ events. Basically, the task waits for GTK+ be ready to serve it. Serving occurs upon idle loop processing, which performs the requested action on the context of the main GTK+ thread. Upon action completion the task is unblocked and continues its work. For the task it appears much as a rendezvous with the GTK+ main thread.

The package provides three ways to request an action to be performed on the context of GTK+ main thread.

• Extensible tagged type. The task that needs to call some GTK+ subroutines, derives from the type Request_Data and places the parameters there. It overrides the procedure Service with a sequence of calls, needed to be done. Then it calls to Request one or multiple times. Exceptions raised in Service are propagated to the task called Request. It is safe to use this Request from any task, including one of the main GTK+ loop. In the latter case Request will not block.
• Plain callback routine. The type Gtk_Callback is a pointer to a parameterless procedure. The procedure Request with the parameter of this type can be used to request a call to the procedure on the context of the main GTK+ loop. Similarly to the variant with a tagged type, it is safe to call Request on any context.
• Generic package Generic_Callback_Request can be instantiated with an appropriate type of callback routine parameters. The procedure Request defined in the package acts like a plain callback routine described above and also accepts a parameter of the user-defined type.
• Generic package Generic_Message is provided for potentially asynchronous execution of user-defined handlers on the GTK+ context. Differently to the methods listed above it the caller does not wait for request completion.

Note that the package is based on timer events.

Quit_Error : exception;
Busy_Error : exception;

The exception propagated when servicing is impossible because the main GTK+ loop was prematurely left.

function Get_Max_Asynchronous return Positive;

This function returns the maximum number of asynchronous requests pending in the queue. When the limit is reached the new asynchronous requests are blocked. When a request stays until timeout expiration, it fails with Busy_Error exception.

function Get_Request_Info return String;

This function returns a string containing information about current requests. It is used for debugging purpose.

procedure Init
          (  Window   : not null access Gtk_Window_Record'Class;
             Period   : Duration := 0.2;
             GPS_Port : Natural  := 50_000
          );

This procedure should be called once from the main GTK+ thread after Init. Usually it is done before entering the loop of processing events and before starting tasks which might use the package functionality. Period specifies how frequently the mail loop will poll for graphic requests from other tasks. The parameter Window is the application window for which the main loop is used. The parameter GPS_Port specifies the port used to connect to the GPS, when the latter is in the server mode.

function Is_Active return Boolean;

This function returns true if servicing is active. When inactive requests fail with Quit_Error exceptions.

procedure Quit;

This procedure stops servicing request. All pending and future requests propagate Quit_Error. Normally it is not necessary to use this procedure because servicing is stopped automatically when the window specified in Init is destroyed.

procedure Set_Max_Asynchronous (Max : Positive);

This procedure sets the maximum number of asynchronous requests pending in the queue. This limit does not affect the synchronous requests because these are limited by the total number of tasks.

type Request_Data is abstract
   new Ada.Finalization.Limited_Controlled with null record;

The base type of a request.

procedure Request (Data : in out Request_Data'Class);

This procedure is called in order to request Data to be serviced on the context of the main GTK+ task. The call is blocking. The caller will wait until the request will be serviced through a call to Service on the GTK+ context. Program_Error is propagated when Init was not called. Other exceptions are the exceptions propagated out of Service and re-raised on the caller's context. Quit_Error is propagated when the main GTK+ loop was quitted before the request was serviced.

procedure Service (Data : in out Request_Data) is abstract;

This abstract procedure which any derived type should implement. All GTK+ calls shall be placed here. Note that Service is called on the context of the main GTK+ thread. An implementation may propagate exceptions which are caught and re-raised on the context of Request.

procedure Request (Service : Gtk_Callback);

The caller will wait until the request will be serviced through a call to Service on the GTK+ context. Service is a parameterless procedure. Program_Error is propagated when Init was not called. Other exceptions are the exceptions propagated out of Service and re-raised on the caller's context. Quit_Error is propagated when the main GTK+ loop was quitted before the request was serviced.

generic
   type User_Data (<>) is limited private;
package Generic_Callback_Request is ...

The package is instantiated with the user data type. It declares the type:

type Callback_Procedure is
   access procedure (Data : not null access User_Data);

This is the procedure to be called on the GTK+ context.

procedure Request
          (  Callback : Callback_Procedure;
             Data     : not null access User_Data
          );

The caller will wait until the request will be serviced through a call to Callback on the GTK+ context. Program_Error is propagated when Init was not called. Other exceptions are the exceptions propagated out of Callback and re-raised on the caller's context. Quit_Error is propagated when the main GTK+ loop was quitted before the request was serviced.

generic
   type User_Data is private;
package Generic_Message is ...

The package is provided for execution of user-defined procedures on the GTK+ context asynchronously to the caller. The package formal parameter is the data type passed to a call. Note that the type is not limited because the values of are marshaled. Note also that this package does not provide any performance advantages over synchronous calls. It is provided for rare cases when servicing the request requires completion of the caller. For example, when the caller is a task that performs some lengthy action which upon completion should destroy a widget that owns the task. When widget destruction is requested from the task it will also wait for the task to finalize. When accomplished synchronously this would deadlock. Observe that for this reason use of Generic_Message on the GTK+ context is meaningless, though allowed.

type Handler_Procedure is access procedure (Data : in out User_Data);

This is the procedure to be called on the GTK+ context.

procedure Send
          (  Handler : Handler_Procedure;
             Data    : User_Data;
             Timeout : Duration := 0.5
          );

This call requests execution of Handler with Data parameters. It does not block the caller unless the maximum number of asynchronous requests is reached (see Set_Max_Asynchronous). When called on the context of the main loop, the callback is postponed until messages loop end. Data is marshaled. Program_Error is propagated when Init was not called. Quit_Error is propagated when the main GTK+ loop was quitted before the request was serviced. Busy_Error is propagated when Timeout is expired.

1.1. Example

The following is a small test program illustrating use of the package.

1.2. Debugging tools

The package Gtk.Main.Router also provides two procedures for simple debugging and messaging purposes:

procedure Say
          (  Message       : UTF8_String;
             Title         : UTF8_String := "";
             Mode          : UTF8_String := Stock_Dialog_Info;
             Justification : Gtk_Justification := Justify_Left;
             Parent        : access Gtk_Widget_Record'Class := null
          );

This procedure pops a dialog box with Message in it. It can be called from any task.

procedure Trace
          (  Message : UTF8_String;
             Break   : Boolean := False
          );

This procedure represents a simplified tracing mechanism. When called first time it pops up a dialog box containing Message.

All further calls add new messages to the box. The dialog box has the check button break. When this button is checked each call to Trace blocks until user confirmation. When the button is unchecked the procedure adds its message without waiting. The button break can be checked at any time. Once checked it will hold on the next message. Then the button next continues execution until a next message. It has the effect of checking the break button. The button record continues without further confirmations, and thus it resets the check state of break. The button quit closes the box. The box will be automatically reopened empty on the next message. The parameter Break when set to true overrides unchecked break button and enters wait after adding the message. This can be useful when the message indicates a certain error.

procedure Trace
          (  Error : Exception_Occurence;
             Break : Boolean := True
          );

This procedure is a shortcut for

Trace (Ada.Exceptions.Exception_Information (Error), Break);

It typically is used like:

   ... -- A suspicious code fragment
exception
   when Error : others => -- Breaks execution, shows
      Trace (Error);      -- the exception message
      raise;
end;

1.3. GNAT-specific debugging tools

The child package Gtk.Main.Router.GNAT_Stack provides procedures Say and Trace of the same profile as its parent. They add stack symbolic traceback to the message printed:

procedure Say
          (  Message       : UTF8_String;
             Title         : UTF8_String := "";
             Mode          : UTF8_String := Stock_Dialog_Info;
             Justification : Gtk_Justification := Justify_Left;
             Parent        : access Gtk_Widget_Record'Class := null
          );
procedure Trace
          (  Message : UTF8_String;
             Break   : Boolean := False
          );
procedure Trace
          (  Error : Exception_Occurence;
             Break : Boolean := True
          );

Trace can be used as follows:

   ... -- A suspicious code fragment
exception
   when Error : others =>                       -- Breaks execution, shows
      Gtk.Main.Router.GNAT_Stack.Trace (Error); -- the exception message
      raise;                                    -- and the call stack
end;

The procedures use GNAT.Traceback.Symbolic for this purpose. Please refer to the GNAT Reference Manual for the prerequisites of.

procedure Set_Log_Trace
          (  Domain : String;
             Level  : Log_Level_Flags := Log_Fatal_Mask or Log_Level_Critical
          );
procedure Set_Log_Trace;

This procedure is used for catching GTK+ log messages. Usually these messages indicate very severe errors which are extremely difficult to track down, because they occur in the core libraries of GTK+ written in C. The procedure eases debugging such errors by causing a log message to appear in the tracing dialog box accompanied by the call stack dump. Doing that it stops the application until user confirmation. The parameters of the procedure are Domain indicating which messages has to be caught and Level specifying the severity level of. When this procedure is called several times its effect is accumulated. Some domain names are:

• Gtk stands for the Gtk library;
• GLib-GObject is for GLib's objects;
• GtkAda+ is used by this library.

Please refer GTK+ documentation for further domain names. When Domain and Level are omitted, all messages from all domains are caught. Note that this happens only if the messages are not caught by other means, i.e. it acts as a default message handler.

procedure Indent
          (  Message : UTF8_String;
             Break   : Boolean  := False;
             Step    : Positive := 2
          );

This procedure places Message in the messages box adding as the prefix a chain of spaces, which length is Step multiplied by the depth of the call step: It can be useful to trace recursive subprograms in order to determine which instance of the caller has printed the message.

type Log_Filter is abstract tagged limited private;

An object of this type is used to filter messages additionally to the domain and level.

function Ignore
         (  Filter  : not null access Log_Filter;
            Domain  : String;
            Level   : Log_Level_Flags;
            Message : UTF8_String
         )  return Boolean is abstract;

This function returns true if the message must be ignored. If any of the filters returns true the message is not traced.

1.4. Translation of addresses into the source lines

Right mouse click on the trace dialog brings the dropdown menu expanded with two items as shown below (the look and feel may vary as it depends on the operating system):

The choice paste stack traceback is used to paste GNAT exception traceback. The traceback is a part of Exception_Information. It has the format:

0x5e1b6e 0x5e109f 0x5f1c28 0x5f850a 0x5f7511 0x5f06df 0x59544b 0x5a66a5

When pasted it is replaced by the symbolic traceback as the utility addr2line does. The prerequisite is that the application is build with debug information included.

1.5. Source navigation

The choice go to the source location is used to open a file in the GPS. When the mouse cursor point at a traceback line which contains a reference to a source file, then GPS is asked to open the file at the line specified in the traceback line. The prerequisites are

1. The application has debug information;
2. The file is a part of the project;
3. GPS is running and has the project open;
4. GPS is running in the server mode;
5. The port GPS server listens must be available for the application (e.g. not blocked by the firewall).

The server mode of GPS is activated as follows:

> gps --server=50000

Here 50000 is the TCP/IP port GPS will listen. The port number is specified in the Init call.

1.6. Debugging GTK+ programs

It is sometimes quite tedious to track down bugs in a GTK+ application. Many of the safeguards, the Ada language has, do not really work with GTK+. Errors are usually detected at run-time at the context of the GTK+, where little can be done. Here is a summary of the basic techniques for designing and debugging GTK+ programs in Ada:

Begin your GTK+ program with:

begin
   Gtk.Main.Init;
   Gtk.Main.Router.Init; -- Start routing and tracing
   Gtk.Main.Router.GNAT_Stack.Set_Log_Trace ("Gdk");
   Gtk.Main.Router.GNAT_Stack.Set_Log_Trace ("Gtk");
   Gtk.Main.Router.GNAT_Stack.Set_Log_Trace ("GLib-GObject");
   Gtk.Main.Router.GNAT_Stack.Set_Log_Trace ("GtkAda+");
   Gtk.Main.Router.GNAT_Stack.Set_Log_Trace ("my_application");
   ...
   Gtk.Main.Main;

This enables routing and tracing, while catching GTK+ errors. The procedure Set_Log_Trace described above turns on tracing for the errors in Gdk, Gtk, GLib, GtkAda contributions and the application itself. The most of errors happen in event handlers. Note that a handler is called on the context of GTK+. Propagation of an exception out of a handler will most likely crash the application. This is the reason why all handlers should rather catch exceptions. E.g.:

procedure Button_Clicked (Button : access Gtk_Button_Record'Class) is
begin
   ...
exception
   when Error : others =>
      Log
      (  "my_application",
         Log_Level_Critical,
         "Fault in Button_Clicked:" & Exception_Information (Error)
      );
end Button_Clicked;

In combination with an initialization shown above, the effect of an exception in Button_Clicked will cause the trace dialog popped up, with the exception information in it. The application will be stopped. If the GPS is active and in the server mode, you will be able to navigate the call stack of the error inspecting the source code locations as described above. The application can be continued from the trace dialog, which will not crash it. As it was said above it is meaningless to propagate an exception out of an event handler.

The GPS in server mode is started as:

> gps --server=50000 my-project-name.gpr

Note that even release version can be built with the -g switch. This does not have any effect on the program performance, since it only adds the debugging information necessary to translate stack trace back into source line locations.

2. GTK+ tree view

Notes about sizing tree views placed in a scrolled window. The tree view widget does not automatically shrink or expand its parent scrolled window. The effect is that the vertical height of the tree view is often too small when the scrolled window containing it is in turn a part of a top level window, such as a dialog. An application might wish to find a better size for the scroll window than GTK+ does. That is - no blank rows beneath the last visible row, all expanded rows visible when there is not too many of them. The following code snippet illustrates a possible approach:

. . . -- Placing items into the model, expanding rows, etc
declare
   Dummy  : GInt;
   Height : GInt;
   Width  : GInt;
begin
   Tree_View.Columns_Autosize;                     -- Size columns
   Tree_View.Get_Preferred_Width  (Dummy, Width);  -- Query the integral
   Tree_View.Get_Preferred_Height (Dummy, Height); -- tree view size
   Tree_View.Set_Size_Request                      -- Set new size
   (  GInt'Min (Width,  600),
      GInt'Min (Height, 500)
   );
end;

Here Get_Preferred_Width and Get_Preferred_Height ask the tree view to return its integral size. Note that at this point the rows should be already added and expanded as necessary. Then Set_Size_Request sets the new tree view size to the returned height and width, but not greater than some reasonable limits, usually chosen to fit into the screen size or parent window. The container widget (a scrolled window) will automatically resize together with the tree view.

2.1. Abstract custom model

The package Gtk.Tree_Model.Abstract_Store provides an abstract base type (Gtk_Abstract_Model_Record) for developing custom tree view models:

type Gtk_Abstract_Model_Record is
   abstract new Gtk_Root_Tree_Model_Record with private;

Objects of the types derived from Gtk_Abstract_Model_Record will implement the GtkTreeModel interface. The implementation maps GTK+ virtual functions to the abstract primitive operations of the base type. A derived type shall provide implementations for them. The abstract primitive operations to override are:

• Children returns the first child node of a tree node. Each node of the tree corresponds to a row;
• Get_Column_Type returns the type of a column. Columns are numbered from 0;
• Get_Flags returns the flags of the model;
• Get_Iter converts a path to the corresponding iterator. An iterator uniquely identifies a row. A path uniquely identifies a sequence of rows bound by a parent-child relation;
• Get_N_Columns returns the number of columns;
• Get_Path converts an iterator to the corresponding path;
• Get_Value returns a cell value specified by the column and row. The latter is indicated by an iterator;
• Has_Child returns true if a tree node has children;
• Next returns an iterator to the next sibling of a node;
• Nth_Child returns an iterator to the Nth child of a node;
• N_Children returns the number of children of a node;
• Parent returns an iterator to the parent node;
• Previous returns an iterator to the previous sibling of a node.

The following operations have a default implementation:

• Ref_Node notifies that a node is in use
• Unref_Node notifies that a node is no more in use

Other operations:

• Finalize can be overridden to provide an Ada-style finalization. When overridden, it must call the default implementation from the body;
• Initialize shall be called by any derived type;
• Register shall be called once, to register the GTK+ type of the implementation.

function Children
         (  Model  : not null access Gtk_Abstract_Model_Record;
            Parent : Gtk_Tree_Iter
         )  return Gtk_Tree_Iter is abstract;

This function return the first child of Parent or Null_Iter. When Parent is Null_Iter, the first top node should be the result.

procedure Finalize
          (  Model : not null access Gtk_Abstract_Model_Record
          )  is null;

This procedure is called upon object destruction. The override, if any, shall call the parent's version.

function Get_Column_Type
         (  Model : not null access Gtk_Abstract_Model_Record;
            Index : GInt
         )  return GType is abstract;

This function returns the type of the model column. Index is the column number, zero based. GType_Invalid is returned when the column does not exist.

function Get_Flags (Model : not null access Gtk_Abstract_Model_Record)
   return Tree_Model_Flags is abstract;

This function returns the flags of Model.

function Get_Iter
         (  Model : not null access Gtk_Abstract_Model_Record;
            Path  : Gtk_Tree_Path
         )  return Gtk_Tree_Iter is abstract;

This function converts Path to iterator. The result is Null_Iter when the path is invalid.

function Get_N_Columns (Model : not null access Gtk_Abstract_Model_Record)
   return GInt is abstract;

This function returns number of columns in Model.

function Get_Path
         (  Model : not null access Gtk_Abstract_Model_Record;
            Iter  : Gtk_Tree_Iter
         )  return Gtk_Tree_Path is abstract;

This function gets the path from an iterator. A path is dynamically allocated and has to be freed later using Path_Free.

procedure Get_Value
          (  Model  : not null access Gtk_Abstract_Model_Record;
             Iter   : Gtk_Tree_Iter;
             Column : Gint;
             Value  : out GValue
          )  is abstract;

This procedure is used to query a value from Model for the iterator Iter and column Column (zero-based). The result is returned in Value. Values are freed by the caller using Unset. It means that the implementation must always initialize Value. When no value can be returned because of some errors an invalid value can be used instead:

Init (Value, GType_Invalid);

Here the value is initialized for the type GType_Invalid.

function Has_Child
         (  Model : not null access Gtk_Abstract_Model_Record;
            Iter  : Gtk_Tree_Iter
         )  return Boolean is abstract;

This function returns true if the row indicated by Iter has a child in Model.

procedure Initialize
          (  Model   : not null access Gtk_Abstract_Model_Record'Class;
             Type_Of : GType
          );

This procedure has to be called by any derived type upon object construction. Normally it is the first call of its Initialize, which in turn is called from a Gtk_New. The parameter Type_Of must be a value returned by Register called with the name assigned to the GTK+ type of the derived type. Note that Register shall be called only once. So its result must be stored somewhere in the package that derives the type. The following code snippets illustrate use of Register: The package specification:

type My_Model_Record is new Gtk_Abstract_Model_Record with private;
type My_Model is access all My_Model_Record'Class;

function Get_Type return Gtk_Type;
function Gtk_New (Model : out My_Model);
procedure Initialize (Model : not null access My_Model_Record'Class);
. . . -- Overriding primitive operations

The package body:

My_Model_Type : GType := GType_Invalid;

function Get_Type return Gtk_Type is
begin
  if My_Model_Type = GType_Invalid then
     My_Model_Type := Register ("MyModel");
  end if;
  return My_Model_Type; -- Registering the GTK+ type
end Get_Type;

procedure Initialize (Model : not null access My_Model_Record'Class) is
begin
   Initialize (Model, Get_Type);
   . . . -- Custom initialization
end Initialize;

procedure Next
          (  Model : not null access Gtk_Abstract_Model_Record;
             Iter  : in out Gtk_Tree_Iter
          )  is abstract;

This function moves Iter to the next sibling node. Null_Iter is the result when there is no more siblings.

function Nth_Child
         (  Model  : not null access Gtk_Abstract_Model_Record;
            Parent : Gtk_Tree_Iter;
            N      : GInt
         )  return Gtk_Tree_Iter is abstract;

This gets iterator to a child of Parent by its zero-based number N. Null_Iter is the result when there is no such child. When Parent is Null_Iter roots are returned.

function N_Children
         (  Model : not null access Gtk_Abstract_Model_Record;
            Iter  : Gtk_Tree_Iter := Null_Iter
         )  return GInt is abstract;

This function returns the number of children of Iter.

function Parent
         (  Model : not null access Gtk_Abstract_Model_Record;
            Child : Gtk_Tree_Iter
         )  return GInt is abstract;

This function returns the parent of Child. For roots Null_Iter is returned.

procedure Previous
          (  Model : not null access Gtk_Abstract_Model_Record;
             Iter  : in out Gtk_Tree_Iter
          )  is abstract;

This function moves Iter to the previous sibling node. Null_Iter is the result when there is no more siblings.

procedure Ref_Node
          (  Model : not null access Gtk_Abstract_Model_Record;
             Iter  : Gtk_Tree_Iter
         );

The default implementation does nothing.

function Register
         (  Name       : String;
            Signals    : Chars_Ptr_Array := Null_Array;
            Parameters : Signal_Parameter_Types :=
                            Null_Parameter_Types
         )  return GType;

For each non-abstract derived type of Gtk_Abstract_Model_Record this function shall be called once before creation of the first object of. For each element of Signals a signal with this name and parameters from the corresponding row of Parameters is added to the registered type. The rows of the array Parameters are padded by GType_None.

procedure Unref_Node
          (  Model : not null access Gtk_Abstract_Model_Record;
             Iter  : Gtk_Tree_Iter
         );

The default implementation does nothing.

2.1.1. Custom model example

Here we consider using the package Gtk_Abstract_Model_Record for developing a custom tree view model. The custom store is based on a doubly-linked list of records. The records contain imaginary transaction data:

• Account number,
• User name,
• Amount,
• Timestamp.

The subdirectory test_gtkada contains the full source:

The package defines the types of the record fields. Then Gtk_Transaction_Store_Record is derived from Gtk_Abstract_Model_Record. According to GtkAda conventions this type is not used directly. An access type Gtk_Transaction_Store to it is used instead. The rationale is that GTK+ objects are subject of garbage collection. So they are never allocated on the stack and are never freed explicitly.

Finally the public part of the interface contains the procedure Insert used to add new record to the store and the procedure Gtk_New, whch creates an empty store.

In the private part the Gtk_Transaction_Store_Record completed. It holds a pointer to the first element of a doubly-linked list of Transaction_Record items. Then the abstract primitive operations of Gtk_Abstract_Model_Record get overridden:

And finally Transaction_Record is defined. It contains the data fields described above and two pointers to link items of the list.

The implementation of the package specification:

The implementation starts with the definition of the GTK+ type used for the store object. The type cannot be determined until GTK+ runs, so it is initialized as invalid and will be resolved later at run-time.

The first thing we need to consider is an implementation of the iterators. An iterator unambiguously identifies a row of the store. In our case rows are represented by Transaction_Record accessed via pointers. So it is naturally to pack pointers into iterators. In GTK+ an iterator has four fields. Three of them have address size. We will use the first field to store a pointer to Transaction_Record. The function To_Iter converts a pointer to the item to an iterator. It simply converts the pointer to an address and stores it into the first address field. The backward conversion provides the function To_Ptr. Null-iterators are converted to null. A more advanced implementation would perform some additional sanity checks, but this is out of the scope of this small example.

Our store is a pure list, so there is no children and parents, i.e neither row can have any child rows.

The store publishes 8 columns, which GTK+ types of are reported by Get_Column_Type. The columns 0..2 represent Account No., User name and Amount. The following 5 represent the time stamp. In a more advanced application you might want to put more complex types into columns, for example by using handles. For such types you would probably need to develop a custom cell renderer as well.

The function Get_Flags informs GTK+ about heuristics it can apply to the store, like that the store is not a tree. The value Tree_Model_Iters_Persist indicates that the iterators stay valid after changes applied to rows. This is true in out case because iterators are just wrapped pointers.

This function converts a tree path to an iterator. In GTK+ a path is an array of child numbers. All children rows of a row are enumerated from 0. So any path is equivalent to some iterator and reverse. In our case conversion first checks if the path is exactly one item long. After this check the child number is the number of the row. We walk through the list of records to that record. Then the pointer to it is converted to an iterator using To_Iter function described above. Observe, that this has O(n) complexity. Obviously, for relatively long lists a more elaborated implementation would definitely use some indexing schema to improve performance.

The function Get_N_Columns returns the number of columns. The function Get_Path is reverse to Get_Iter described above.

For the given row and column Get_Value returns the value of the cell. The row is specified by an iterator. The column is by its zero-based number. The parameter Value is the result. The pair of GTK+ procedures Init, Set_type is the way to place a value there. Init specifies the GTK+ type of the value. Set_type stores the value there. The caller is responsible to call Unset on Value.

The procedure Gtk_New is the store factory. It creates a new store object. First it checks if the GTK+ type was already registered. If not it registers it under the name GtkTransactionStore. This name can be later used in the GTK+ files for instance. Register shall be called once before any use of any store object. Initialize shall be called for each store object. Note that it takes the GTK+ type as a paramter.

Finalize is provided for custom finalization. It is analogous to the Ada.Finalization's one. The implementation calls to the parent Finalize and then deletes all items of the list.

There is no children, it is not a tree.

The procedure Insert allocates a new record, initializes its fields according to the parameters and appends the record to the list. Then, very importantly, it emits a GTK+ signal that a row was inserted. For this it calls Row_Inserted of Gtk.Tree_Model. The parameters are the path and the iterator of the new row. Get_Path and To_Iter are used to obtain them.

The procedure Next moves the iterator to the next row.

The function Nth_Child returns an iterator to the n-th child of a row. Note that when Parent is null-iterator the result is the n-th row. This is the only case we should take care of. Remember the note of O(n) complexity of such operations on doubly-linked lists.

This function is analogous to Nth_Child, it counts the children. Again our case is when the parameter is null-iterator.

We have no children and parents, so the implementation of Parent is trivial.

The same subdirectory test_gtkada contains a small test program for this store in the file test_custom_store.adb. The program creates a store and tree view. Observe, that it adds some records to the store in a quasi-concurrent way from GTK+ timer to illustrate that tree view would properly react on the content changes.

2.2. Generic sortable model

The generic package Gtk.Tree_Model.Generic_Sort provides an interface to GtkTreeSortable. The package is instantiated with a custom tree model derived from Gtk_Abstract_Model_Record:

generic
   type Tree_Model_Record (<>) is
      new Gtk_Abstract_Model_Record with private;
   type Tree_Model is access all Tree_Model_Record'Class;
package Gtk.Tree_Model.Generic_Sort is
   ...

The generic parameters are a type derived from Gtk_Abstract_Model_Record and an access type used with it. The package defines a new model based on one of Gtk_Abstract_Model_Record, which has the sorted data of the underlying model. The type of the new model is:

type Gtk_Tree_Model_Sort_Record is
   new Gtk_Tree_Model_Record with private;
type Gtk_Tree_Model_Sort is
   access all Gtk_Tree_Model_Sort_Record'Class;

The type Gtk_Tree_Model_Sort_Record is normally used as a base type for a derived user type which overrides the function Compare, which is used to when the widget sorts its contents:

function Compare
         (  Store : not null access Gtk_Tree_Model_Sort_Record;
            Left  : Gtk_Tree_Iter;
            Right : Gtk_Tree_Iter
         )  return Gtk.Missed.Row_Order;

This function is used for sorting if Set_Sort_Func was called for the current sort column or as a default. Left and Right are the iterators in the unsorted model. The current sort column can be queried using Get_Sort_Column_ID. The unsorted model can be obtained using Get_Model. Note that the sort order as returned by Get_Sort_Column_ID should not influence the result of this function. The caller automatically translates the result into descending order if necessary. The type Row_Order is defined in Gtk.Missed as follows:

type Row_Order is (Before, Equal, After);

The procedure Set_Sort_Func is used to activate Compare for desired columns:

procedure Set_Sort_Func
          (  Store  : not null access Gtk_Tree_Model_Sort_Record'Class;
             Column : GInt
          );
procedure Set_Sort_Func
          (  Store : not null access Gtk_Tree_Model_Sort_Record'Class
          );

The second variant activates Compare for default sorting. Default sorting in GTK+ refers to an unsorted model.

2.3. Custom cell renderer

This package Gtk.Cell_Renderer.Abstract_Renderer provides an abstract base type Gtk_Abstract_Renderer_Record_for GTK+ tree view column renderers. An object of this type functions as GtkCellRenderer. The type is declared as:

type Gtk_Abstract_Renderer_Record is
   abstract new Gtk_Cell_Renderer_Record with private;

A derived type shall override the following primitive operations:

function Get_Aligned_Area
         (  Cell      : not null access Gtk_Abstract_Renderer_Record;
            Widget    : not null access Gtk_Widget_Record'Class;
            Flags     : Gtk_Cell_Renderer_State;
            Cell_Area : Gdk_Rectangle
         )  return Gdk_Rectangle is abstract;

This function returns the are inside Cell_Area that would be used to render the content.

function Get_Size
         (  Cell      : not null access Gtk_Abstract_Renderer_Record;
            Widget    : not null access Gtk.Widget.Gtk_Widget_Record'Class;
            Cell_Area : Gdk_Rectangle
         )  return Gdk_Rectangle is abstract;
function Get_Size
         (  Cell   : not null access Gtk_Abstract_Renderer_Record;
            Widget : not null access Gtk.Widget.Gtk_Widget_Record'Class
         )  return Gdk_Rectangle is abstract;

These functions return the desired area of the renderer in the form of a rectangle.

procedure Render
          (  Cell            : not null access Gtk_Abstract_Renderer_Record;
             Context         : Cairo_Context;
             Widget          : not null access Gtk_Widget_Record'Class;
             Background_Area : Gdk_Rectangle;
             Cell_Area       : Gdk_Rectangle;
             Flags           : Gtk_Cell_Renderer_State
          )  is abstract;

This procedure is called to perform rendering. Context is the drawing context. Background_Area is the rectangle around the cell which includes the border. Cell_Area is the area where things should be drawn into.

Other operations include:

overriding
function Activate
         (  Cell   : not null access Gtk_Abstract_Renderer_Record;
            Event  : Gdk_Event;
            Widget : not null access Gtk_Widget_Record'Class;
            Path            : UTF8_String;
            Background_Area : Gdk_Rectangle;
            Cell_Area       : Gdk_Rectangle;
            Flags           : Gtk_Cell_Renderer_State
         )  return Boolean;

This function can be overridden to make the renderer activatable. Such a renderer may hold a toggle button in it. The default implementation returns false. Path specifies the activation event location, e.g. the tree path to the model.

procedure Commit (Cell : not null access Gtk_Abstract_Renderer_Record);

This procedure is used to notify the tree view about the changes made (this is used for editable renderers). From here the render changes the model.

procedure Finalize (Cell : not null access Gtk_Abstract_Renderer_Record);

This procedure can be overridden to provide an Ada-style finalization. When overridden, it must call the default implementation from the body.

function Get_Mode (Cell : not null access Gtk_Abstract_Renderer_Record)
   return Gtk_Cell_Renderer_Mode;

This function returns the renderer mode, such as inert, editable or activatable.

function Get_Path (Cell : not null access Gtk_Abstract_Renderer_Record)
   return UTF8_String;

This function returns returns the path of the cell being edited.

overriding
procedure Get_Preferred_Height
          (  Cell   : not null access Gtk_Abstract_Renderer_Record;
             Widget : not null access Gtk_Widget_Record'Class;
             Minimum_Height : out GInt;
             Natural_Height : out GInt
          );

This procedure retrieves the renderer's height if rendered to Widget. The default implementation re-dispatches to Get_Size.

overriding
procedure Get_Preferred_Height_For_Width
          (  Cell   : not null access Gtk_Abstract_Renderer_Record;
             Widget : not null access Gtk_Widget_Record'Class;
             Width  : GInt;
             Minimum_Height : out GInt;
             Natural_Height : out GInt
          );

This procedure retrieves the renderer's width for given Width if rendered to Widget. The default implementation re-dispatches to Get_Size.

overriding
procedure Get_Preferred_Get_Width
          (  Cell   : not null access Gtk_Abstract_Renderer_Record;
             Widget : not null access Gtk_Widget_Record'Class;
             Minimum_Height : out GInt;
             Natural_Height : out GInt
          );

This procedure retrieves the renderer's width if rendered to Widget. The default implementation re-dispatches to Get_Size.

overriding
procedure Get_Preferred_Width_For_Height
          (  Cell   : not null access Gtk_Abstract_Renderer_Record;
             Widget : not null access Gtk_Widget_Record'Class;
             Height : GInt;
             Minimum_Width : out GInt;
             Natural_Width : out GInt
          );

This procedure retrieves the renderer's width for given Height if rendered to Widget. The default implementation re-dispatches to Get_Size.

procedure Get_Property
          (  Cell          : not null access Gtk_Abstract_Renderer_Record;
             Param_ID      : Property_ID;
             Value         : out GValue;
             Property_Spec : Param_Spec
          );

This procedure returns the value of a GTK+ property the renderer understands. The properties are the values the renderer can show. Each property is specified as a text string which then appears in Add_Attribute. The procedure shall initialize Value. It is the caller's responsibility to unset it.

overriding
function Get_Request_Mode
         (  Cell : not null access Gtk_Abstract_Renderer_Record;
         )  return Gtk_Size_Request_Mode;

This function returns preferred method of estimation of the area needed to renderer content. The default implementation returns Constant_Size.

function Get_X_Align
         (  Cell : not null access Gtk_Abstract_Renderer_Record
         )  return GFloat;
function Get_X_Pad
         (  Cell : not null access Gtk_Abstract_Renderer_Record
         )  return GUInt;
function Get_Y_Align
         (  Cell : not null access Gtk_Abstract_Renderer_Record
         )  return GFloat;
function Get_Y_Pad
         (  Cell : not null access Gtk_Abstract_Renderer_Record
         )  return GUInt;

These functions return some widget properties.

procedure Initialize
          (  Cell    : not null access Gtk_Abstract_Renderer_Record'Class;
             Type_Of : GType
          );

This procedure has to be called by any derived type upon object construction. Normally it is the first call of its Initialize, which in turn is called from a Gtk_New. The parameter Type_Of must be a value returned by Register called with the name assigned to the GTK+ type of the derived type. Note that Register shall be called only once. So its result must be stored somewhere in the package that derives the type.

type Commit_Callback is access procedure
     (  Cell : not null access Gtk_Abstract_Renderer_Record'Class
     );

procedure On_Commit
          (  Cell    : not null access Gtk_Abstract_Renderer_Record;
             Handler : not null Commit_Callback;
             After   : Boolean := False
          );

This procedure can be used to attach a handler to the commit signal.

function Register
         (  Name : String;
            Init : not null C_Class_Init := Base_Class_Init'Access
         )  return GType;

This procedure is used to register the GTK+ type of the renderer. The following code snippets illustrate use of Register: In the package specification:

type My_Renderer_Record is new Gtk_Abstract_Renderer_Record with private;
type My_Renderer is access all My_Renderer_Record'Class;

function Get_Type return Gtk_Type;
function Gtk_New (Cell : out My_Renderer);
overriding
procedure Initialize (Cell : not null access My_Renderer_Record'Class);
. . . -- Overriding primitive operations

In the package body:

My_Renderer_Type : GType := GType_Invalid;

function Get_Type return Gtk_Type is
begin
  if My_Renderer_Type = GType_Invalid then
     My_Renderer_Type := Register ("MyRenderer", My_Class_Initialize'Access);
  end if;
  return My_Renderer_Type; -- Registering the GTK+ type
end Get_Type;

procedure Initialize (Cell : not null access My_Renderer_Record'Class) is
begin
   Initialize (Cell, Get_Type);
   . . . -- Custom initialization
end Initialize;

Usually Register specifies a user-provided procedure to be called upon initialization of the GTK+ class of the renderer. It is necessary to declare GTK+ properties of the renderer. The procedure has the following profile:

type C_Class_Init is access procedure (Class : GObject_Class);
pragma Convention (C, C_Class_Init);

The parameter Class is the class to initialize. When a user-defined procedure is provided, it shall call to Base_Class_Init from its body, before it begins to declare properties of the renderer.

procedure Set_Mode
          (  Cell : not null access Gtk_Abstract_Renderer_Record;
             Mode : Gtk_Cell_Renderer_Mode
          );

This procedure sets the renderer's mode property. The renderer can be inert, activatable or editable.

procedure Set_Property
          (  Cell          : not null access Gtk_Abstract_Renderer_Record;
             Param_ID      : Property_ID;
             Value         : GValue;
             Property_Spec : Param_Spec
          );

This procedure sets the value of a GTK+ property. The default implementation calls the parent's version.

function Start_Editing
         (  Cell   : not null access Gtk_Abstract_Renderer_Record;
            Event  : Gdk_Event;
            Widget : not null access Gtk_Widget_Record'Class;
            Path            : UTF8_String;
            Background_Area : Gdk_Rectangle;
            Cell_Area       : Gdk_Rectangle;
            Flags           : Gtk_Cell_Renderer_State
         )  return Gtk_Widget;

This procedure is called for editable cells upon start editing. The implementation returns a widget responsible for editing or null. The widget returned should implement the Gtk_Cell_Editable interface. Otherwise, the behaviour of the renderer will be as if Start_Editing would return null. The caller is responsible to Ref the result it gets and to Unref where appropriate. The default implementation returns null. A typical implementation would create a Gtk_Cell_Editable widget, like Gtk_Entry, initialize it with the current renderer's value, connect to the editing_done and focus_out_event signals of the widget and return the widget as the result.

overriding
procedure Stop_Editing
          (  Cell      : not null access Gtk_Abstract_Renderer_Record;
             Cancelled : Boolean
          );

This procedure ends editing.

The widget declares commit signal, which is emitted by a call to the procedure Commit. This signal a tree view widget or its model would like to connect to, when an editable renderer is used in the widget. The handler of the signal would set the modified value into the tree model.

2.4. Editable renderers

The protocol of an editable GTK+ cell render is as follows. When the renderer's mode is Cell_Renderer_Editable (see Get_Mode) then:

1. Upon editing activation the cell renderer receives a start editing notification. This is translated into a call to the Start_Editing primitive operation;
2. If Start_Editing rejects editing attempt, it returns null. Otherwise it creates a widget with Gtk_Cell_Editable interface. Usually it is Gtk_Entry. Normally the returned widget should be initialized with the current cell value. The implementation might also wish to connect to the editing_done and focus_out_event signals of the widget;
3. Upon focus_out_event the handler of calls Stop_Editing with Canceled set to true;
4. Upon editing_done the handler of takes the edited value from the widget. If it decides to dismiss the value, it calls to Stop_Editing with Canceled set to true. If it accepts the value, it calls Stop_Editing with Canceled set to false followed by a call to Commit, which notifies about the changes made. Commit emits the signal commit;
5. The renderer does not touch the tree model. It is the responsibility the commit handler. Within the handler Get_Path can be called to determine the string representation of the row, of which cell has been edited (see Get_Iter_From_String). Note that due to limitations of GTK+, there is no obvious way to determine the column of the cell. It should become known to the handler in some other way. The handler sets the value into the tree model. This ends editing.

2.5. Fixed-point renderer

The package Gtk.Cell_Renderer_Fixed provides a simple, yet, usable example a cell renderer. It defines a fixed-point numeric renderer. The numbers are represented in the form xxxx.yyyy using facilities of the package Ada.Text_IO.Float_IO. The renderer aligns all numbers along the positions of their decimal points. The renderer is editable. The package defines the rendrerer's type:

type Gtk_Cell_Renderer_Fixed_Record is
   new Gtk.Cell_Renderer.Abstract_Renderer.
       Gtk_Abstract_Renderer_Record with private;
type Gtk_Cell_Renderer_Fixed is
   access all Gtk_Cell_Renderer_Fixed_Record'Class;

and the operations on it:

function Get_Type return Gtk_Type;

This function returns the GTK+ type of the fixed-point renderers.

procedure Gtk_New
          (  Cell  : out Gtk_Cell_Renderer_Fixed;
             After : Natural := 0
          );

This procedure creates a new renderer. The parameter After determines the number of decimal places shown after the point.

procedure Initialize
          (  Cell  : access Gtk_Cell_Renderer_Fixed_Record'Class;
             After : Natural
          );

This procedure shall be called from any type derived from Cell_Renderer_Fixed upon initialization.

The renderer provides the following properties:

• value is the rendered value. The type of the property is GDouble.
• after is the number of digits shown after the decimal point. The type of the property is GUint.

2.4.1. Annotated source code of the renderer

The package specification file:

The type Gtk_Cell_Renderer_Fixed_Record is derived from the abstract cell renderer type Gtk_Abstract_Cell_Renderer_Record. The GtkAda convention is that the names of implementation types ends with the suffix _Record. The public type to use is Cell_Renderer_Fixed, which is an access type. GTK+ uses a reference counting to collect objects like Gtk_Abstract_Cell_Renderer_Record, more or less transparently to the user.

The procedure Finalize of the parent type is overridden to have an ability to clean-up some internal data upon object finalization.

This function determines the area of the widget which will be used by the renderer.

Get_Property needs to be overridden to provide interface to the renderer's properties. The properties is the way GTK+ communicates with the renderer when it renders a cell. It extracts the cell value and sets the corresponding property of the renderer. Then it ask the renderer about the size required to show the value or ask it to render the value.

The procedures Get_Size are called to get the screen size required to render the currently set property of the renderer. The function Get_Type returns the GTK+ type of the renderer.

The procedure Get_New provides the standard way to create a new renderer object. Internally, it calls to Iniialize, which shall be called by any derived type upon initialization of the latter.

Render is called to display the renderer's property on the screen. Set_Property is a counterpart of Get_Property described above.

Because the renderer is editable Start_Editing is overridden to provide the functionality.

The renderer's implementation consists of the following fields:

• Text is a widget actually responsible for rendering texts;
• Value holds the current value property of the renderer;
• After keeps the after property;
• Max_Offset is the number of pixels to the place where the decimal point is shown. It is evaluated as the maximum length of among all cells of the rendered column. Which allows to align the numbers. This might happen not working if new rows are added without re-rendering all column cells, or when rows are removed.
• Height and Width are in pixels. They are the rendered text's height and width for the current value of the property value.
• Left_Width is the width of the rendered text before the decimal point. Max_Offset is calculated as a maximum of Left_Width;
• Focus_Out.is the ID of the current focus_out_event handler. It is needed to disconnect the handler upon end of editing.

Here we declare the handlers for editing_done and focus_out_event. The handles will be connected to a Gtk_Entry widget, which will perform editing. We also instantiate User_Callback to connect Editing_Done and User_Return_Callback to connect Focus_Out.

The implementation of the package:

The package GDouble_IO is an instance of Ada.Text_IO.Float_IO used to render GDouble numbers to text.

The variable Renderer_Type holds the GTK+ type of the renderer. It is queried by Get_Type to determine whether the type is already registered in GTK+. Upon registration the procedure Class_Init will be  called. The next two constants are the identifiers of the renderer's properties. GTK+ translates property name to the identifier when it calls Get_Property or Set_Property.

The procedure Class_Init is called by Get_Type once upon type registration. The implementation of Class_Init calls to the parent's Class_Init and then registers the properties of the renderer. Each renderer object will have these two properties.

The handler of editing_done receives the Gtk_Entry widget as the parameter. The second parameter is the user data identifying the renderer. First the handler disconnects the renderer from focus_out_event. Then it takes the text from the entry widget and converts it to GDouble. Upon any error it cancels editing by calling Stop_Editing with Canceled = true. Otherwise it stores the new value into the renderer. Then it stops editing using, this time by using Stop_Editing with Canceled = false. Then it calls Commit to emit the commit signal.

Finalize releases the field Text and then calls the parent type's Finalize.

The handler of focus_out_event simply calls to Editing_Done and returns.

This function evaluates the area which will be used to render the value, see implementation of Render below.

The implementation of Get_Property is straightforward. It receives the identifier of the property and has to initialize the parameter Value with the value of the type of the property. Then it sets the property value into Value.

The procedure Update is used internally to evaluate the renderer's state. First it checks if the field Text is already initialized. If not, it creates it using Create_Pango_Layout call. Note that it cannot be made earlier, upon renderer construction, because Create_Pango_Layout requires a widget parameter. The procedure Finalize will destroy this field.

Then the value of the property value is rendered to text using the procedure Put. It is guaranteed UTF-8, so there is no need to care about any conversions from Latin-1 encoding. The next two loops determine where the output starts in the output string Text (the variable Start_Pos) and where the decimal point is located (the variable Point_Pos).

The rendered text is set into the field Text and its size in pixels is calculated. After that, Index_To_Line_X is used to calculate the horizontal offset to the point. The result is in units, so it is converted to pixels; before placing into Left_Width field. The value of Left_Width influences Max_Offset, which is the maximum of all Left_Widths seen.

Then the total width of the cell is calculated as the sum of the space required before the decimal point and after it. The former obviously is Max_Offset. The latter is the maximum the space required for the current value and one has been required before the call (stored Cell.Width - Cell.Max_Offset).

This variant of Get_Size is interested in only width and height of the rendered value. The implementation calls to Update and then returns the fields Width and Height.

This variant is a little bit more complex because it specifies the surrounding rectangle. Again, Update is called and the positions of the left top corner are evaluated using alignment properties of the renderer.

The function Get_Type checks if the renderer's GTK+ type is not yet registered and if so, then registers it by calling to Register of Gtk_Abstract_Renderer_Record. Two parameters of the function Register are the name of the GTK+ class and the class initialization procedure. Class_Init described above is used for the second.

The implementation of Gtk_New allocates the object and calls to Initialize. The first thing Initialize has to do is to call parent's Initialize of Gtk_Abstract_Renderer_Record. The second parameter of it is the renderer's type. So it calls to Get_Type, which in turn registers the GTK+ type as necessary.

The implementation of Render first calls to Get_Size to update the renderer's state and get the rectangle where the value has to be drawn into. The current style context of the widget is stored in Style. The drawing context is saved. Then the clipping rectangle determined by the parameter Cell_Area is set in the context. After that Render_Layout is called to draw the text of the field Text. The position of the left-top corner of the output is determined by the Cell_Area parameter of the procedure Render. Get_X_Pad and Get_Y_Pad are called to obtain actual padding. Area.X and Area.Y are returned by Get_Size and relative to the corner. The horizontal offset should be additionally adjusted to the difference between the maximal width of the output field before the decimal point and the width of the rendered text of the current value. Finally the context is restored.

The procedure Set_Property is reverse to Get_Property described above.

The procedure Start_Editing is called upon editing request. For example when a cell is doubly clicked. First the renderer formats a string with the current value of the cell. The parameters of Start_Editing are similar to ones of Render. The additional parameter Path identifies the row the cell being edited belongs to. You don't need to store this string because the base type does it for you. Get_Path can be later used to obtain it. First, Start_Editing stores the current value in Text (1..Start_Pos).

Then an entry widget is created and the text is set into the widget. Some additional settings are applied to the widget. Its horizontal alignment is set from the corresponding renderer's property. Its frame is removed. The content is selected (Select_Region). Then Editing_Done and Focus_Out are connected to the widget. Finally, it is shown and returned. Note that there is no need to care about removing the widget, it is a responsibility of the caller.

2.4.2. Test program

File test_gtk_fixed.adb:

The above is mostly standard GTK+ initialization stuff, except the procedure Commit and instantiation of User_Callback for it. The variables Table_View is a tree view widget and its scroll bar. The procedure Commit is attached to the renderer to store editing changes into the list store. It uses Get_Iter_From_String applied to Get_Path to obtain the iterator of the edited row. Then it queries the value from the renderer and stores it into the first column of the row. The package Test_Gtk_Fixed_Handlers is the following instantiation of event handlers:

File test_gtk_fixed_handlers.ads:

File test_gtk_fixed.adb (continued):

This fragment creates a list store (Table) consisting of one column of GDouble data. The column is filled with randomly generated numbers from in the range -50..50. Finally the store is attached to the widget.

File test_gtk_fixed.adb (continued):

Here the two columns are added to the tree view widget. The first column uses Gtk_Cell_Renderer_Fixed to render the first column of the list store. Note that Add_Attribute refers to the property value of the renderer. The renderer is set to editable mode using Set_Mode. The procedure Commit is connected to the commit signal of the renderer. The second column uses the standard text renderer to render the same first column of the store.

File test_gtk_fixed.adb (continued):

Finally the scroll bar is added to the widget, all things are shown and messages loop is entered. The result might look like:

2.6. Columned model

The package Gtk.Tree_Model.Columned_Store provides a derived tree model. The model contains columns of the reference model composed in n columns. When the reference model itself has m columns then the derived model will have total n·m columns. The cells of the reference model are arranged top-bottom, left-to-right as shown on the figure:

Reference model, m=3		Derived columned model, with n=3 major columns
a1 b1 c1 a2 b2 c2 a3 b3 c3 a4 b4 c4 a5 b5 c5 a6 b6 c6 a7 b7 c7 a8 b8 c8		a1 b1 c1 a4 b4 c4 a7 b7 c7 a2 b2 c2 a5 b5 c5 a8 b8 c8 a3 b3 c3 a6 b6 c6

The model is flat as a list and contains the immediate descendants of a node from the reference model. Note also the model itself does not have means to manipulate its content. When it is necessary to modify the content, the reference model is dealt with. The columned model will automatically follow the changes made on the reference model. This includes translation of the reference model signals into ones of the columned model. For example reference model row removal may manifest itself as a series of columned model signals like row changing and row deletion. Additionally to the standard signals of a tree model the signal root-changed is emitted immediately after changing the root of the columned store. This may happen, for example, when the root of the columned model is deleted from the reference one. That causes it to change to the most nested ancestor node.

type Gtk_Columned_Store_Record is
   new Gtk_Abstract_Model_Record with private;
type Gtk_Columned_Store is
   access all Gtk_Columned_Store_Record'Class;

The following subprograms are defined in the package:

function From_Columned
         (  Model  : not null access Gtk_Columned_Store_Record;
            Iter   : Gtk_Tree_Iter;
            Column : Positive
         )  return Gtk_Tree_Iter;
function From_Columned
         (  Model  : not null access Gtk_Columned_Store_Record;
            Path   : Gtk_Tree_Path;
            Column : Positive
         )  return Gtk_Tree_Path;

These functions convert an iterator or path of the columned model to the corresponding iterator or path of the reference model. The additional parameter is the major column number 1..n, where n is the number of columns specified upon model creation in Gtk_New. The result is Null_Iter or null path on an error. Note that the returned path has to be freed using Path_Free.

function Get_Column_Height
         (  Model  : not null access Gtk_Columned_Store_Record;
            Column : Positive
         )  return Natural;

This function returns the number of filled rows in the major column Column. The result is 0 when Column is greater than the number of major columns.

function Get_Major_Columns
         (  Model : not null access Gtk_Columned_Store_Record
         )  return Positive;

This function returns the number of major columns, i.e. the parameter Columns as it was specified upon model creation in Gtk_New or Set_Reference.

function Get_Reference
         (  Model : not null access Gtk_Columned_Store_Record
         )  return Gtk_Tree_Model;

This function returns the reference model.

function Get_Reference_Iter
         (  Model  : not null access Gtk_Columned_Store_Record;
            Row    : Positive;
            Column : Positive
         )  return Gtk_Tree_Iter;

This function composes an iterator to the reference model row specified by its Row and Column. The result is Null_Iter when Row and Column do not specify a reference model row.

function Get_Root
         (  Model : not null access Gtk_Columned_Store_Record
         )  return Gtk_Tree_Iter;

This function returns an iterator of reference model to the root of the derived model. All nodes of the derived model are immediate descendants of.

function Get_Root
         (  Model : not null access Gtk_Columned_Store_Record
         )  return Gtk_Tree_Path;

This function returns the path in reference model to the root of the derived model. The result shall be freed using Path_Free if not null.

function Get_Rows
         (  Model  : not null access Gtk_Columned_Store_Record;
            Filled : Boolean
         )  return Natural;

This function returns the number of rows. When the parameter Filled is true, only complete rows count. Otherwise any does.

function Get_Row_Width
         (  Model : not null access Gtk_Columned_Store_Record;
            Row   : Positive
         )  return Natural;

This function returns the number of filled columns in the row Row. The result is 0 when Row is greater than the number of rows.

procedure Gtk_New
          (  Model     : out Gtk_Columned_Store;
             Reference : not null access Gtk_Root_Tree_Model_Record'Class;
             Columns   : Positive;
             Root      : Gtk_Tree_Iter := Null_Iter
          );

The model is constructed by specifying the reference model, the number of columns and the derived model's root (the parameter Root). By default the root is one of the reference model. The derived model will contain only immediate children on Root.

procedure Gtk_New (Model : out Gtk_Columned_Store);

This variant construct an empty model which can be later bound to a reference model using Set_Reference.

procedure Initialize
          (  Model     : not null access Gtk_Columned_Store_Record'Class;
             Reference : not null access Gtk_Root_Tree_Model_Record'Class;
             Columns   : Positive;
             Parent    : Gtk_Tree_Iter
          );
procedure Initialize (Model : access Gtk_Columned_Store_Record'Class);

One of these procedures is to be called by any derived type from its Initialize.

function Is_Ancestor
         (  Model : not null access Gtk_Columned_Store_Record;
            Iter  : Gtk_Tree_Iter
         )  return Boolean;
function Is_Ancestor
         (  Model : not null access Gtk_Columned_Store_Record;
            Path  : Gtk_Tree_Iter
         )  return Boolean;

These functions return true if the root of the columned model is an ancestor of the iterator or path specified in the reference model.

function Is_Descendant
         (  Model : not null access Gtk_Columned_Store_Record;
            Iter  : Gtk_Tree_Iter
         )  return Boolean;
function Is_Descendant
         (  Model : not null access Gtk_Columned_Store_Record;
            Path  : Gtk_Tree_Iter
         )  return Boolean;

These functions return true if the root of the columned model is a descendant of the iterator or path in the reference model.

function To_Columned
         (  Model : not null access Gtk_Columned_Store_Record;
            Iter  : Gtk_Tree_Iter
         )  return Gtk_Tree_Iter;
function To_Columned
         (  Model : not null access Gtk_Columned_Store_Record;
            Path  : Gtk_Tree_Path
         )  return Gtk_Tree_Path;

These functions convert an iterator or path of the reference model to the corresponding iterator or path of the columned model. The result is Null_Iter or null path on an error. Note that the returned path has to be freed using Path_Free.

procedure To_Columned
          (  Model  : not null access Gtk_Columned_Store_Record;
             Iter   : in out Gtk_Tree_Iter;
             Column : out Positive
          );

This procedure is a variant of iterator conversion which also yields the major column number 1..n, where n is the number of columns specified upon model creation in Gtk_New.

procedure Set_Null_Reference
          (  Model : not null access Gtk_Columned_Store_Record;
             Root_Changed : Boolean := True
          );

This procedure makes the model empty. An empty model has no reference model associated with. The parameter Root_Changed causes root-changed emitted when Model there had a reference model. This procedure can be used if the reference model have to undergo massive changes you don't want to follow one by one in the columned model. The columned model can be detached using this procedure, then changes can be applied and, finally the columned model is reattached again using Set_Reference.

procedure Set_Reference
          (  Model     : not null access Gtk_Columned_Store_Record;
             Reference : not null access Gtk_Root_Tree_Model_Record'Class;
             Columns   : Positive;
             Root      : Gtk_Tree_Iter
          );

This procedure changes the model, the number of columns and the root. One should use this procedure with care, because clients of the columned model might be unprepared to the changes in columns number and types. When the root or the reference model is indeed changed root-changed is emitted.

procedure Set_Root
          (  Model : not null access Gtk_Columned_Store_Record;
             Root  : Gtk_Tree_Iter
          );

This procedure changes the model root. When the root is indeed changed, root-changed is emitted.

2.7. Extension model

The package Gtk.Tree_Model.Extension_Store provides a derived tree model. The model extends its reference model by adding new columns to it:

Reference model, columns a, b, c		Derived model, new columns d, e
a1 b1 c1 a2 b2 c2 a3 b3 c3 a4 b4 c4		a1 b1 c1 d1 e1 a2 b2 c2 d2 e2 a3 b3 c3 d3 e3 a4 b4 c4 d4 e4

The reference model itself is not changed, it is the derived model which keeps new columns data. It is possible both to derive multiple extension models adding different columns to the same reference model, as well as to use an extension model as a reference one with adding new columns to it. Internally the derived model is a tree store containing new columns. The extended model does not have its own row insertion and deletion operations. Instead of this the rows are manipulated in the reference model. The effect of these operations mirrors on all extended models of. When the reference model rows get inserted, their values in the extended columns can be set using Set_Extension. For this the reference model iterator should be converted to an iterator of the extension model with To_Extension. When the reference model rows get deleted, the corresponding cells of the extension model as removed automatically. This model translates the reference model signals into ones of the extension model. Thus handlers of row-changed, row-inserted, row-deleted etc can be directly used on the extension model.

type Gtk_Extension_Store_Record is
   new Gtk_Abstract_Model_Record with private;
type Gtk_Extension_Store is
   access all Gtk_Extension_Store_Record'Class;

The following subprograms are defined in the package:

procedure Changed
          (  Model : not null access Gtk_Extension_Store_Record;
             Path  : Gtk_Tree_Path;
             Iter  : Gtk_Tree_Iter
          );

This procedure is called upon row change in the reference model. An implementation can override this procedure to modify extension columns using an appropriate call to Set_Extension. Alternatively it can handle row-changed signal which the provided implementation of this procedure emits. The parameters Path and Iter identify the row in the extension model.

procedure Deleted
          (  Model : not null access Gtk_Extension_Store_Record;
             Path  : Gtk_Tree_Path
          );

This procedure is called when a reference model row has been deleted. The parameter Path is a (now invalid) path to the deleted row in the extension model. It cannot be used anymore. The default implementation emits the signal row-deleted. When overriding this procedure carefully consider calling this one from there.

procedure Deleting
          (  Model : not null access Gtk_Extension_Store_Record;
             Path  : Gtk_Tree_Path;
             Iter  : Gtk_Tree_Iter
          );

This procedure is called upon row deletion. Differently to Delete it is called just before deleting the extension row. An implementation shall not modify either the reference or the extension model here. The parameters Path and Iter identify the row being deleted in the extension model. Note that they cannot be converted to the reference model or used to access it in any other way, because the corresponding row in it is already deleted there. Also at this point the extension store and its reference model are unsynchronized so it makes usually no sense to access the reference model anyway. The primary objective of this procedure is to save the data of the extension columns upon deletion. The default implementation does nothing.

function From_Extension
         (  Model : not null access Gtk_Extension_Store_Record;
            Iter  : Gtk_Tree_Iter
         )  return Gtk_Tree_Iter;
function From_Extension
         (  Model : not null access Gtk_Extension_Store_Record;
            Path  : Gtk_Tree_Path
         )  return Gtk_Tree_Path;

These functions convert an iterator or path of the extension model to an iterator or path in the reference model. Note that the returned path has to be freed using Path_Free.

function Get_Extension_Types
         (  Model : not null access Gtk_Extension_Store_Record
         )  return GType_Array;

This function returns the types of the extension columns. When the result is not empty, its bounds are set so that the array indices correspond to zero-based column numbers (as in tree model).

function Get_Reference
         (  Model : not null access Gtk_Extension_Store_Record
         )  return Gtk_Tree_Model;

This function returns the reference model.

procedure Gtk_New
          (  Model     : out Gtk_Extension_Store;
             Reference : not null access Gtk_Root_Tree_Model_Record'Class;
             Types     : GType_Array
          );

This procedure creates a new extension model. The result is returned via the parameter Model. The parameter Reference is the reference model. The parameter Types is an array of the extension columns types. For each element of the array a column of the corresponding type is added.

procedure Gtk_New
          (  Model : out Gtk_Extension_Store;
             Types : GType_Array
          );

This variant creates an empty model. It can get a reference model assigned later using Set_Reference.

procedure Initialize
          (  Model     : not null access Gtk_Extension_Store_Record'Class;
             Reference : not null access Gtk_Root_Tree_Model_Record'Class;
             Types     : GType_Array
          );
procedure Initialize
          (  Model : not null access Gtk_Extension_Store_Record'Class;
             Types : GType_Array
          );

One of these procedures has to be called by any derived type from its Initialize.

procedure Inserted
          (  Model : not null access Gtk_Extension_Store_Record;
             Path  : Gtk_Tree_Path;
             Iter  : Gtk_Tree_Iter
          );

This procedure is called upon row insertion in the reference model. An implementation can override this procedure to initialize extension columns using an appropriate call to Set_Extension. Alternatively it can handle row-inserted signal which the provided implementation of this procedure emits. The parameters Path and Iter identify the row in the extension model. When overriding this procedure carefully consider calling this one from there.

procedure Set_Extension
          (  Model  : not null access Gtk_Extension_Store_Record'Class;
             Iter   : Gtk_Tree_Iter;
             Column : Positive;
             Value  : Boolean
          );
procedure Set_Extension
          (  Model  : not null access Gtk_Extension_Store_Record'Class;
             Iter   : Gtk_Tree_Iter;
             Column : Positive;
             Value  : GInt
          );
procedure Set_Extension
          (  Model  : not null access Gtk_Extension_Store_Record'Class;
             Iter   : Gtk_Tree_Iter;
             Column : Positive;
             Value  : UTF8_String
          );
procedure Set_Extension
          (  Model  : not null access Gtk_Extension_Store_Record'Class;
             Iter   : Gtk_Tree_Iter;
             Column : Positive;
             Value  : GValue
          );

These procedures are used to modify the extended model cells. The parameter Iter is an extension store iterator to the row of the cell. The parameter Column is the number of the extension column of the cell. The parameter Value is the value to set. Note that there is no universal way to change the reference model cells. That depends on the reference model type. When the type is known, the the reference model cell can be modified using the corresponding operations of the type with the iterator converted to the reference model iterator (see To_Extension).

procedure Set_Null_Reference
          (  Model : not null access Gtk_Extension_Store_Record
          );

This procedure sets the reference model empty. This can be used to before undertaking massive changes in the reference model. First the reference model is set to null, then changes are applied and finally Set_Reference is used to assign the reference model back.

procedure Set_Reference
          (  Model     : not null access Gtk_Extension_Store_Record;
             Reference : not null access Gtk_Root_Tree_Model_Record'Class
          );

This procedure changes the reference model. The side effect of this operation is that the extension columns become empty. The new reference model should have exactly same types of columns as its predecessor, because clients using the model might not anticipate column number and types change.

function To_Extension
         (  Model : not null access Gtk_Extension_Store_Record;
            Iter  : Gtk_Tree_Iter
         )  return Gtk_Tree_Iter;
function To_Extension
         (  Model : not null access Gtk_Extension_Store_Record;
            Path  : Gtk_Tree_Path
         )  return Gtk_Tree_Path;

These functions convert an iterator or path of the reference model to an iterator or path to the corresponding row in the extension model. Note that the returned path has to be freed using Path_Free.

2.8. Abstract browser model and widgets

The package Gtk.Abstract_Browser provides an abstract model of a caching tree browsing model. The model contains directories of items physically stored outside the model. Browsing the items is accomplished through primitive operations to interface an external items store, such as a file system for instance or a database. The model caches items as necessary, transparently to the tree views rendering the model. The policy of caching can vary and is controlled by concrete implementations of the model. A typical application example is a model of a file system. A tree view widget rendering the model will cause the file system directories cached when expanded in the tree view.

The package also provides two specialized tree view widgets for rendering the directories tree and the items of a directory.

2.8.1. Abstract caching store

The type of the caching store is:

type Gtk_Abstract_Directory_Record is
   abstract new Gtk_Tree_Model_Record with private;
type Gtk_Abstract_Directory is
   access all Gtk_Abstract_Directory_Record'Class;

It is a tree model with the abstract primitive operations implemented in order to access the items of. The items are uniquely identified by their full names globally or else by their simple names within a directory. The data types for the item names are;

type Item_Name is new UTF8_String;
type Item_Path is new UTF8_String;

The subprograms of the package do not interpret the content of objects of these types, they are transparently passed as is. The following requirements are imposed on paths and names:

• A path uniquely specifies an item (globally);
• A name uniquely specifies an item within its directory;
• The item name can be obtained from its path. Though it is not required that name were a physical cart the path. The way it is obtained from the path is up to implementation.
• A path can be constructed from the item name and its containing directory path.

type Item_Type is new UTF8_String;

This type characterizes an item. It can be the name of a stock image used to indicate the item type, as a directory, executable file etc.

type Directory_Item
     (  Name_Length : Natural;
        Kind_Length : Natural
     )  is
record
   Policy    : Caching_Policy;
   Directory : Boolean;
   Name      : Item_Name (1..Name_Length);
   Kind      : Item_Type (1..Kind_Length);
end record;

This type is used for querying items. Its fields are as follows:

• Policy controls the caching policy applied to the item;
• Directory is true when item is a directory;
• Name is the simple name of the item;
• Kind is the item type.

The model has three columns:

1. GType_String is Item_Type converted to UTF8_String;
2. GType_String is Item_Name converted to UTF8_String;
3. GType_Int is in 0..2 when the item is a directory and 3 otherwise.

It contain only directory items. So when viewed using a tree view it will show the cached items directory tree. An unfiltered tree model of all cached items can be obtained from the model using Get_Tree_Store. That model contains all cached items and the same columns as Gtk_Abstract_Directory. Both represent different view of the same cache.

Abstract_Directory_Class_Name : constant String :=
   "GtkAbstractDirectory";

This string constant defines the GTK+ class name of the model.

type Icon_Type is (Stock_ID, GIcon, Pixbuf, Themed);
type Icon_Data (Kind : Icon_Type; Length : Natural) is record
   case Kind is
      when Stock_ID | Themed =>
         Name : String (1..Length);
      when GIcon =>
         Icon : GObject;
      when Pixbuf =>
         Image : Gdk_Pixbuf;
    end case;
end record;

This type is used to return icons of items. The discriminant Kind defines the icon type:

• Stock_ID specifies an stock icon by its ID (the field Name);
• GIcon is an icon object (Unref must be used to free it);
• Pixbuf is an image object (Unref must be used to free it);
• Themed specifies a themed icon by its name.

Abstract primitive operations. The following abstract primitive operations have to be implemented by a derived type:

function Compare
         (  Store     : not null access Gtk_Abstract_Directory_Record;
            Directory : Item_Path;
            A, B      : Directory_Item;
            By_Name   : Boolean
         )  return Row_Order is abstract;

This function is used to sort items of a directory. The parameter Directory is the path of the directory containing the items A and B being compared. The parameter By_Name when true instructs to ignore anything but the item names. The result has the type Row_Order.

function Get_Directory
         (  Store : not null access Gtk_Abstract_Directory_Record;
            Item  : Item_Path
         )  return Item_Path is abstract;

This function obtains the containing directory path from Item. Name_Error is propagated when Item has no parent.

function Get_Name
         (  Store : not null access Gtk_Abstract_Directory_Record;
            Item  : Item_Path
         )  return Item_Name is abstract;

This function obtains the item name by its path Item.

function Get_Path
         (  Store     : not null access Gtk_Abstract_Directory_Record;
            Directory : Item_Path;
            Name      : Item_Name
         )  return Item_Path is abstract;

This function composes a path from the directory path and the item name in the directory.

procedure Progress
          (  Store     : not null access Gtk_Abstract_Directory_Record;
             Directory : Item_Path;
             State     : GDoubleRead
          );

This procedure is called to indicate the progress of a caching operation. Directory is the path of the folder being cached. State is the overall progress. The default operation emits the signal progress. Note that the procedure is no called to reflect every change. Too frequent occurrences are filtered out. however it is always called when State reaches 1.0.

function Read
         (  Store : not null access Gtk_Abstract_Directory_Record
         )  return Directory_Item is abstract;

This function returns the next item of the directory for which Rewind was called before. The result is the item found. The internal cursor is advanced to the item. When an implementation detects an error, it has several options to handle this. It can

• raise End_Error and ignore the rest of the directory;
• return a special item and raise End_Error by the next call;
• raise Data_Error with the effect of removing the directory content from the cache.

Giving any error messages is the responsibility of Read not the caller. The procedures from the package never call Read without calling Rewind before it. It is also never called so that several directories could be browsed simultaneously. So an application need not to keep any history for more than one directory search. The field Policy of the result returned by Read controls caching of directories:

• Cache_Ahead immediately caches the directory. If all directories of a path have this policy the tree along this path will be cached in advance. This policy is used when the directory tree becomes available once, or when it would make no sense to postone its caching;
• Cache_Expanded caches the directory first when its parent get expanded. This ensures that the view of any item is always consistent. This policy is used for directories which are always browsable;
• Cache_Never instructs not to cache a directory until its children get visible. This policy can be used for the directories which caching might be expensive or else not always possible. An attempt to do it will be postponed until the user would try to browse the tree item corresponding to the directory.

function Rewind
         (  Store     : not null access Gtk_Abstract_Directory_Record;
            Directory : Item_Path
         )  return Directory_Item is abstract;

This function is called before Read to initiate a new directory search. An implementation typically prepares iteration of the directory specified by its path Directory. It is guaranteed that no nested or multiple iterations happen. When the parameter Directory is an empty string, the cursor has to be set to the first root item (of the root directory). Otherwise it is set to the first item in the directory. The cursor is implementation maintained. The function returns the new state of the directory being iterated. (The first item of will be returned by the consequent Read.) Usually the returned state does not change and the implementation can return the predefined constant:

Directory_Entered : constant Directory_Item := ...

But in some cases an implementation might wish to change the directory type in order to show a different icon for a mounted volume, for example. In such cases the result's policy is interpreted as follows:

• Cache_Ahead indicates that the directory will be cached and its state does not change. This is the most frequently used policy. All other fields are ignored. One can also use the constant value Directory_Entered for this purpose;
• Cache_Expanded is like above, but the directory name and type replace the values in the cache. The field Directory is ignored;
• Cache_Never prevents of the directory iteration. The directory name and type replace the current ones in the cache. When the discriminant Directory is changed to false, the directory is replaced by an item in the cache.

When access to the directory requires credentials or some user action, then Rewind is a place to ask the user for. When such request fails, due to cancellation, for example, then Cache_Never can be returned. When Data_Error exception is propagated out of Rewind, the corresponding item is removed from the cache.

Primitive operations:

procedure Finalize
          (  Store : not null access Gtk_Abstract_Directory_Record
          );

This subprogram has to be called upon destruction when overridden.

function Get_Cached
         (  Store : not null access Gtk_Abstract_Directory_Record;
            Path  : Item_Path
         )  return Directory_Item;

This function returns description of an already cached item by its path. Constraint_Error is propagated when Path does not specify a cached item. Name_Error is propagated when Path is illegal.

function Get_Tree_Store
         (  Store : not null access Gtk_Abstract_Directory_Record
         )  return Gtk_Tree_Store;

This function returns a tree store of the cached directory items. It contains all items of, both directories and leaf items. The model can be modified in order to add and remove items, though a safer way to do it is to use Created, Deleted and Refresh calls. This model is referenced by the model Store and thus it should not be referenced or unreferenced using Ref or Unref.

procedure Read_Error
          (  Store : access Gtk_Abstract_Directory_Record;
             Text  : UTF8_String;
             Path  : Item_Path
          );

This procedure emits read-error signal.

procedure Rewind_Error
          (  Store : not null access Gtk_Abstract_Directory_Record;
             Text  : UTF8_String;
             Path  : Item_Path
          );

This procedure emits rewind-error signal.

procedure Trace
          (  Store : not null access Gtk_Abstract_Directory_Record;
             Depth : Natural;
             Text  : String
          );

This procedure is called to trace certain actions. The parameter Depth is the depth of recursion, which can be used to decorate Text. The default implementation calls to Trace.

Class-wide operations:

procedure Cache
          (  Store : not null access Gtk_Abstract_Directory_Record'Class;
             Item  : Item_Path
          );

This procedure  caches the path to the item specified by its path. The directory structure is queried as necessary and cached. The root directory full name is empty string.

procedure Changed
          (  Store     : not null access Gtk_Abstract_Directory_Record'Class;
             Directory : Item_Path
          );

This procedure synchronizes the cache with the directory. The parameter Directory is the path of the directory changed. This procedure is used when the application gets aware of some, usually massive changes in the directory structure made from outside. In that case it uses Changed to resynchronize the store with it.

procedure Created
          (  Store     : not null access Gtk_Abstract_Directory_Record'Class;
             Directory : Item_Path;
             Item      : Directory_Item
          );

This procedure is called to synchronize the store when a new item gets inserted from outside. The parameter Item describes the item created. The parameter Directory is the path of the directory of. For the root directory items the parameter is an empty string. An alternative to Created is refreshing the cache at the directory containing the inserted item (see Changed). The latter might be preferable upon massive items insertions.

procedure Deleted
          (  Store : not null access Gtk_Abstract_Directory_Record'Class;
             Item  : Item_Path
          );

This procedure is called to synchronize the store when an item gets deleted from outside. Item is the path of the deleted item. The following code snippet illustrates moving an item from one directory to another with cache notification:

declare
   Old_Path : Item_Path := Get_Path (Store, Old_Directory, Name);
   Item     : Directory_Item := Get_Cached (Store, Old_Path);
begin
   ... -- Renaming the item using some external means
   Deleted (Store, Old_Path);            -- Removed at old directory
   Created (Store, New_Directory, Item); -- Added at the new directory
end;

function Get_Depth
         (  Store : not null access Gtk_Abstract_Directory_Record'Class
         )  return Natural;

This function returns depth of nesting calls while caching is active.

function Get_Tracing
         (  Store : not null access Gtk_Abstract_Directory_Record'Class
         )  return Traced_Actions;

This function returns the current state of tracing.

procedure Initialize
          (  Store : not null access Gtk_Abstract_Directory_Record'Class
          );

This procedure is to called upon initialization by the derived type upon object construction.

procedure Renamed
          (  Store    : not null access Gtk_Abstract_Directory_Record'Class;
             Old_Path : Item_Path;
             New_Name : Item_Name
          );

This procedure is called to synchronize the store when an item has been renamed outside while it stays in the same directory. The parameter Old_Path identifies the item. New_Nam is the new name of.

procedure Set_Tracing
          (  Store   : not null access Gtk_Abstract_Directory_Record'Class;
             Tracing : Traced_Actions
          );

This procedure changes tracing status. The parameter Tracing defines which actions need to be traced.

Signals. There are additional to standard tree model signals which Gtk_Abstract_Disrectory can emit:

• item-inserted is emitted when an item has been added to the model. The first parameter is an unfiltered iterator to the inserted row, the second parameter is the path to the row;
• item-renamed is emitted when an item has been renamed. The first parameter is an unfiltered iterator to the row of the item. The second parameter is the old item name;
• item-deleted is emitted when an item has been deleted. The first parameter is the full path of deleted item;
• item-deleting is emitted before item deletion. The first parameter is an unfiltered iterator to the row of the item, the second parameter is the path to the row;
• progress is emitted to indicate progress of a caching operation. The first parameter is the path to the folder being cached. The second parameter is GType_Double is a value in range 0.0..1.0;
• read-error is emitted when Read propagates an exception. The behavior of the model is that the corresponding directory item is not cached and the exception is handled. The handler emits this signal with the first string parameter (GType_String) containing the message text and the second string parameter containing the path of the directory being read. The signal handler may for instance show the message in a messages console;
• refreshed is emitted when an iterator of the store has been refreshed. The parameter is the path in the store that was refreshed (GType_String);
• rewind-error is emitted when Rewind propagates an exception. The exception handler removes the directory from the cache and emits the signal with the exception message and the directory path as the first parameter and second parameters correspondingly.

2.8.2. Directory tree view

The package Gtk.Abstract_Browser defines the type of a specialized tree view widget for indication of the directory tree of a Gtk_Abstract_Directory store:

type Gtk_Directory_Tree_View_Record is
   new Gtk_Tree_View_Record with private;
type Gtk_Directory_Tree_View is
   access all Gtk_Directory_Tree_View_Record'Class;

The tree view filters shows only directories. It has single selection mode. The following operations are defined:

function Get_Cache
         (  Widget : not null access Gtk_Directory_Tree_View_Record
         )  return Gtk_Abstract_Directory;

This function returns the Gtk_Abstract_Directory object used with the directory tree view.

function Get_Current_Directory
         (  Widget : not null access Gtk_Directory_Tree_View_Record
         )  return Item_Path;

This function returns the path of the directory currently selected in the tree view. Name_Error is propagated when there is no directory selected.

function Get_Icon
         (  Widget       : not null access Gtk_Directory_Tree_View_Record;
            Kind         : Item_Type;
            Expanded     : Boolean;
            Has_Children : Boolean;
            Topmost      : Boolean
         )  return Icon_Data;

This function is called to obtain the icon rendered for a directory. The parameter Kind is the type of the directory as it was returned by Read. The parameter Expanded is true if the directory is currently expanded. The parameter Has_Children is true if it has children items in the cache. When it is not, then normally this indicates that the directory is not readable. Topmost is true when the directory is a root. The default implementation returns stock ID gtk-stop when Has_Children is false. Otherwise it returns the value of Kind unless Expanded is true and Kind is gtk-directory. In this latter case it returns gtk-open.

function Get_Name
         (  Widget       : not null access Gtk_Directory_Tree_View_Record;
            Name         : Item_Name;
            Kind         : Item_Type;
            Expanded     : Boolean;
            Has_Children : Boolean;
            Topmost      : Boolean
         )  return Item_Name;

This function is called to obtain the name rendered for a directory. The parameter Name is the directory name. The parameter Kind is the type of the directory as it was returned by Read. The parameter Expanded is true if the directory is currently expanded. The parameter Has_Children is true if it has children items in the cache. When it is not, then normally this indicates that the directory is not readable. The parameter Topmost is true when the directory is a root. The default implementation returns Name.

procedure Gtk_New
          (  Widget   : out Gtk_Directory_Tree_View;
             Store    : not null access Gtk_Abstract_Directory_Record'Class;
             Selected : Item_Path := ""
          );

This procedure creates the widget. The parameter Store is the Gtk_Abstract_Directory object indicated by the widget. The parameter Selected when not empty is the path of the directory to select. The directory tree is expanded as much as possibly in order to make selection. When Selected does not indicate an existing directory, then the most close match is selected.

procedure Initialize
          (  Widget   : not null access Gtk_Directory_Tree_View_Record'Class;
             Store    : not null access Gtk_Abstract_Directory_Record'Class;
             Selected : Item_Path
          );

This procedure has to be called by the derived type from its Initialize.

function Is_Editable
         (  Widget : not null access Gtk_Directory_Tree_View_Record
         )  return Boolean;

This function returns true if Widget allows editing directory names. See Set_Editable.

procedure Name_Commit
          (  Widget   : not null access Gtk_Directory_Items_View_Record;
             Old_Path : Item_Path;
             New_Name : Item_Name
          );

This procedure is called when directory name editing is done. For this the widget must have directory names editing enabled by a call to Set_Editable. The parameter Old_Path identifies the directory. The parameter New_Name specifies a new name for it. When the directory name is valid the implementation can change it outside the cache and when that succeeds notify the cache using Renamed (Get_Cache (Widget), Old_Path, New_Name). The default implementation does nothing. That means it rejects any renaming request.

procedure Set_Current_Directory
          (  Widget    : not null access Gtk_Directory_Tree_View_Record;
             Directory : Item_Path
          );

This procedure selects Directory in the widget. The directory tree is expanded as necessary. Any selected before directory is deselected. The selected one is scrolled into the view. The path to Directory is cached when required. When Directory does not exist the procedure stops by its most nested existing parent.

procedure Set_Editable
          (  Widget   : not null access Gtk_Directory_Items_View_Record;
             Editable : Boolean
          );

By default the item names listed by the widget are not editable. When Set_Editable is called with Editable set to true, then the operator will be able to edit directory names directly. The name input is confirmed through the primitive operation Name_Commit.

2.8.3. Directory items view

The package Gtk.Abstract_Browser defines the type of a specialized tree view widget for indication of the items from some directory of a Gtk_Abstract_Directory store:

type Gtk_Directory_Items_View_Record is
   new Gtk_Tree_View_Record with private;
type Gtk_Directory_Items_View is
   access all Gtk_Directory_Items_View_Record'Class;

The tree view shows items of one directory. It supports features usual for file managers:

• columned items output;
• multiple selection of items;
• editing item names;
• filtering items;
• navigation and selection of items using arrows and page scrolling key;
• navigation and selection of items by the first letter of item name;
• switching to directories by activating them.

Note that as usual the same store may have any number of widgets independently rendering its content.

Directory_Items_Class_Name : constant String :=
   "GtkDirectoryItemsView";

This is the name of the widget's GTK+ class. The widget emits the following signals additionally to the signals of a tree view:

• directory-changed when the directory indicated by the widget has been changed;
• selection-changed when the selection of the widget items has been changed.

The following operations are defined on the widget type:

procedure Activated
          (  Widget : not null access Gtk_Directory_Items_View_Record;
             Index  : Positive
          );

This procedure is called upon activation a directory item. That is when the user clicks doubly on an item. The parameter Index identifies the item. All items from the directory filtered by the widget are enumerated from 1 to Get_Directory_Size. The default implementation when the item is a directory selects it in the directory tree view (if any) which in turn causes the widget to show the items of this directory. When it is not a directory and the item names are editable (see Set_Editable) it starts editing the item name.

procedure Directory_Changed
          (  Widget : not null access Gtk_Directory_Items_View_Record
          );

This procedure is called when the widget is switched to show another directory. The default implementation emits the directory-changed signal.

function Filter
         (  Widget    : not null access Gtk_Directory_Items_View_Record;
            Directory : Boolean;
            Name      : Item_Name;
            Kind      : Item_Type
         )  return Boolean;

This function can be overridden to prevent some items from being visible. The default implementation lets all items in.

procedure Finalize
          (  Widget : not null access Gtk_Directory_Items_View_Record
          );

This subprogram is called upon destruction. It has to be called from its overriding.

function Get_Cache
         (  Widget : not null access Gtk_Directory_Items_View_Record
         )  return Gtk_Abstract_Directory;

This function returns the Gtk_Abstract_Directory object used with by the directory items view.

function Get_Column
         (  Widget : not null access Gtk_Directory_Items_View_Record;
            Index  : Positive
         )  return Positive;

This function returns the column of an item by its index. Constraint_Error is propagated when Index is not in 1..Get_Directory_Size. Note that the number of items and their indices are constrained to only the items filtered by the function Filter.

function Get_Columns
         (  Widget : not null access Gtk_Directory_Items_View_Record
         )  return Positive;

This function returns the number of item columns.

function Get_Current
         (  Widget : not null access Gtk_Directory_Items_View_Record
         )  return Natural;

This function returns the index of the current item. The result is 0 when there is no one. Otherwise it is a number from 1 to Get_Directory_Size. The items in the directory are ordered according to the function Compare.

function Get_Directory
         (  Widget : not null access Gtk_Directory_Items_View_Record
         )  return Item_Path;

This function returns the path of the indicated directory. The path of the root directory is empty.

function Get_Directory_Size
         (  Widget : not null access Gtk_Directory_Items_View_Record
         )  return Natural;

This function returns the number of items in the indicated directory.

function Get_Directory_Tree_View
         (  Widget : not null access Gtk_Directory_Items_View_Record
         )  return Gtk_Directory_Tree_View;

This function returns the directory tree view widget used with Widget. The result is null if there is no any.

function Get_Icon
         (  Widget       : not null access Gtk_Directory_Items_View_Record;
            Name         : Item_Name;
            Kind         : Item_Type;
            Directory    : Boolean;
            Has_Children : Boolean
         )  return Icon_Data;

This function is called to obtain the icon used for an item. The parameters Name, Kind and Directory are the name, the type and the directory of the item as they were returned by Read. The default implementation returns the value of Kind converted to String. Note that the widget is a columned view, so this function can be called for an empty cell of a partially filled row. Such cases can be recognized when Name and Kind are empty in order to return (Stock_ID, 0, ""), so that no icon would appear. When Directory is true and Has_Children is false this usually indicates that the folder is unreadable.

function Get_Index
         (  Widget : not null access Gtk_Directory_Items_View_Record;
            Name   : Item_Name
         )  return Natural;

This function returns the index of a cached item specified by its name. The result is 0 when there is no such item. Note that some items can be filtered out by the function Filter.

function Get_Index
         (  Widget : not null access Gtk_Directory_Items_View_Record;
            Row    : Positive;
            Column : Positive
         )  return Natural;

This function returns the index of an item specified by its row and column. The result is 0 if Row and Column do not identify any item.

function Get_Name
         (  Widget : not null access Gtk_Directory_Items_View_Record;
            Index  : Positive
         )  return Item_Name;

This function returns name of an item by its index. Constraint_Error is propagated when Index is not in 1..Get_Directory_Size.

function Get_Path
         (  Widget : not null access Gtk_Directory_Items_View_Record;
            Name   : Item_Name
         )  return Item_Path;

This function returns the path of an item by its name. It is equivalent to: Get_Path (Widget.Cache, Get_Directory (Widget), Name);

function Get_Path
         (  Widget : not null access Gtk_Directory_Items_View_Record;
            Index  : Positive
         )  return Item_Path;

This function returns path of an item by its index. Constraint_Error is propagated when Index is not in 1..Get_Directory_Size.

function Get_Row
         (  Widget : not null access Gtk_Directory_Items_View_Record;
            Index  : Positive
         )  return Positive;

This function returns the row of an item by its index. Constraint_Error is propagated when Index is not in 1..Get_Directory_Size.

function Get_Selection
         (  Widget : not null access Gtk_Directory_Items_View_Record
         )  return Selection;

This function returns the array of indices of the currently selected items. The type Selection is declared in the package as:

type Selection is array (Positive range <>) of Positive;

The selection type depends on the current selection mode:

function Get_Selection_Mode
         (  Widget : not null access Gtk_Directory_Items_View_Record
         )  return Gtk_Selection_Mode;

This function returns the current selection mode. The default selection mode is Selection_Multiple.

function Get_Selection_Size
         (  Widget : not null access Gtk_Directory_Items_View_Record
         )  return Natural;

This function returns the number of currently selected items.

function Get_Type
         (  Widget : not null access Gtk_Directory_Items_View_Record;
            Index  : Positive
         )  return Item_Type;

This function returns the type of an item by its index. Constraint_Error is propagated when Index is not in 1..Get_Directory_Size.

function Get_Visible_Height
         (  Widget : not null access Gtk_Directory_Items_View_Record
         )  return Natural;

This function returns the number of rows visible in the leftmost visible column of Widget. The widget has to be realized.

function Get_Visible_Width
         (  Widget : not null access Gtk_Directory_Items_View_Record
         )  return Natural;

This function returns the number of columns visible in the topmost visible row of Widget. The widget has to be realized.

procedure Gtk_New
          (  Widget  : out Gtk_Directory_Items_View;
             Tree    : not null access Gtk_Directory_Tree_View_Record'Class;
             Columns : Positive
          );

This procedure creates Widget of directory items view. The parameter Tree is the directory tree view widget associated with. A directory selected in the tree is automatically shown by Widget. Similarly, when the current directory is changed for example when the operator activates a directory item, this item gets selected in Tree and the path to it is expanded. The parameter Columns specifies the number item columns in Widget.

procedure Gtk_New
          (  Widget  : out Gtk_Directory_Items_View;
             Store   : not null access Gtk_Abstract_Directory_Record'Class;
             Columns : Positive;
             Current : Item_Path := ""
          );

This variant is used when no directory tree view has to be associated with the widget. In this case the parameter Store is a Gtk_Abstract_Directory store object which items are indicates: The parameter Current is the path of the directory to show. When empty the root directory is shown. When non-existent the most nested existing parent is shown.

procedure Initialize
          (  Widget  : not null access Gtk_Directory_Items_View_Record'Class;
             Tree    : not null access Gtk_Directory_Tree_View_Record'Class;
             Columns : Positive
          );
procedure Initialize
          (  Widget  : not null access Gtk_Directory_Items_View_Record'Class;
             Store   : not null access Gtk_Abstract_Directory_Record'Class;
             Columns : Positive;
             Current : Item_Path
          );

One of these procedures shall be called from the Initialize of the derived type.

function Input_Event
         (  Widget : not null access Gtk_Directory_Items_View_Record;
            Index  : Positive;
            Event  : Gdk_Event
         )  return Boolean;

This function is called upon a key or button press event not handled otherwise by the widget. It is a convenience function to ease handling events. It has the parameter Index identifying the item on which the event happened. The result is false when the event should be passed to other handlers. The default implementation returns false.

function Is_Directory
         (  Widget : not null access Gtk_Directory_Items_View_Record;
            Index  : Positive
         )  return Boolean;

This function returns true if the item specified by Index is a directory. Constraint_Error is propagated when Index is not in 1..Get_Directory_Size.

function Is_Editable
         (  Widget : not null access Gtk_Directory_Items_View_Record
         )  return Boolean;

This function returns true if Widget allows editing item names listed in it. See Set_Editable.

function Is_Selected
         (  Widget : not null access Gtk_Directory_Items_View_Record;
            Index  : Positive
         )  return Boolean;

This function returns true if the item specified by Index is a selected. Constraint_Error is propagated when Index is not in 1..Get_Directory_Size.

function Locate
         (  Widget : not null access Gtk_Directory_Items_View_Record;
            X, Y   : GDouble
         )  return Natural;

This function returns the index of an item at the coordinates X, Y relative to the Widget's bin_window. The result is 0 when X and Y do not specify any item.

procedure Move
          (  Widget       : not null access Gtk_Directory_Items_View_Record;
             Changed      : out Boolean;
             Modifier     : Gdk_Modifier_Type;
             To           : Natural;
             By           : Integer := 0;
             Fixed_Row    : Boolean := False
             Fixed_Column : Boolean := False
          );

This procedure moves the current position to the item with the index To + By. It does nothing when To is less than 1. When the position after incrementing using By is out of 1..Get_Directory_Size, it is saturated to the nearest existing one. The parameter Modifier controls selection change caused by the operation:

The effect depends on the constraints imposed by the selection mode as specified by Set_Selection_Mode. The parameters Fixed_Row and Fixed_Column when true prevent the row or column of To from being left. This procedure can be used for item navigation. For instance navigation upwards can be achieved by specifying To = Get_Current (Widget) and By = -1. The output parameter Changed is set to true if the position was changed. Otherwise it is set to false.

procedure Name_Commit
          (  Widget : not null access Gtk_Directory_Items_View_Record;
             Index  : Positive;
             Name   : Item_Name
          );

This procedure is called when item name editing is done. For this the widget must have item names editing enabled by a call to Set_Editable. The parameter Index identifies the item. The parameter Name specifies a new name for it. When the item name is valid the implementation can change it outside the cache and when that succeeds notify the cache using Renamed (Widget, Index, Name). The default implementation does nothing.

procedure Refilter
          (  Widget : not null access Gtk_Directory_Items_View_Record
          );

This procedure is called when the item filtering logic changes, i.e. the behavior of the primitive operation Filter alters. The procedure forces scanning the directory items in order to decide whether they should be made visible or not.

procedure Refresh
          (  Widget : not null access Gtk_Directory_Items_View_Record
          );

This procedure refreshes the widget contents.

procedure Renamed
          (  Widget : not null access Gtk_Directory_Items_View_Record;
             Index  : in out Natural;
             Name   : Item_Name
          );

This procedure is provided for convenience. It calls to Renamed upon item renaming. Index identifies the item by its position. Name is the new item name. Constraint_Error is propagated when Index is not in 1..Get_Directory_Size. Note that the result might become invisible as the result of filtering. In this case Index is set to 0. Otherwise it is the renamed item index.

procedure Reset_Selection
          (  Widget : not null access Gtk_Directory_Items_View_Record;
          );

This procedure removes selection of any items.

procedure Selection_Changed
          (  Widget : not null access Gtk_Directory_Items_View_Record
          );

This procedure is called when the selection state changes. The default implementation emits the selection-changed signal.

procedure Set_Editable
          (  Widget   : not null access Gtk_Directory_Items_View_Record;
             Editable : Boolean
          );

By default the item names listed by the widget are not editable. When Set_Editable is called with Editable set to true, the operator will be able to edit the item names. The name input is confirmed through the primitive operation Name_Commit.

procedure Set_Selection
          (  Widget : not null access Gtk_Directory_Items_View_Record;
             Name   : Item_Name;
             State  : Boolean
          );
procedure Set_Selection
          (  Widget : not null access Gtk_Directory_Items_View_Record;
             Index  : Position;
             State  : Boolean
          );

These procedures set selection of an item by its name or else position. The parameter Name or else Index specify the item to select if State is true or deselect if State is false. Nothing happens if Name or Index do not specify any item.

procedure Set_Selection_Mode
          (  Widget : not null access Gtk_Directory_Items_View_Record;
             Mode   : Gtk_Selection_Mode
          );

This procedure changes the selection mode. The default selection mode is Selection_Multiple. Other modes are:

• Selection_None does not allow any item to be selected, when set deselects any selected items;
• Selection_Single allows one or none items selected. When this mode is set items from a multiple selections are deselected except one. When the current item is selected it remains in this state;
• Selection_Browse allows exactly one item selected. When this mode is set and the selection is empty, then the current item is selected. Otherwise from a multiple selection all items are deselected except the current one if possible;
• Multiple_Selection allows any kind of selection.

2.9. Files directory cache and a browsing widget

The package Gtk.Directory_Browser provides an implementations of the abstract browsing model and a customized widget to use with it. It caches and renders the file system directory structure in a two-pane way customary to modern file managers. The widget is a composite widget derived from Gtk_Paned_Record:

The implementation is rather straightforward because all work is actually done by Gtk_Directory_Tree_View and Gtk_Directory_Items_View. The widget just assembles then together and adds scroll bars.

2.9.1. Files directory cache

The type Gtk_Directory is an implementation of Gtk_Abstract_Directory that caches the file system directory structure:

type Gtk_Directory_Record is
   new Gtk_Abstract_Directory_Record with private;
type Gtk_Directory is access all Gtk_Directory_Record'Class;

The full names of Ada.Directories are used as Gtk_Abstract_Directory paths. The simple names of Ada.Directories are used as item names. File_Kind is mapped to Gtk_Abstract_Directory item type. The type value is chosen from the stock items as follows: The value Directory is mapped to gtk-directory, Ordinary_File to gtk-file, Special_File to gtk-execute.

procedure Delete
          (  Store : not null access Gtk_Directory_Record;
             File  : UTF8_String
          );

This procedure is used to remove a file or directory. It synchronizes the cache Store after completion of physical removal.

procedure Finalize (Store : not null access Gtk_Directory_Record);

This procedure is called upon finalization. When overridden it has to be called from the overriding.

procedure Gtk_New
          (  Store   : out Gtk_Directory;
             Policy  : Caching_Policy := Cache_Expanded;
             Tracing : Traced_Actions := Trace_Nothing
          );

This procedure creates a new caching store. The result is returned through the parameter Store. The parameter Policy determines the caching policy. For a discussion concerning different policies see the description of the abstract primitive operation Read. The parameter Tracing specifies, which actions are desired for tracing.

procedure Initialize
          (  Store   : not null access Gtk_Directory_Record'Class;
             Policy  : Caching_Policy;
             Tracing : Traced_Actions
          );

This procedure has to be called from the Initialize of the derived type.

2.9.2. Files directory browsing widget

The directory browsing widget provides functionality close to one of Microsoft explorer. It is a composite widget consisting of two panes. One pane contains a directory tree widget for navigating folders. Another pane contains a directory items widget for browsing files. The widget is derived from the paned widget. Its panes contain scrolled windows which in turn contain the tree and item view widgets:

type Gtk_Directory_Browser_Record is
   new Gtk_Paned_Record with private;
type Gtk_Directory_Browser is
   access all Gtk_Directory_Browser_Record'Class;

The following subprograms are defined on the widget:

function Filter
         (  Widget    : not null access Gtk_Directory_Browser_Record;
            Directory : Boolean;
            Name      : Item_Name;
            Kind      : Item_Type
         )  return Boolean;

This function can be overridden to prevent some items from being visible in the files view pane. The default implementation lets all items in.

function Get_Cache
         (  Widget : not null access Gtk_Directory_Browser_Record
         )  return Gtk_Directory;

The function returns the directory cache associated with the widget.

function Get_Files_View
         (  Widget : not null access Gtk_Directory_Browser_Record
         )  return Gtk_Directory_Items_View;

The function returns the files browsing widget.

function Get_Tracing
         (  Store : not null access Gtk_Directory_Browser_Record
         )  return Traced_Actions;

This function returns the current state of tracing.

function Get_Tree_View
         (  Widget : not null access Gtk_Directory_Browser_Record
         )  return Gtk_Directory_Tree_View;

The function returns the directory tree browsing widget.

procedure Gtk_New
          (  Widget    : out Gtk_Directory_Browser;
             File      : UTF8_String := Current_Directory;
             Columns   : Positive    := 4;
             Vertical  : Boolean     := False;
             Tree_Size : Gtk_Requisition := (Width => 180, Height => 500);
             List_Size : Gtk_Requisition := (Width => 600, Height => 500);
             Store     : Gtk_Directory   := null;
             Tracing   : Traced_Actions  := Trace_Nothing
          );

The procedure creates a new widget. The parameter File is the full name of a file to browse. Its most nested existing parent is selected in the directory tree view. Correspondingly it is shown in the files view. The parameter Columns specifies the number columns in the files view. When the parameter Vertical is false the tree view is shown left of the files view. Otherwise it is shown above. The parameters Tree_Size and List_Size control size of the directory tree and files list panes. The widget wiil try to render them so that no scroll bars will appear. For this the panes will be expanded but not larger than the corresponding parameters specify. The parameter Store is the directory cache to use with the widget. When specified as null a new directory cache is created transparently. The parameter Tracing specifies the actions desired for tracing.

procedure Initialize
          (  Widget    : not null access Gtk_Directory_Browser_Record'Class;
             File      : UTF8_String;
             Columns   : Positive;
             Vertical  : Boolean;
             Tree_Size : Gtk_Requisition;
             List_Size : Gtk_Requisition;
             Store     : Gtk_Directory;
             Tracing   : Traced_Actions
          );

This procedure has to be called from the Initialize of the derived type.

procedure Set_Tracing
          (  Widget  : not null access Gtk_Directory_Browser_Record;
             Tracing : Traced_Actions
          );

This procedure changes tracing status. The parameter Tracing defines which actions need to be traced.

function Get_Root_Directory (File : String) return String;

This procedure returns the full name of the root directory indicated by the widget.

2.9.3. Wildcard browsing widget

The package Gtk.Wildcard_Directory_Browser provides a specialized directory browsing widget with files list pane filtered using wildcard patterns.

type Gtk_Wildcard_Directory_Browser_Record is
   new Gtk_Directory_Browser_Record with private;
type Gtk_Wildcard_Directory_Browser is
   access all Gtk_Wildcard_Directory_Browser_Record'Class;

The following subprograms are defined on the widget:

procedure Finalize
          (  Widget : not null access Gtk_Wildcard_Directory_Browser_Record
          );

This procedure has to be called by the derived type when overridden upon its finalization.

function Get_Pattern
         (  Widget : not null access Gtk_Wildcard_Directory_Browser_Record
         )  return String_List.GList;

This function returns the currently used pattern. The result shall not be modified.

procedure Gtk_New
          (  Widget    : out Gtk_Wildcard_Directory_Browser;
             Pattern   : String_List.GList := Any;
             File      : UTF8_String := Current_Directory;
             Columns   : Positive    := 4;
             Vertical  : Boolean     := False;
             Tree_Size : Gtk_Requisition := (Width => 180, Height => 500);
             List_Size : Gtk_Requisition := (Width => 600, Height => 500);
             Store     : Gtk_Directory   := null;
             Tracing   : Traced_Actions  := Trace_Nothing
          );
procedure Gtk_New
          (  Widget    : out Gtk_Wildcard_Directory_Browser;
             Pattern   : Controlled_String_List;
             File      : UTF8_String := Current_Directory;
             Columns   : Positive    := 4;
             Vertical  : Boolean     := False;
             Tree_Size : Gtk_Requisition := (Width => 180, Height => 500);
             List_Size : Gtk_Requisition := (Width => 600, Height => 500);
             Store     : Gtk_Directory   := null;
             Tracing   : Traced_Actions  := Trace_Nothing
          );

These procedures create a new widget. The parameter Pattern is the files filter pattern. It can be specified either as a list or as a controlled wrapper around. When omitted the pattern is considered as matching anything. The parameter File is the full name of a file to browse. Its most nested existing parent is selected in the directory tree view. Correspondingly it is shown in the files view. The parameter Columns specifies the number columns in the files view. When the parameter Vertical is false the tree view is shown left of the files view. Otherwise it is shown above. The parameters Tree_Size and List_Size control size of the directory tree and files list panes. The widget will try to render them so that no scroll bars will appear. For this the panes will be expanded but not larger than the corresponding parameters specify. The parameter Store is the directory cache to use with the widget. When specified as null a new directory cache is created transparently. The parameter Tracing specifies the actions desired for tracing.

procedure Initialize
          (  Widget    : not null access Gtk_Wildcard_Directory_Browser_Record'Class;
             Pattern   : String_List.GList;
             File      : UTF8_String;
             Columns   : Positive;
             Vertical  : Boolean;
             Tree_Size : Gtk_Requisition;
             List_Size : Gtk_Requisition;
             Store     : Gtk_Directory;
             Tracing   : Traced_Actions
          );

This procedure has to be called from the Initialize of the derived type.

procedure Set_Pattern
          (  Widget  : not null access Gtk_Wildcard_Directory_Browser_Record;
             Pattern : String_List.GList := Any
          );
procedure Set_Pattern
          (  Widget  : not null access Gtk_Wildcard_Directory_Browser_Record;
             Pattern : UTF8_String
          );
procedure Set_Pattern
          (  Widget  : not null access Gtk_Wildcard_Directory_Browser_Record;
             Pattern : Controlled_String_List
          );

These procedures set new pattern. The pattern can be specified as a single alternative, as a list or as a controlled wrapper around.

2.10. Persistent storage browsing

The package Gtk.Persistent_Storage_Browser provides specialized cache and widgets for browsing persistent storages.

2.10.1. Paths, URI, Credentials

Paths. Persistent objects are identified by paths. Path have the type Item_Path. A path consists of UTF-8 encoded names separated by forward slashes (/). Slash and any other characters within a name can be escaped using backward slash (\). The first name of a path specified a persistent storage. The following operations are defined on paths:

function "&" (Path : Item_Path; Name : Item_Name) return Item_Path;

This function composes a path from a path to the directory and the item name within the directory. Name_Error is propagated when Name is empty.

function Get_Name (Path : Item_Path) return Item_Name;

This function returns the name part of Path. Name_Error is propagated when Path is illegal.

function Get_Directory (Path : Item_Path) return Item_Path;

This function returns the directory part of Path. Name_Error is propagated when Path is illegal or else there when there is no directory part.

function Is_Root (Path : Item_Path) return Boolean;

This function returns true if Path specifies a root-level item, i.e. a persistent storage.

URI. Uniform Resource Identifiers (URI) of persistent objects are used to identify them outside the application. An URI describes the persistent storage, user credentials used to access it and the path within the storage. URI syntax supports storing encrypted user credentials. The type:

type Scheme_Type is (DSN_Scheme, SQLite_Scheme);

defines URI schemes of the supported persistent storages:

• DSN_Scheme is the scheme for the ODBC data source;
• SQLite_Scheme is the scheme for the SQLite data base.

The following operations are defined for object's URI:

procedure Get_Credentials
          (  URI          : UTF8_String;
             User         : out Unbounded_String;
             Password     : out Unbounded_String;
             Has_Password : out Boolean
          );

This procedure takes user credentials from URI. The output parameters User and Password are set from the corresponding parts of URI. The parameter Has_Password is returned true, when URI contains password. Otherwise Password is returned empty. Two URI schemes are supported:

• DSN_Scheme describing an ODBC data source, User and Password are the credentials to access the data source. Has_Pasword indicates if the password was specified;
• SQLite_Scheme, User is the SQLite data base file name, Password is empty string. Has_Pasword is false.

function Get_DSN (URI : UTF8_String) return Item_Name;

This function returns the persistent storage name from URI. The result is an empty string when URI has syntax errors.

function Get_Path (URI : UTF8_String) return Item_Path;

This function returns the object path from URI. The result is an empty string when URI has syntax errors.

function Get_Scheme (URI : UTF8_String) return Scheme_Type;

This function returns the URI scheme. Constraint_Error is propagated when the scheme is unknown.

function To_DSN_URI
         (  DSN             : UTF8_String;
            User            : UTF8_String;
            Password        : UTF8_String := "";
            Stored_Password : Boolean     := False
         )  return UTF8_String;

This function composes a DSN URI from the data source name DSN and user credentials. When the parameter Stored_Password is true, the result will contain Password. For such URI the procedure Get_Credentials will return true in Has_Password.

function To_SQLite_URI
         (  DSN  : UTF8_String;
            File : UTF8_String;
         )  return UTF8_String;

This function composes a SQLite URI from the data source name DSN and the data base file name File.

Credentials. Accessing persistent storage may require querying user credentials. The package provides an abstract interface for.

type Abstract_Credentials_Query is abstract
   new Object.Entity with null record;
type Abstract_Credentials_Query_Ptr is
   access Abstract_Credentials_Query'Class;

The type Abstract_Credentials_Query is the abstract base type of credentials query. Usually it is implemented as a dialog. The following abstract operations have to be implemented:

procedure Create
          (  Query           : in out Abstract_Credentials_Query;
             Scheme          : out Scheme_Type;
             Name            : out Unbounded_String;
             User            : out Unbounded_String;
             Password        : out Unbounded_String;
             Stored_Password : out Boolean;
             Storage         : out Storage_Handle
          )  is abstract;

The function asks user to input the persistent storage type, name, user name and password. After successful completion the output parameters are set and the the parameter Storage is a valid handle to the persistent storage. When user cancels input Storage is invalid. An implementation may propagate Use_Error to indicate that the persistent storage should not be used, i.e. dropped. The output parameter Scheme indicates the type of the credentials, which then determines other output parameters:

• DSN_Scheme, Name is the persistent storage server name or else DSN name. User is the user name, Password is the password. Stored_Password is the pasword storing flag;
• SQLite_Scheme, Name is the persistent storage name. User contains the SQLite data base file name. Password is an empty string. Stored_Password is false.

procedure Get
          (  Query           : in out Abstract_Credentials_Query;
             Scheme          : Scheme_Type;
             Name            : UTF8_String;
             User            : in out Unbounded_String;
             Password        : in out Unbounded_String;
             Stored_Password : in out Boolean;
             Storage         : out Storage_Handle
          )  is abstract;

This procedure is like Create, but has initial values for Scheme, Name, User and Stored_Password. Further, Scheme and  Name cannot be changed.

package Query_Handles is
   new Object.Handle
       (  Abstract_Credentials_Query,
          Abstract_Credentials_Query_Ptr
       );
use Query_Handles;

This package provides handles to query objects.

2.10.2. Cache

The package Gtk.Persistent_Storage_Browser defines a specialized directory cache of persistent objects:

type Gtk_Persistent_Directory_Record is
   new Gtk_Abstract_Directory_Record with private;
type Gtk_Persistent_Directory is
   access all Gtk_Persistent_Directory_Record'Class;

The following additional operations are defined:

procedure Add_Storage
          (  Store   : access Gtk_Persistent_Directory_Record;
             Storage : out Storage_Handle
          );

This procedure can be called in order to query the user for a new persistent storage. for this it uses the credential dialog associated with the store. When the storage was successfully added a handle to it is returned. Otherwise it is set invalid. The storage is added at the root level. When the user chooses an already connected storage, its handle is returned.

procedure Browse
          (  Store   : access Gtk_Persistent_Directory_Record;
             Path    : Item_Path;
             Storage : out Storage_Handle;
             Object  : out Deposit_Handle;
             Partial : Boolean := False
          );

This procedure browses a path specified by the parameter Path. It returns a handle to the object indicated by the path (the parameter Object) and a handle to the persistent storage of (the parameter Storage). The persistent storage must be connected to be browsed. When the storage is not yet connected, or some items of the path do not exist End_Error is propagated. If the parameter Partial is true, then the path is browsed as far as possible and End_Error is not propagated. Use_Error is propagated when an object on the path cannot be restored from the persistent storage because its class is unknown.

procedure Delete
          (  Store : access Gtk_Persistent_Directory_Record;
             Path  : Item_Path
          );

The object specified by Path is unnamed and then the cache is synchronized as necessary. When Path specifies a persistent storage, then it is only disconnected and removed from the cache. Nothing happens when object does not exist.

function Get_Class
         (  Store : access Gtk_Persistent_Directory_Record;
            Path  : Item_Path
         )  return String;

This function is similar to Browse except that it returns the object's class rather than the object itself. Though it restores all objects along the path in order to get the class.

function Get_Creation_Time
         (  Store : access Gtk_Persistent_Directory_Record;
            Path  : Item_Path
         )  return Time;

This function is similar to Browse except that it returns the object's creation time. Though it restores all objects along the path in order to get the class.

function Get_DSN
         (  Store   : access Gtk_Persistent_Directory_Record;
            Storage : Storage_Handle
         )  return Item_Name;

The result is the DSN name of Storage as registered in Store. Constraint_Error is propagated when Storage is not cached in Store.

function Get_Manager
         (  Widget : access Gtk_Persistent_Directory_Record
         )  return Gtk_Recent_Manager;

This function returns the recent resource manager used by the store.

function Get_Path
         (  Store   : access Gtk_Persistent_Directory_Record;
            Storage : Storage_Handle;
            Object  : Deposit_Handle
         )  return Item_Path;

This function returns a path to Object in Storage. When Object is invalid the result is the root directory path, i.e. same as returned by Get_DSN, converted to Item_Path.

function Get_Query
         (  Store : access Gtk_Persistent_Directory_Record
         )  return Query_Handles.Handle;

This function returns a handle to the credential query dialog used with Store.

function Get_Storage
         (  Store : access Gtk_Persistent_Directory_Record;
            Path  : Item_Path
         )  return Storage_Handle;

This function returns a handle to the storage where the object specified by Path belongs. Root-level paths denote the storage itself. The result is an invalid handle if the storage is not yet connected.

procedure Gtk_New
          (  Store   : out Gtk_Persistent_Directory;
             Query   : Query_Handles.Handle;
             Manager : access Gtk_Recent_Manager_Record'Class :=
                              Get_Default;
             Tracing : Traced_Actions := Trace_Nothing
          );

This procedure creates a new cache. The parameter Manager is a recent resource manager to use. The manager keeps the configured persistent storage data sources as items. Each such item appears at the root level of the cache. When Query is an invalid handle no querying is used and so any root-level items attempted for browsing, which cannot be connected will be simply removed. The parameter Tracing specifies the actions desired for tracing.

procedure Initialize
          (  Store   : access Gtk_Persistent_Directory_Record'Class;
             Query   : Query_Handles.Handle;
             Manager : access Gtk_Recent_Manager_Record'Class;
             Tracing : Traced_Actions := Trace_Nothing
          );

This procedure has to be called upon initialization of a derived type object.

function Is_Directory
         (  Store : access Gtk_Persistent_Directory_Record;
            Name  : String;
            Class : String
         )  return Boolean;

This function is used to determine if a persistent object should be considered a directory. Only the objects for which this function returns true are scanned for having children. In fact any persistent object may serve as a directory. But usually there is some restriction put on. The default implementation returns true only for the objects that have class Directory.

procedure Set_Query
          (  Store : access Gtk_Persistent_Directory_Record;
             Query : Query_Handles.Handle
          );

This procedure changes the credential query dialog of Store to Query.

2.10.3. Persistent storage tree view

The package Gtk.Persistent_Storage_Browser provides a specialized tree view widget for persistent directories tree (see Gtk_Directory_Tree_View):

type Gtk_Persistent_Storage_Tree_View_Record is
   new Gtk_Directory_Tree_View_Record with private;
type Gtk_Persistent_Storage_Tree_View is
   access all Gtk_Persistent_Storage_Tree_View_Record'Class;

The following additional operations are provided:

function Get_Current_Object
         (  Widget : access Gtk_Persistent_Storage_Tree_View
         )  return Deposit_Handle;

This function returns a handle to the currently selected directory. The result is an invalid handle if no directory is selected. Data_Error is propagated on storage errors.

function Get_Current_Storage
         (  Widget : access Gtk_Persistent_Storage_Tree_View
         )  return Storage_Handle;

This function returns a handle to the storage where the currently selected directory resides. The result is an invalid handle if no directory is selected. Data_Error is propagated on storage errors.

function Get_Directory_Cache
         (  Widget : access Gtk_Persistent_Storage_Tree_View
         )  return Gtk_Persistent_Directory;

The function returns the directory cache associated with the widget.

procedure Gtk_New
          (  Widget   : out Gtk_Persistent_Storage_Tree_View;
             Store    : access Gtk_Persistent_Directory_Record'Class;
             Selected : Item_Path := ""
          );

This procedure creates a new widget. The parameter Selected is the path of an item to expand the directory tree to. When the item is a directory it is selected. Otherwise its parent is selected. When Selected is an empty string then nothing is done.

procedure Initialize
          (  Widget   : access Gtk_Persistent_Storage_Tree_View_Record'Class;
             Store    : access Gtk_Persistent_Directory_Record'Class;
             Selected : Item_Path
          );

This procedure has to be called upon initialization of a derived type object.

Persistent_Storage_Tree_View_Class_Name : constant String :=
   "GtkPersistentStorageTreeView";

This string constant contains the GTK+ class name of the widget. The widget has the following additional style properties:

2.10.4. Persistent storage objects view

The package Gtk.Persistent_Storage_Browser provides a specialized tree view widget for persistent object directories rendered as a columned list:

type Gtk_Persistent_Storage_Items_View_Record is
   new Gtk_Directory_Items_View_Record with private;
type Gtk_Persistent_Storage_Items_View is
   access all Gtk_Persistent_Storage_Items_View_Record'Class;

The following additional operations are provided:

function Get_Directory_Cache
         (  Widget : access Gtk_Persistent_Storage_Items_View
         )  return Gtk_Persistent_Directory;

The function returns the directory cache associated with the widget.

function Get_Directory_Object
         (  Widget : access Gtk_Persistent_Storage_Items_View
         )  return Deposit_Handle;

This function returns a handle to the current directory. The result is an invalid handle if no directory is selected. Data_Error is propagated on storage errors.

function Get_Storage
         (  Widget : access Gtk_Persistent_Storage_Items_View
         )  return Storage_Handle;

This function returns a handle to the storage where the currentl directory resides. The result is an invalid handle if no directory is selected. Data_Error is propagated on storage errors.

procedure Gtk_New
          (  Widget  : out Gtk_Persistent_Storage_Items_View;
             Store   : access Gtk_Persistent_Directory_Record'Class;
             Columns : Positive;
             Current : Item_Path := ""
          );

This procedure creates a new widget. The parameter Store is a cache object to use with. The parameter Columns is the number of columns. The parameter Current is the directory to render initially.

procedure Gtk_New
          (  Widget  : out Gtk_Persistent_Storage_Items_View;
             Tree    : access Gtk_Persistent_Storage_Tree_View_Record'Class;
             Columns : Positive;
          );

This variant of the procedure creates a new widget which works with a directory browsing widget specified by the parameter Tree.

procedure Initialize
          (  Widget  : access Gtk_Persistent_Storage_Items_View_Record'Class;
             Store   : access Gtk_Persistent_Directory_Record'Class;
             Columns : Positive;
             Current : Item_Path
          );
procedure Initialize
          (  Widget  : access Gtk_Persistent_Storage_Items_View_Record'Class;
             Tree    : access Gtk_Persistent_Storage_Tree_View_Record'Class;
             Columns : Positive
          );

One of these procedures have to be called upon initialization of a derived type object.

Persistent_Storage_Items_View_Class_Name : constant String :=
   "GtkPersistentStorageItemsView";

This string constant contains the GTK+ class name of the widget. The widget has the same additional style properties as Persistent_Storage_Tree_View_Class_Name.

2.10.5. Persistent storage browsing widget

The package Gtk.Persistent_Storage_Browser provides a composite widget for browsing persistent storage directories:

type Gtk_Persistent_Storage_Browser_Record is
   new Gtk_Paned_Record with private;
type Gtk_Persistent_Storage_Browser is
   access all Gtk_Persistent_Storage_Browser_Record'Class;

The widget is a descendant of paned. One of its children is a tree view of the persistent storage directory browsed another is a columned list of persistent objects in the currently viewed directory. The following operations are provided:

function Filter
         (  Widget    : access Gtk_Persistent_Storage_Browser_Record;
            Directory : Boolean;
            Name      : Item_Name;
            Kind      : Item_Type
         )  return Boolean;

This function can be overridden to prevent some objects from being shown in the directory items pane. The default implementation lets all items in.

function Get_Cache
         (  Widget : access Gtk_Persistent_Storage_Browser_Record
         )  return Gtk_Persistent_Directory;