-------------------- Desktop Handling -- -------------------- The MDI provides a way to save desktops, i.e the list of children currently open in the MDI and their location. It can then restore the desktop at some later point.
Desktops require support from the widgets that are put in the MDI. They need to register a function to save them and a function to recreate them. Using Ada streams for this didn't prove workable since some children might need extra parameters not available to them through streams. This is why the following subprograms are in a generic package, so that you can pass whatever parameter(s) is needed in your application.
Desktops are saved and restored in XML trees.
If you need your application to load a "default desktop" when the user hasn't defined one, it is recommended that you distribute an actual file containing this desktop. You could also create the XML tree in memory yourself, and thus hard-code the default desktop if need be.
procedure Change_Perspective
(Item : access Gtk.Widget.Gtk_Widget_Record'Class)
Internal, but needed so that we can have a 'Access on a callback
function Create_Menu
(MDI : access MDI_Window_Record'Class;
Accel_Path_Prefix : String := "<gtkada>";
User : User_Data;
Registration : Menu_Registration_Procedure := null)
return Gtk.Menu.Gtk_Menu
Create a dynamic menu that can then be inserted into a menu bar. This menu is dynamic, ie its content will changed based on the focus child. If this function is called several times, a new menu is created every time. Accel_Path_Prefix must be the same for every call. Accel_Path_Prefix is used so that the key shortcuts associated with these menu items can be changed dynamically by the user (see gtk-accel_map.ads). The prefix must start with "<" and end with ">". User is used for the callbacks on perspective changes, and passed to Load_Perspective With recent versions of gtk+, the use of Glib.Menu_Model.Gmenu_Model is encouraged, so you should use Set_Menu_Model above instead.
procedure Create_Perspective
(MDI : access MDI_Window_Record'Class;
Name : String;
User : User_Data)
Create a new perspective with the current desktop layout. If another perspective with the same name exists, it is replaced.
procedure Create_Perspective_CB
(Item : access Gtk.Widget.Gtk_Widget_Record'Class)
procedure Define_Perspective
(MDI : access MDI_Window_Record'Class;
XML : Glib.Xml_Int.Node_Ptr;
User : User_Data)
Define a new perspective (in the same format as returned by Save_Desktop, the central area is under control of the user so you cannot change it). If such a perspective already exists, nothing is done (since the user might have modified it already). XML's root node is the <perspective> node, including its "name" attribute. XML must be freed by the caller.
procedure Free_Registered_Desktop_Functions
Free the memory allocated for the registered functions.
function Get_XML_Content
(MDI : access MDI_Window_Record'Class;
Tag : String) return Glib.Xml_Int.Node_Ptr
Return the first XML subtree starting with 'Tag'. This allows a module to retrieve its content after the 'Load_Desktop' call.
type Load_Desktop_Function is access function
(MDI : MDI_Window; Node : Glib.Xml_Int.Node_Ptr; User : User_Data)
return MDI_Child;
A general function that loads a widget from an XML tree.
As for Save_Desktop_Function, this function should return null if it doesn't know how to handle Node or if Node doesn't describe a widget type that it can handle.
This function returns an MDI_Widget that has been put in the MDI.
procedure Load_Perspective
(MDI : access MDI_Window_Record'Class;
Name : String;
User : User_Data)
Replace the current perspective by another one. This preserves the editor area. If the perspective does not exist, nothing is done, unless no perspective is currently loaded (in which case we load the first on in the list).
type Menu_Registration_Procedure is access procedure
(User : User_Data;
Item_Name : String;
Accel_Path : String);
Function used to register in the application a static menu created by the MDI.
procedure On_Action_Create_Perspective
(MDI : access MDI_Window_Record'Class;
Params : Glib.Values.GValues;
User : User_Data)
procedure On_Action_Select_Perspective
(MDI : access MDI_Window_Record'Class;
Params : Glib.Values.GValues;
User : User_Data)
procedure On_Perspective_Changed_Update_Menu
(Menu : access Gtk.Widget.Gtk_Widget_Record'Class)
procedure Register_Desktop_Functions
(Save : Save_Desktop_Function;
Load : Load_Desktop_Function)
Register a set of functions to save and load desktops for some specific widget types. This can be called multiple times. Save might be null.
function Restore_Desktop
(MDI : access MDI_Window_Record'Class;
Perspectives : Glib.Xml_Int.Node_Ptr;
From_Tree : Glib.Xml_Int.Node_Ptr;
User : User_Data) return Boolean
Restore the contents of the MDI from its saved XML tree. Perspectives is the list of perspectives. It is cloned as needed, so the caller is still responsible for freeing it. The first perspective is loaded. From_Tree is the part of the desktop that describes the editor area. User is passed as a parameter to all of the Load_Desktop_Function registered by the widgets. Return False if the desktop couldn't be loaded It also restores the size and position of the toplevel window that contains the MDI
procedure Save_Desktop
(MDI : access MDI_Window_Record'Class;
User : User_Data;
Perspectives : out Glib.Xml_Int.Node_Ptr;
Central : out Glib.Xml_Int.Node_Ptr)
Return XML representations of the perspectives and central area. Both nodes need to be freed by the caller, and can be saved in a file (to be passed to Restore_Desktop later on). This function calls each of the registered function for the children of the MDI. It also saves the size and position of the toplevel window that contains the MDI
type Save_Desktop_Function is access function
(Widget : access Gtk.Widget.Gtk_Widget_Record'Class;
User : User_Data) return Glib.Xml_Int.Node_Ptr;
A general function that dumps the parameters of a widget into an XML tree.
Note: you should register one such function for all the widget types you will put in the MDI and that need to be saved when a desktop is saved. The MDI will call all the registered functions one after the other. Therefore, your function should return null if Widget is not of a type that is it can handle.
Before calling the registered save_desktop_function, the MDI will first use the child's Save_Desktop primitive function.
procedure Set_Menu_Model
(MDI : not null access MDI_Window_Record'Class;
App : not null access Gtk.Application.Gtk_Application_Record'Class;
Model : access Glib.Menu.Gmenu_Record'Class;
User : User_Data)
Associates a menu model with the MDI. This model will be filled and maintained by the MDI, to provide useful actions like floating/docking items, selecting items,...
type User_Data is private;
Generic type of parameter that is passed to all the children's save and restore functions.