Toc Gallery Index Tree Glib.Object

Hierarchy

Description

This package provides a minimal binding to the GObject type in Glib. See Glib.Properties for information on how to manipulate properties

Types

  • type GObject is access all GObject_Record'Class;
    The base type for Glib/Gdk/Gtk objects. It basically gives access to an underlying C object. This is not a controlled type for efficiency reasons and because glib takes care of the memory management on its own.
  • type GObject_Class is new GType_Class;
  • type GObject_Record is tagged private;
  • type Interface_Vtable is private;
    The virtual table of an interface (see Glib.Types). This is only useful when doing introspection.
  • type Signal_Id_Array is array (Guint range <>) of Glib.Signal_Id;
  • type Signal_Parameter_Types is array (Natural range <>, Natural range <>) of GType;
    The description of the parameters for each event. These are the parameters that the application must provide when emitting the signal. The user can of course add his own parameters when connecting the signal in his application, through the use of Gtk.Handlers.User_Callback.

    Each event defined with Initialize_Class_Record below should have an entry in this table. If Gtk_Type_None is found in the table, it is ignored. For instance, a Signal_Parameter_Type like: (1 => (1 => Gdk_Type_Gdk_Event, 2 => GType_None), 2 => (1 => GType_Int, 2 => GType_Int)); defines two signals, the first with a single Gdk_Event parameter, the second with two ints parameters.

  • type Signal_Query is private;
  • type Weak_Notify is access procedure (Data : System.Address; Where_The_Object_Was : System.Address);
  • type verification is made to check if you are using the correct -- matching Get function. This is your own responsability. -- -- We recommend using this package only if you want your data to be -- available from your own C code. If you just want to access it from Ada, -- you should consider creating a new tagged type instead, that extends -- either GObject_Record or the specific widget type you need. -- end User_Data;

Subprograms

  • function Is_Created (Object : in GObject_Record'Class) return Boolean;
    Return True if the associated C object has been created, False if no C object is associated with Object. This is not the same as testing whether an access type (for instance any of the widgets) is "null", since this relates to the underlying C object.
  • function Get_Type (Object : access GObject_Record) return GType;
    Return the type of Object. This function is mostly used internally, since in Ada you can simply test whether an object belong to a class with a statement like:

    if Object in Gtk_Button_Record'Class then ...

    which is easier.

  • Life cycle

  • procedure G_New (Object : out GObject);
    Create a new GObject. This is only required when you want to create an Ada tagged type to which you can attach new signals. Most of the time, you only need to directly create the appropriate Gtk Widget by calling the correct Gtk_New procedure.
  • procedure Initialize (Object : access GObject_Record'Class);
    Internal initialization function. See the section "Creating your own widgets" in the documentation.
  • procedure Ref (Object : access GObject_Record);
    Increment the reference counter for Object. See Unref below. Since an object is not deleted while its reference count is not null, this is a way to keep an object in memory, in particular when you want to temporarily remove a widget from its parent.
  • procedure Unref (Object : access GObject_Record);
    Decrement the reference counter for Object. When this reaches 0, the object is effectively destroy, all the callbacks associated with it are disconnected.
  • procedure Weak_Ref (Object : access GObject_Record'Class; Notify : Weak_Notify; Data : System.Address := System.Null_Address);
    This kind of reference doesn't increment the object's reference counting. However, it can and should be used to monitor the object's life cycle, in particular to detect is destruction. When Object is destroyed, calls Notify
  • procedure Weak_Unref (Object : access GObject_Record'Class; Notify : Weak_Notify; Data : System.Address := System.Null_Address);
    Cancels the settings of Weak_Ref.
  • procedure Deallocate (Object : access GObject_Record);
    This operation is used to deallocate Object. The default implementation assumes that the value passed in is an access value created by an allocator of the default pool, i.e. it will assume that an instance of Unchecked_Deallocation (GObject_Record'Class, GObject) can be used to deallocate the designated object. Types derived of GObject_Record can override this operation in order to cope with objects allocated on other pools or even objects allocated on the stack. This design is limited to support only one allocation strategy for each class, as the class tag is used to identify the applicable strategy.
  • Interfacing with C

    The following functions are made public so that one can easily create new objects outside the Glib or Gtk package hierarchy. Only experienced users should make use of these functions.
  • function Get_Object (Object : access GObject_Record'Class) return System.Address;
    Access the underlying C pointer.
  • procedure Set_Object (Object : access GObject_Record'Class; Value : System.Address);
    Modify the underlying C pointer.
  • function Get_User_Data (Obj : System.Address; Stub : GObject_Record'Class) return GObject;
    Return the Ada object matching the C object Obj. If Obj was created explicitely from GtkAda, this will be the exact same widget. If Obj was created implicitely by gtk+ (buttons in complex windows,...), a new Ada object of type Stub will be created.
  • function Get_User_Data_Fast (Obj : System.Address; Stub : GObject_Record'Class) return GObject;
    Same as Get_User_Data, but does not try to guess the type of Obj, always default to Stub if Obj is unknown to GtkAda.
  • function Unchecked_Cast (Obj : access GObject_Record'Class; Stub : GObject_Record'Class) return GObject;
    Cast Obj in an object of tag Stub'Class. Return the resulting object and free the memory pointed by Obj.
  • Signals

    Any child of GObject can be associated with any number of signals. The mechanism for signals is fully generic, and any number of arguments can be associated with signals. See the function Initialize_Class_Record for more information on how to create new signals for your own new widgets. The subprograms below are provided for introspection: they make it possible to query the list of signals defined for a specific widget, as well as their parameters and return types.
    ??? This section is incomplete.
  • function Lookup (Object : Glib.GType; Signal : String) return Glib.Signal_Id;
    Returns the signal Id associated with a specific Object/Signal pair. Null_Signal_Id is returned if no such signal exists for Object. You can then use the Query procedure to get more information on the signal.
  • function List_Ids (Typ : Glib.GType) return Signal_Id_Array;
    Return the list of signals defined for Typ. You can get more information on each of this signals by using the Query function below. See also the function Get_Type above to convert from an object instance to its type. Using a GType as the parameter makes it easier to find the signals for a widget and its ancestors (using Glib.Parent).
  • procedure Query (Id : Glib.Signal_Id; Result : out Signal_Query);
    Return the description associated with the signal Id. You can get the various fields from Query with one of the functions below. Result is undefined if Id is Invalid_Signal_Id or Null_Signal_Id
  • function Id (Q : Signal_Query) return Glib.Signal_Id;
    Return the signal Id. Each Id is specific to a widget/signal name pair. These Ids can then be used to temporarily block a signal for instance, through the subprograms in Gtk.Handlers.
  • function Signal_Name (Q : Signal_Query) return String;
    Return the name of the signal, as should be used in a call to Connect.
  • function Return_Type (Q : Signal_Query) return Glib.GType;
    Return the type of object returned by the handlers for this signal.
  • function Params (Q : Signal_Query) return GType_Array;
    Return the list of parameters for the handlers for this signal
  • Creating new widgets

    These types and functions are used only when creating new widget types directly in Ada. These functions initialize the classes so that they are correctly recognized by gtk+ itself See the GtkAda user's guide for more information on how to create your own widget types in Ada.
  • procedure Initialize_Class_Record (Object : access GObject_Record'Class; Signals : Gtkada.Types.Chars_Ptr_Array; Class_Record : in out GObject_Class; Type_Name : String; Parameters : Signal_Parameter_Types := Null_Parameter_Types);
    Create the class record for a new object type. It is associated with Signals'Length new signals. A pointer to the newly created structure is also returned in Class_Record. If Class_Record /= System.Null_Address, no memory allocation is performed, we just reuse it. As a result, each instantiation of an object will share the same GObject_Class, exactly as is done for gtk+.

    Note: The underlying C object must already have been initialized by a call to its parent's Initialize function. Parameters'Length should be the same as Signals'Length, or the result is undefined. As a special case, if Parameters has its default value, all signals are created with no argument. This is done for backward compatibility mainly, and you should instead give it an explicit value. Type_Name should be a unique name identifying the name of the new type.

    Only the signals with no parameter can be connected from C code. However, any signal can be connected from Ada. This is due to the way we define default marshallers for the signals.

  • function Type_From_Class (Class_Record : GObject_Class) return GType;
    Return the internal gtk+ type that describes the newly created Class_Record. See the function Glib.Types.Class_Peek for the opposite function converting from a GType to a GObject_Class.
  • Properties introspection

    See glib.ads for more information on properties
  • function Interface_List_Properties (Vtable : Interface_Vtable) return Glib.Param_Spec_Array;
    Return the list of properties of an interface (see also Glib.Properties) from a Vtable from Default_Interface_Peek). See also Class_List_Properties for a similar function for objects.
  • function Class_List_Properties (Class : GObject_Class) return Glib.Param_Spec_Array;
    Return the list of all properties of the class.
  • Signals

    Any child of GObject can be associated with any number of signals. The mechanism for signals is fully generic, and any number of arguments can be associated with signals. See the function Initialize_Class_Record for more information on how to create new signals for your own new widgets. The subprograms below are provided for introspection: they make it possible to query the list of signals defined for a specific widget, as well as their parameters and return types.
    ??? This section is incomplete.
  • procedure Notify (Object : access GObject_Record; Property_Name : String);
    Emits the "notify" signal, to signal every listener that the property has been changed.
  • Lists

  • function Convert (W : GObject) return System.Address;
    function Convert (W : System.Address) return GObject;

Signals

  • notify
    procedure Handler (Object : access GObject_Record'Class; Name : String);
    Emitted when the property Name has been modified

Alphabetical Index