PageRenderTime 19ms CodeModel.GetById 8ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 0ms

/src/wrappers/gobject/library/g_param_spec.e

http://github.com/tybor/Liberty
Specman e | 1053 lines | 284 code | 243 blank | 526 comment | 3 complexity | a444c2faa81aa46c0405dce333ba11be MD5 | raw file
   1indexing
   2	description: "GParamSpec, Metadata for parameter specifications"
   3	copyright: "[
   4					Copyright (C) 2006 eiffel-libraries team, GTK+ team
   5					Copyright (C) 2008 Raphael Mack
   6					
   7					This library is free software; you can redistribute it and/or
   8					modify it under the terms of the GNU Lesser General Public License
   9					as published by the Free Software Foundation; either version 2.1 of
  10					the License, or (at your option) any later version.
  11					
  12					This library is distributed in the hope that it will be useful, but
  13					WITHOUT ANY WARRANTY; without even the implied warranty of
  14					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15					Lesser General Public License for more details.
  16
  17					You should have received a copy of the GNU Lesser General Public
  18					License along with this library; if not, write to the Free Software
  19					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20					02110-1301 USA
  21				]"
  22				
  23class G_PARAM_SPEC
  24	-- GParamSpec is an object structure that encapsulates the metadata
  25	-- required to specify parameters, such as e.g. GObject properties.
  26	
  27	-- Parameter names need to start with a letter (a-z or
  28	-- A-Z). Subsequent characters can be letters, numbers or a
  29	-- '-'. All other characters are replaced by a '-' during
  30	-- construction.
  31
  32	-- Note: this class in an Eiffel-only design would have been deferred. 
  33	-- It is used as a quicker way to handle parameter specification 
  34	-- of unknown type without having to write a big inspect clause.
  35
  36	-- When the parameter specification type is known it is better to 
  37	-- use the correct heir; i.e. G_PARAM_SPEC_BOOLEAN.
  38	
  39inherit
  40	C_STRUCT
  41		redefine 
  42			from_external_pointer
  43		end
  44	MIXED_MEMORY_HANDLING 
  45	-- TODO: check it C_OWNED is actually better.	
  46	--	undefine from_external_pointer end
  47insert
  48	G_PARAM_SPEC_EXTERNALS
  49	G_TYPE_EXTERNALS
  50
  51creation from_external_pointer
  52	
  53feature -- Creation
  54	from_external_pointer (a_ptr: POINTER) is
  55			-- TODO: G_PARAM_SPEC should be deferred and its place should be taken by specialized heirs such as G_PARAM_SPEC_BOOLEAN
  56		do
  57			Precursor {C_STRUCT} (a_ptr)
  58			owner_class := g_type_class_peek (get_owner_type (a_ptr))
  59			param_id := get_param_id (a_ptr)
  60		end
  61
  62feature -- Flags
  63
  64	flags: INTEGER is
  65		do
  66			Result := get_flags (handle)
  67		ensure are_valid_param_flags (Result)
  68		end
  69
  70	is_readable: BOOLEAN is
  71			-- Is Current parameter readable?
  72		do
  73			Result:= (flags & g_param_readable).to_boolean
  74		end
  75
  76	is_writable: BOOLEAN is
  77			-- Is Current parameter writable?
  78		do
  79			Result:= (flags & g_param_writable).to_boolean
  80		end
  81
  82	is_set_at_construction: BOOLEAN is
  83			-- Will the parameter be set upon object construction?
  84		do
  85			Result:= (flags & g_param_construct).to_boolean
  86		end
  87	
  88	is_set_only_at_construction: BOOLEAN is
  89			-- Will the parameter only be set upon object construction?
  90		do
  91			Result:= (flags & g_param_construct_only).to_boolean
  92		end
  93
  94	-- TODO: find a better, not-clashing name for is_readable: BOOLEAN
  95	-- is -- Is strict validation not required upon parameter
  96	-- conversion?  (see `convert') do Result:=
  97	-- flags.bit_test(g_param_lax_validation_bit) end
  98	
  99
 100-- Doesn't work in GTK 2.6
 101--	is_static_name: BOOLEAN is
 102			-- Is the string used as name when constructing the parameter
 103			-- guaranteed to remain valid and unmodified for the lifetime
 104			-- of the parameter?
 105--		do
 106--			Result:= (flags & g_param_static_name).to_boolean
 107--		end
 108
 109-- Doesn't work in GTK 2.6
 110--	is_static_blurb: BOOLEAN is
 111			-- Is the string used as blurb when constructing the parameter
 112			-- guaranteed to remain valid and unmodified for the lifetime
 113			-- of the parameter?
 114--		do
 115--			Result:= (flags & g_param_static_blurb).to_boolean
 116--		end
 117
 118	is_readwrite: BOOLEAN is
 119			-- Is parameter read/write?
 120		do
 121			Result := (flags & g_param_readwrite).to_boolean
 122		ensure definition: Result implies (is_readable and is_writable)
 123		end
 124
 125feature
 126	set_default (a_value: G_VALUE) is
 127			-- Sets `a_value' to its default value as specified in Current.
 128		require valid_value: a_value /= Void
 129			-- TODO a GValue of correct type for current
 130		do
 131			g_param_value_set_default (handle, a_value.handle)
 132		end
 133
 134	is_default_value (a_value: G_VALUE): BOOLEAN is
 135			-- Does `a_value' contains the default value specified in
 136			-- Current?
 137		require
 138			value_not_void: a_value /= Void
 139			correct_value_type: a_value.type = value_gtype
 140		do
 141			Result:=(g_param_value_defaults(handle,a_value.handle)).to_boolean
 142		end
 143
 144	validate (a_value: G_VALUE): BOOLEAN is
 145			-- Has `a_value' to be changed to comply with the
 146			-- specifications set out by Current? For example, a
 147			-- G_PARAM_SPEC_INT might require that integers stored in
 148			-- value may not be smaller than -42 and not be greater than
 149			-- +42. If value contains an integer outside of this range,
 150			-- it is modified accordingly, so the resulting value will
 151			-- fit into the range -42 .. +42.
 152		require valid_value: a_value /= Void
 153			-- TODO a GValue of correct type for current
 154		do
 155			Result:=(g_param_value_validate(handle,a_value.handle)).to_boolean
 156		end
 157
 158	convert (a_source, a_destination: G_VALUE; strict_validation: BOOLEAN): BOOLEAN is
 159			-- Transforms `a_source' into `a_destination' if possible,
 160			-- and then validates `a_destination', in order for it to
 161			-- conform to Current. If `strict_validation' is True this
 162			-- function will only succeed if the transformed
 163			-- `a_destination' complied to Current without
 164			-- modifications. True if transformation and validation were
 165			-- successful, False otherwise and dest_value is left
 166			-- untouched.
 167		require -- TODO valid destination of corret type for Current
 168		do
 169			Result:=(g_param_value_convert(handle,
 170													 a_source.handle, a_destination.handle,
 171													 strict_validation.to_integer)).to_boolean
 172		end
 173
 174	compare (value1,value2: G_VALUE): INTEGER is
 175			-- Compares value1 with value2 according to Current, and
 176			-- return -1, 0 or +1, if value1 is found to be less than,
 177			-- equal to or greater than value2, respectively.
 178		require -- TODO value1 and 2: a GValue of correct type for pspec
 179		do
 180			Result := (g_param_values_cmp (handle,value1.handle,value2.handle))
 181		end
 182	
 183
 184feature -- queries
 185	name: STRING is
 186			-- the name of a G_PARAM_SPEC
 187		do
 188			--create 
 189			--Result.from_external_copy(g_param_spec_get_name(handle))
 190			create {CONST_STRING} Result.from_external(g_param_spec_get_name(handle))
 191		end
 192
 193	nick: STRING is
 194			-- the nick of a G_PARAM_SPEC
 195		do
 196			--create 
 197			--Result.from_external_copy(g_param_spec_get_nick(handle))
 198			create {CONST_STRING} Result.from_external(g_param_spec_get_nick(handle))
 199		end
 200	
 201	blurb: STRING is
 202			-- the blurb of a G_PARAM_SPEC
 203		do
 204			-- create Result.from_external_copy(g_param_spec_get_blurb(handle))
 205			create {CONST_STRING} Result.from_external(g_param_spec_get_blurb(handle))
 206		end
 207
 208feature 
 209	is_initialized: BOOLEAN is
 210			-- Is hidden implementation data correctly initialized?
 211		do
 212			Result := (owner_class.is_not_null and (param_id /= 0))
 213		end
 214
 215feature {WRAPPER} -- Implementation 
 216	owner_class: POINTER
 217			-- The GObjectClass the created and installed the corresponding property
 218	param_id: INTEGER 
 219			-- The parameter id to be passed to the property
 220			-- setter/getter function
 221feature -- name validity
 222	is_a_valid_name (a_string: STRING): BOOLEAN is
 223			-- Does `a_string' comply with the rules for G_PARAM_SPEC names?
 224		do
 225			-- When creating and looking up a GParamSpec, either separator can be used, but they cannot be mixed. Using '-' is considerably more efficient and in fact required when using property names as detail strings for signals.
 226			not_yet_implemented
 227		end
 228
 229	type_name: STRING is
 230			-- the GType name of this parameter spec.
 231		do
 232			create Result.from_external_copy (g_param_spec_type(handle))
 233		ensure result_not_void: Result /= Void
 234		end
 235
 236	value_gtype: INTEGER is
 237			-- the GType to initialize a GValue for this parameter.
 238		do
 239			Result:= g_param_spec_value_type (handle)
 240			ensure 
 241				is_valid_gtype: -- TODO: since this require a somehow
 242				-- complete G_TYPES class
 243		end
 244
 245feature {} -- Creation
 246
 247	make_integer (a_name,a_nick,a_blurb: STRING;
 248				  a_min,a_max,a_default: INTEGER; some_flags: INTEGER) is
 249			-- Creates a parameter specification for an integer setting.
 250			-- `a_name' is the canonical name of the property specified,
 251			-- `a_nick' is the nick name for the property specified,
 252			-- `a_blurb' is a description of the property specified.
 253			--`a_default' is the default value for the property
 254			--`some_flags' are flags for the property specified
 255		require
 256			max_greater_than_min: a_min < a_max
 257				default_in_range: a_default.in_range (a_min, a_max)
 258		do
 259			handle := g_param_spec_int (a_name.to_external, a_nick.to_external, a_blurb.to_external,
 260										 a_min, a_max, a_default,
 261										 some_flags)
 262			-- Note: where Gobject type system took this?
 263			owner_class := g_type_class_peek(get_owner_type(handle))
 264			param_id := get_param_id (handle)
 265		ensure is_integer: is_integer
 266		end
 267
 268feature -- Boolean parameter
 269	is_boolean: BOOLEAN is
 270			-- Is this a boolean parameter?
 271		do
 272			Result := g_is_param_spec_boolean (handle).to_boolean
 273		end
 274
 275	default_boolean: BOOLEAN is
 276			-- default boolean value
 277		do
 278			Result := default_gboolean(handle).to_boolean
 279		end
 280
 281feature -- Integer parameter
 282	is_integer: BOOLEAN is
 283			-- Is this an integer parameter?
 284		do
 285			Result := g_is_param_spec_int (handle).to_boolean
 286		end
 287
 288	default_integer: INTEGER is
 289			-- The default integer value
 290		require is_integer: is_integer
 291		do
 292			Result := get_default_int (handle)
 293		end
 294
 295	minimum_integer: INTEGER is
 296			-- The minimum integer value
 297		require is_integer: is_integer
 298		do
 299			Result := get_min_int (handle)
 300		end
 301
 302	maximum_integer: INTEGER is
 303			-- The maximum integer value
 304		require is_integer: is_integer
 305		do
 306			Result := get_max_int (handle)
 307		end
 308
 309feature {} -- Natural parameter
 310	is_natural: BOOLEAN is
 311			-- Is this a natural parameter?
 312		do
 313			Result := (g_is_param_spec_uint (handle).to_boolean)
 314		end
 315
 316	default_natural: INTEGER is
 317			-- The default natural value
 318		require is_natural: is_natural
 319		do
 320			Result := get_default_uint (handle)
 321		end
 322
 323	minimum_natural: INTEGER is
 324			-- The minimum natural value
 325		require is_natural: is_natural
 326		do
 327			Result := get_min_uint (handle)
 328		end
 329
 330	maximum_natural: INTEGER is
 331			-- The maximum natural value
 332		require is_natural: is_natural
 333		do
 334			Result := get_max_uint (handle)
 335		end
 336
 337feature -- TODO: INTEGER_64 (int64) parameter
 338
 339feature -- TODO: long parameter. Note: could it be the same of INTEGER_64?
 340
 341feature -- TODO: unsigned long parameter. Note: could it be the same of an eventual NATURAL_64?
 342feature -- TODO: NATURAL_64 (uint64) parameter
 343
 344feature -- TODO: REAL_32 (float) parameter
 345	is_real_32: BOOLEAN is
 346			-- Is this an integer parameter?
 347		do
 348			Result := g_is_param_spec_float (handle).to_boolean
 349		end
 350
 351	default_real_32: REAL_32 is
 352			-- The default integer value
 353		require is_real_32: is_real_32
 354		do
 355			Result := get_default_float (handle)
 356		end
 357
 358	minimum_real_32: REAL_32 is
 359			-- The minimum real_32 value
 360		require is_real_32: is_real_32
 361		do
 362			Result := get_min_float (handle)
 363		end
 364
 365	maximum_real_32: REAL_32 is
 366			-- The maximum real_32 value
 367		require is_real_32: is_real_32
 368		do
 369			Result := get_max_float (handle)
 370		end
 371
 372feature -- TODO: REAL_64 (double) parameter
 373	is_real_64: BOOLEAN is
 374			-- Is this an real_64 parameter?
 375		do
 376			Result := g_is_param_spec_double (handle).to_boolean
 377		end
 378
 379	default_real_64: REAL_64 is
 380			-- The default integer value
 381		require is_real_64: is_real_64
 382		do
 383			Result := get_default_double (handle)
 384		end
 385
 386	minimum_real_64: REAL_64 is
 387			-- The minimum real_64 value
 388		require is_real_64: is_real_64
 389		do
 390			Result := get_min_double (handle)
 391		end
 392
 393	maximum_real_64: REAL_64 is
 394			-- The maximum real_64 value
 395		require is_real_64: is_real_64
 396		do
 397			Result := get_max_double (handle)
 398		end
 399
 400feature -- TODO: enum parameter. Note: this need a wrapper for G_ENUM
 401	is_enum: BOOLEAN is
 402			-- Is this an enumeration (Enum in C) parameter?
 403		do
 404			Result := (g_is_param_spec_enum (handle).to_boolean)
 405		end
 406
 407
 408feature -- TODO: flags parameter. Note: this could need a wrapper for G_FLAG_CLASS and G_FLAG_VALUE
 409
 410feature -- TODO: STRING parameter
 411	is_string: BOOLEAN is
 412			-- Is this a string parameter?
 413		do
 414			Result := (g_is_param_spec_string (handle).to_boolean)
 415		end
 416
 417
 418feature -- TODO: G_PARAM_SPEC parameter 
 419	-- Note: call me dumb but it seems a little too recursive IMHO. Paolo 2006-06-28
 420feature -- TODO: G_BOXED parameter. Note: this require a wrapper for G_BOXED
 421feature -- TODO: POINTER parameter. Note: is this really needed? Paolo 2006-06-28
 422feature -- TODO: G_OBJECT parameter
 423
 424feature -- TODO: UNICODE CHARACTER parameter
 425	
 426feature -- CHARACTER parameter
 427	is_character: BOOLEAN is
 428			-- Is this a character parameter?
 429		do
 430			Result := g_is_param_spec_char (handle).to_boolean
 431		end
 432
 433	default_character: CHARACTER is
 434			-- The default character value
 435		require is_character: is_character
 436		do
 437			Result := def_char (handle).to_character
 438		end
 439
 440	minimum_character: CHARACTER is
 441			-- The minimum character value
 442		require is_character: is_character
 443		do
 444			Result := min_char (handle).to_character
 445		end
 446
 447	maximum_character: CHARACTER is
 448			-- The maximum character value
 449		require is_character: is_character
 450		do
 451			Result := max_char (handle).to_character
 452		end
 453	
 454feature -- TODO: (if meaningful) unsigned char parameter
 455feature -- TODO: G_VALUE_ARRAY parameter
 456feature -- TODO: override parameter
 457feature -- TODO: (if meaningful) G_TYPE parameter
 458
 459
 460feature {} -- Unwrapped API
 461	
 462--   GParamSpec
 463
 464--  typedef struct {
 465--    GTypeInstance  g_type_instance;
 466
 467--    gchar         *name;
 468--    GParamFlags    flags;
 469--    GType          value_type;
 470--    GType          owner_type;    /* class or interface using this property */
 471--  } GParamSpec;
 472
 473--    All fields of the GParamSpec struct are private and should not be used
 474--    directly, except for the following:
 475
 476--    GTypeInstance g_type_instance; private GTypeInstance portion
 477--    gchar *name;                   name of this parameter
 478--    GParamFlags flags;             GParamFlags flags for this parameter
 479--    GType value_type;              the GValue type for this parameter
 480--    GType owner_type;              GType type that uses (introduces) this
 481--                                   paremeter
 482
 483--    -----------------------------------------------------------------------
 484
 485--   GParamSpecClass
 486
 487--  typedef struct {
 488--    GTypeClass      g_type_class;
 489
 490--    GType           value_type;
 491
 492--    void          (*finalize)             (GParamSpec   *pspec);
 493
 494--    /* GParam methods */
 495--    void          (*value_set_default)    (GParamSpec   *pspec,
 496--                                           GValue       *value);
 497--    gboolean      (*value_validate)       (GParamSpec   *pspec,
 498--                                           GValue       *value);
 499--    gint          (*values_cmp)           (GParamSpec   *pspec,
 500--                                           const GValue *value1,
 501--                                           const GValue *value2);
 502--  } GParamSpecClass;
 503
 504--    The class structure for the GParamSpec type. Normally, GParamSpec
 505--    classes are filled by g_param_type_register_static().
 506
 507--    GTypeClass g_type_class; the parent class
 508--    GType value_type;        the GValue type for this parameter
 509--    finalize ()              The instance finalization function (optional),
 510--                             should chain up to the finalize method of the
 511--                             parent class.
 512--    value_set_default ()     Resets a value to the default value for this
 513--                             type (recommended, the default is
 514--                             g_value_reset()), see
 515--                             g_param_value_set_default().
 516--    value_validate ()        Ensures that the contents of value comply with
 517--                             the specifications set out by this type
 518--                             (optional), see g_param_value_set_validate().
 519--    values_cmp ()            Compares value1 with value2 according to this
 520--                             type (recommended, the default is memcmp()),
 521--                             see g_param_values_cmp().
 522
 523--    -----------------------------------------------------------------------
 524
 525--   enum GParamFlags
 526
 527--  typedef enum
 528--  {
 529--    G_PARAM_READABLE            = 1 < < 0,
 530--    G_PARAM_WRITABLE            = 1 < < 1,
 531--    G_PARAM_CONSTRUCT           = 1 < < 2,
 532--    G_PARAM_CONSTRUCT_ONLY      = 1 < < 3,
 533--    G_PARAM_LAX_VALIDATION      = 1 < < 4,
 534--    G_PARAM_STATIC_NAME         = 1 < < 5,
 535--  #ifndef G_DISABLE_DEPRECATED
 536--    G_PARAM_PRIVATE             = G_PARAM_STATIC_NAME,
 537--  #endif
 538--    G_PARAM_STATIC_NICK         = 1 < < 6,
 539--    G_PARAM_STATIC_BLURB        = 1 < < 7
 540--  } GParamFlags;
 541
 542--    Through the GParamFlags flag values, certain aspects of parameters can
 543--    be configured.
 544
 545--    G_PARAM_READABLE       the parameter is readable
 546--    G_PARAM_WRITABLE       the parameter is writable
 547--    G_PARAM_CONSTRUCT      the parameter will be set upon object
 548--                           construction
 549--    G_PARAM_CONSTRUCT_ONLY the parameter will only be set upon object
 550--                           construction
 551--    G_PARAM_LAX_VALIDATION upon parameter conversion (see
 552--                           g_param_value_convert()) strict validation is
 553--                           not required
 554--    G_PARAM_STATIC_NAME    the string used as name when constructing the
 555--                           parameter is guaranteed to remain valid and
 556--                           unmodified for the lifetime of the parameter.
 557--                           Since 2.8
 558--    G_PARAM_STATIC_BLURB   the string used as blurb when constructing the
 559--                           parameter is guaranteed to remain valid and
 560--                           unmodified for the lifetime of the parameter.
 561--                           Since 2.8
 562
 563--    -----------------------------------------------------------------------
 564
 565--   G_PARAM_READWRITE
 566
 567--  #define G_PARAM_READWRITE       (G_PARAM_READABLE | G_PARAM_WRITABLE)
 568
 569--    GParamFlags value alias for G_PARAM_READABLE | G_PARAM_WRITABLE.
 570
 571--    -----------------------------------------------------------------------
 572
 573--   G_PARAM_MASK
 574
 575--  #define G_PARAM_MASK            (0x000000ff)
 576
 577--    Mask containing the bits of GParamSpec.flags which are reserved for
 578--    GLib.
 579
 580--    -----------------------------------------------------------------------
 581
 582--   G_PARAM_USER_SHIFT
 583
 584--  #define G_PARAM_USER_SHIFT      (8)
 585
 586--    Minimum shift count to be used for user defined flags, to be stored in
 587--    GParamSpec.flags.
 588
 589--    -----------------------------------------------------------------------
 590
 591--   g_param_spec_ref ()
 592
 593--  GParamSpec* g_param_spec_ref                (GParamSpec *pspec);
 594
 595--    Increments the reference count of pspec.
 596
 597--    pspec :   a valid GParamSpec
 598--    Returns : the GParamSpec that was passed into this function
 599
 600--    -----------------------------------------------------------------------
 601
 602--   g_param_spec_unref ()
 603
 604--  void        g_param_spec_unref              (GParamSpec *pspec);
 605
 606--    Decrements the reference count of a pspec.
 607
 608--    pspec : a valid GParamSpec
 609
 610--    -----------------------------------------------------------------------
 611
 612--   g_param_spec_sink ()
 613
 614--  void        g_param_spec_sink               (GParamSpec *pspec);
 615
 616--    The initial reference count of a newly created GParamSpec is 1, even
 617--    though no one has explicitly called g_param_spec_ref() on it yet. So
 618--    the initial reference count is flagged as "floating", until someone
 619--    calls g_param_spec_ref (pspec); g_param_spec_sink (pspec); in sequence
 620--    on it, taking over the initial reference count (thus ending up with a
 621--    pspec that has a reference count of 1 still, but is not flagged
 622--    "floating" anymore).
 623
 624--    pspec : a valid GParamSpec
 625
 626--    -----------------------------------------------------------------------
 627
 628--   g_param_spec_ref_sink ()
 629
 630--  GParamSpec* g_param_spec_ref_sink           (GParamSpec *pspec);
 631
 632--    Convenience function to ref and sink a GParamSpec.
 633
 634--    pspec :   a valid GParamSpec
 635--    Returns : the GParamSpec that was passed into this function
 636
 637--    Since 2.10
 638
 639--    -----------------------------------------------------------------------
 640
 641--   g_param_value_set_default ()
 642
 643--  void        g_param_value_set_default       (GParamSpec *pspec,
 644--                                               GValue *value);
 645
 646--    Sets value to its default value as specified in pspec.
 647
 648--    pspec : a valid GParamSpec
 649--    value : a GValue of correct type for pspec
 650
 651--    -----------------------------------------------------------------------
 652
 653--   g_param_value_defaults ()
 654
 655--  gboolean    g_param_value_defaults          (GParamSpec *pspec,
 656--                                               GValue *value);
 657
 658--    Checks whether value contains the default value as specified in pspec.
 659
 660--    pspec :   a valid GParamSpec
 661--    value :   a GValue of correct type for pspec
 662--    Returns : whether value contains the canonical defualt for this pspec
 663
 664--    -----------------------------------------------------------------------
 665
 666--   g_param_value_validate ()
 667
 668--  gboolean    g_param_value_validate          (GParamSpec *pspec,
 669--                                               GValue *value);
 670
 671--    Ensures that the contents of value comply with the specifications set
 672--    out by pspec. For example, a GParamSpecInt might require that integers
 673--    stored in value may not be smaller than -42 and not be greater than
 674--    +42. If value contains an integer outside of this range, it is modified
 675--    accordingly, so the resulting value will fit into the range -42 .. +42.
 676
 677--    pspec :   a valid GParamSpec
 678--    value :   a GValue of correct type for pspec
 679--    Returns : whether modifying value was necessary to ensure validity
 680
 681--    -----------------------------------------------------------------------
 682
 683--   g_param_value_convert ()
 684
 685--  gboolean    g_param_value_convert           (GParamSpec *pspec,
 686--                                               const GValue *src_value,
 687--                                               GValue *dest_value,
 688--                                               gboolean strict_validation);
 689
 690--    Transforms src_value into dest_value if possible, and then validates
 691--    dest_value, in order for it to conform to pspec. If strict_validation
 692--    is TRUE this function will only succeed if the transformed dest_value
 693--    complied to pspec without modifications. See also
 694--    g_value_type_transformable(), g_value_transform() and
 695--    g_param_value_validate().
 696
 697--    pspec :             a valid GParamSpec
 698--    src_value :         souce GValue
 699--    dest_value :        destination GValue of correct type for pspec
 700--    strict_validation : TRUE requires dest_value to conform to pspec
 701--                        without modifications
 702--    Returns :           TRUE if transformation and validation were
 703--                        successful, FALSE otherwise and dest_value is left
 704--                        untouched.
 705
 706--    -----------------------------------------------------------------------
 707
 708--   g_param_values_cmp ()
 709
 710--  gint        g_param_values_cmp              (GParamSpec *pspec,
 711--                                               const GValue *value1,
 712--                                               const GValue *value2);
 713
 714--    Compares value1 with value2 according to pspec, and return -1, 0 or +1,
 715--    if value1 is found to be less than, equal to or greater than value2,
 716--    respectively.
 717
 718--    pspec :   a valid GParamSpec
 719--    value1 :  a GValue of correct type for pspec
 720--    value2 :  a GValue of correct type for pspec
 721--    Returns : -1, 0 or +1, for a less than, equal to or greater than result
 722
 723--    -----------------------------------------------------------------------
 724
 725--   g_param_spec_get_name ()
 726
 727--  const gchar* g_param_spec_get_name          (GParamSpec *pspec);
 728
 729--    Returns the name of a GParamSpec.
 730
 731--    pspec :   a valid GParamSpec
 732--    Returns : the name of pspec.
 733
 734--    -----------------------------------------------------------------------
 735
 736--   g_param_spec_get_nick ()
 737
 738--  const gchar* g_param_spec_get_nick          (GParamSpec *pspec);
 739
 740--    Returns the nickname of a GParamSpec.
 741
 742--    pspec :   a valid GParamSpec
 743--    Returns : the nickname of pspec.
 744
 745--    -----------------------------------------------------------------------
 746
 747--   g_param_spec_get_blurb ()
 748
 749--  const gchar* g_param_spec_get_blurb         (GParamSpec *pspec);
 750
 751--    Returns the short description of a GParamSpec.
 752
 753--    pspec :   a valid GParamSpec
 754--    Returns : the short description of pspec.
 755
 756--    -----------------------------------------------------------------------
 757
 758--   g_param_spec_get_qdata ()
 759
 760--  gpointer    g_param_spec_get_qdata          (GParamSpec *pspec,
 761--                                               GQuark quark);
 762
 763--    Gets back user data pointers stored via g_param_spec_set_qdata().
 764
 765--    pspec :   a valid GParamSpec
 766--    quark :   a GQuark, naming the user data pointer
 767--    Returns : the user data pointer set, or NULL
 768
 769--    -----------------------------------------------------------------------
 770
 771--   g_param_spec_set_qdata ()
 772
 773--  void        g_param_spec_set_qdata          (GParamSpec *pspec,
 774--                                               GQuark quark,
 775--                                               gpointer data);
 776
 777--    Sets an opaque, named pointer on a GParamSpec. The name is specified
 778--    through a GQuark (retrieved e.g. via g_quark_from_static_string()), and
 779--    the pointer can be gotten back from the pspec with
 780--    g_param_spec_get_qdata(). Setting a previously set user data pointer,
 781--    overrides (frees) the old pointer set, using NULL as pointer
 782--    essentially removes the data stored.
 783
 784--    pspec : the GParamSpec to set store a user data pointer
 785--    quark : a GQuark, naming the user data pointer
 786--    data :  an opaque user data pointer
 787
 788--    -----------------------------------------------------------------------
 789
 790--   g_param_spec_set_qdata_full ()
 791
 792--  void        g_param_spec_set_qdata_full     (GParamSpec *pspec,
 793--                                               GQuark quark,
 794--                                               gpointer data,
 795--                                               GDestroyNotify destroy);
 796
 797--    This function works like g_param_spec_set_qdata(), but in addition, a
 798--    void (*destroy) (gpointer) function may be specified which is called
 799--    with data as argument when the pspec is finalized, or the data is being
 800--    overwritten by a call to g_param_spec_set_qdata() with the same quark.
 801
 802--    pspec :   the GParamSpec to set store a user data pointer
 803--    quark :   a GQuark, naming the user data pointer
 804--    data :    an opaque user data pointer
 805--    destroy : function to invoke with data as argument, when data needs to
 806--              be freed
 807
 808--    -----------------------------------------------------------------------
 809
 810--   g_param_spec_steal_qdata ()
 811
 812--  gpointer    g_param_spec_steal_qdata        (GParamSpec *pspec,
 813--                                               GQuark quark);
 814
 815--    Gets back user data pointers stored via g_param_spec_set_qdata() and
 816--    removes the data from pspec without invoking it's destroy() function
 817--    (if any was set). Usually, calling this function is only required to
 818--    update user data pointers with a destroy notifier.
 819
 820--    pspec :   the GParamSpec to get a stored user data pointer from
 821--    quark :   a GQuark, naming the user data pointer
 822--    Returns : the user data pointer set, or NULL
 823
 824--    -----------------------------------------------------------------------
 825
 826--   g_param_spec_get_redirect_target ()
 827
 828--  GParamSpec* g_param_spec_get_redirect_target
 829--                                              (GParamSpec *pspec);
 830
 831--    If the paramspec redirects operations to another paramspec, returns
 832--    that paramspec. Redirect is used typically for providing a new
 833--    implementation of a property in a derived type while preserving all the
 834--    properties from the parent type. Redirection is established by creating
 835--    a property of type GParamSpecOverride. See g_object_override_property()
 836--    for an example of the use of this capability.
 837
 838--    pspec :   a GParamSpec
 839--    Returns : paramspec to which requests on this paramspec should be
 840--              redirected, or NULL if none.
 841
 842--    Since 2.4
 843
 844--    -----------------------------------------------------------------------
 845
 846--   g_param_spec_internal ()
 847
 848--  gpointer    g_param_spec_internal           (GType param_type,
 849--                                               const gchar *name,
 850--                                               const gchar *nick,
 851--                                               const gchar *blurb,
 852--                                               GParamFlags flags);
 853
 854--    Creates a new GParamSpec instance.
 855
 856--    A property name consists of segments consisting of ASCII letters and
 857--    digits, separated by either the '-' or '_' character. The first
 858--    character of a property name must be a letter. Names which violate
 859--    these rules lead to undefined behaviour.
 860
 861--    When creating and looking up a GParamSpec, either separator can be
 862--    used, but they cannot be mixed. Using '-' is considerably more
 863--    efficient and in fact required when using property names as detail
 864--    strings for signals.
 865
 866--    param_type : the GType for the property; must be derived from
 867--                 G_TYPE_PARAM
 868--    name :       the canonical name of the property
 869--    nick :       the nickname of the property
 870--    blurb :      a short description of the property
 871--    flags :      a combination of GParamFlags
 872--    Returns :    a newly allocated GParamSpec instance
 873
 874--    -----------------------------------------------------------------------
 875
 876--   GParamSpecTypeInfo
 877
 878--  typedef struct {
 879--    /* type system portion */
 880--    guint16         instance_size;                               /* obligatory */
 881--    guint16         n_preallocs;                                 /* optional */
 882--    void          (*instance_init)        (GParamSpec   *pspec); /* optional */
 883
 884--    /* class portion */
 885--    GType           value_type;                                  /* obligatory */
 886--    void          (*finalize)             (GParamSpec   *pspec); /* optional */
 887--    void          (*value_set_default)    (GParamSpec   *pspec,  /* recommended */
 888--                                           GValue       *value);
 889--    gboolean      (*value_validate)       (GParamSpec   *pspec,  /* optional */
 890--                                           GValue       *value);
 891--    gint          (*values_cmp)           (GParamSpec   *pspec,  /* recommended */
 892--                                           const GValue *value1,
 893--                                           const GValue *value2);
 894--  } GParamSpecTypeInfo;
 895
 896--    This structure is used to provide the type system with the information
 897--    required to initialize and destruct (finalize) a parameter's class and
 898--    instances thereof. The initialized structure is passed to the
 899--    g_param_type_register_static() The type system will perform a deep copy
 900--    of this structure, so it's memory does not need to be persistent across
 901--    invocation of g_param_type_register_static().
 902
 903--    guint16 instance_size; Size of the instance (object) structure.
 904--    guint16 n_preallocs;   Prior to GLib 2.10, it specified the number of
 905--                           pre-allocated (cached) instances to reserve
 906--                           memory for (0 indicates no caching). Since GLib
 907--                           2.10, it is ignored, since instances are
 908--                           allocated with the slice allocator now.
 909--    instance_init ()       Location of the instance initialization function
 910--                           (optional).
 911--    GType value_type;      The GType of values conforming to this
 912--                           GParamSpec
 913--    finalize ()            The instance finalization function (optional).
 914--    value_set_default ()   Resets a value to the default value for pspec
 915--                           (recommended, the default is g_value_reset()),
 916--                           see g_param_value_set_default().
 917--    value_validate ()      Ensures that the contents of value comply with
 918--                           the specifications set out by pspec (optional),
 919--                           see g_param_value_set_validate().
 920--    values_cmp ()          Compares value1 with value2 according to pspec
 921--                           (recommended, the default is memcmp()), see
 922--                           g_param_values_cmp().
 923
 924--    -----------------------------------------------------------------------
 925
 926--   g_param_type_register_static ()
 927
 928--  GType       g_param_type_register_static    (const gchar *name,
 929--                                               const GParamSpecTypeInfo *pspec_info);
 930
 931--    Registers name as the name of a new static type derived from
 932--    G_TYPE_PARAM. The type system uses the information contained in the
 933--    GParamSpecTypeInfo structure pointed to by info to manage the
 934--    GParamSpec type and its instances.
 935
 936--    name :       0-terminated string used as the name of the new GParamSpec
 937--                 type.
 938--    pspec_info : The GParamSpecTypeInfo for this GParamSpec type.
 939--    Returns :    The new type identifier.
 940
 941--    -----------------------------------------------------------------------
 942
 943--   GParamSpecPool
 944
 945--  typedef struct _GParamSpecPool GParamSpecPool;
 946
 947--    A GParamSpecPool maintains a collection of GParamSpecs which can be
 948--    quickly accessed by owner and name. The implementation of the GObject
 949--    property system uses such a pool to store the GParamSpecs of the
 950--    properties all object types.
 951
 952--    -----------------------------------------------------------------------
 953
 954--   g_param_spec_pool_new ()
 955
 956--  GParamSpecPool* g_param_spec_pool_new       (gboolean type_prefixing);
 957
 958--    Creates a new GParamSpecPool.
 959
 960--    If type_prefixing is TRUE, lookups in the newly created pool will allow
 961--    to specify the owner as a colon-separated prefix of the property name,
 962--    like "GtkContainer:border-width". This feature is deprecated, so you
 963--    should always set type_prefixing to FALSE.
 964
 965--    type_prefixing : Whether the pool will support type-prefixed property
 966--                     names.
 967--    Returns :        a newly allocated GParamSpecPool.
 968
 969--    -----------------------------------------------------------------------
 970
 971--   g_param_spec_pool_insert ()
 972
 973--  void        g_param_spec_pool_insert        (GParamSpecPool *pool,
 974--                                               GParamSpec *pspec,
 975--                                               GType owner_type);
 976
 977--    Inserts a GParamSpec in the pool.
 978
 979--    pool :       a GParamSpecPool.
 980--    pspec :      the GParamSpec to insert
 981--    owner_type : a GType identifying the owner of pspec
 982
 983--    -----------------------------------------------------------------------
 984
 985--   g_param_spec_pool_remove ()
 986
 987--  void        g_param_spec_pool_remove        (GParamSpecPool *pool,
 988--                                               GParamSpec *pspec);
 989
 990--    Removes a GParamSpec from the pool.
 991
 992--    pool :  a GParamSpecPool
 993--    pspec : the GParamSpec to remove
 994
 995--    -----------------------------------------------------------------------
 996
 997--   g_param_spec_pool_lookup ()
 998
 999--  GParamSpec* g_param_spec_pool_lookup        (GParamSpecPool *pool,
1000--                                               const gchar *param_name,
1001--                                               GType owner_type,
1002--                                               gboolean walk_ancestors);
1003
1004--    Looks up a GParamSpec in the pool.
1005
1006--    pool :           a GParamSpecPool
1007--    param_name :     the name to look for
1008--    owner_type :     the owner to look for
1009--    walk_ancestors : If TRUE, also try to find a GParamSpec with param_name
1010--                     owned by an ancestor of owner_type.
1011--    Returns :        The found GParamSpec, or NULL if no matching
1012--                     GParamSpec was found.
1013
1014--    -----------------------------------------------------------------------
1015
1016--   g_param_spec_pool_list ()
1017
1018--  GParamSpec** g_param_spec_pool_list         (GParamSpecPool *pool,
1019--                                               GType owner_type,
1020--                                               guint *n_pspecs_p);
1021
1022--    Gets an array of all GParamSpecs owned by owner_type in the pool.
1023
1024--    pool :       a GParamSpecPool
1025--    owner_type : the owner to look for
1026--    n_pspecs_p : return location for the length of the returned array
1027--    Returns :    a newly allocated array containing pointers to all
1028--                 GParamSpecs owned by owner_type in the pool
1029
1030--    -----------------------------------------------------------------------
1031
1032--   g_param_spec_pool_list_owned ()
1033
1034--  GList*      g_param_spec_pool_list_owned    (GParamSpecPool *pool,
1035--                                               GType owner_type);
1036
1037--    Gets an GList of all GParamSpecs owned by owner_type in the pool.
1038
1039--    pool :       a GParamSpecPool
1040--    owner_type : the owner to look for
1041--    Returns :    a GList of all GParamSpecs owned by owner_type in the
1042--                 poolGParamSpecs.
1043feature -- size
1044
1045	struct_size: INTEGER is
1046		external "C use <glib-object.h>"
1047		alias "sizeof(GParamSpec)"
1048		end
1049
1050	-- invariant 
1051	-- is_shared: is_shared
1052	-- initialized: is_initialized
1053end