/src/wrappers/gobject/library/g_param_spec.e
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