[Contents] [Back] [Prev] [Up] [Next] [Forward]

# Package Glib.Object

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

- Glib.Object Signals
- Glib.Object Types
- Glib.Object Subprograms

## Signals

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

## Types

    type GObject_Class is private;

    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

## 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 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.

### 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.

    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

    function Class_From_Type
      (Typ                :        GType)
       return GObject_Class;

| Return the class record for a specific type

### Signals

??? 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 C_Signal_Query_Size   return Natural;

[Contents] [Back] [Prev] [Up] [Next] [Forward]