1 2@c %start of fragment 3 4@deftp Class <gtk-recent-manager> 5Derives from @code{<gobject>}. 6 7This class defines the following slots: 8 9@table @code 10@item filename 11The full path to the file to be used to store and read the list 12 13@item limit 14The maximum number of items to be returned by gtk_recent_manager_get_items() 15 16@item size 17The size of the recently used resources list 18 19@end table 20 21@end deftp 22 23@defop Signal <gtk-recent-manager> changed 24Emitted when the current recently used resources manager changes its contents. 25 26Since 2.10 27 28@end defop 29 30@deftp Class <gtk-recent-info> 31Derives from @code{<gboxed>}. 32 33This class defines no direct slots. 34 35@end deftp 36 37@deffn Function gtk-recent-manager-new @result{}@tie{} (ret@tie{}@code{<gtk-recent-manager>}) 38Creates a new recent manager object. Recent manager objects are used to handle 39the list of recently used resources. A @code{<gtk-recent-manager>} object 40monitors the recently used resources list, and emits the "changed" signal each 41time something inside the list changes. 42 43@code{<gtk-recent-manager>} objects are expensive: be sure to create them only 44when needed. You should use the @code{gtk-recent-manager-new-for-screen} or the 45@code{gtk-recent-manager-get-default} functions instead. 46 47@table @var 48@item ret 49A newly created @code{<gtk-recent-manager>} object. 50 51@end table 52 53Since 2.10 54 55@end deffn 56 57@deffn Function gtk-recent-manager-get-default @result{}@tie{} (ret@tie{}@code{<gtk-recent-manager>}) 58Gets the recent manager for the default screen. See 59@code{gtk-recent-manager-get-for-screen}. 60 61@table @var 62@item ret 63A unique @code{<gtk-recent-manager>} associated with the default screen. This 64recent manager is associated with the screen and can be used as long as the 65screen is open. Do not ref or unref it. 66 67@end table 68 69Since 2.10 70 71@end deffn 72 73@deffn Function gtk-recent-manager-get-for-screen (screen@tie{}@code{<gdk-screen>}) @result{}@tie{} (ret@tie{}@code{<gtk-recent-manager>}) 74Gets the recent manager object associated with @var{screen}; if this function 75has not previously been called for the given screen, a new recent manager object 76will be created and associated with the screen. Recent manager objects are 77fairly expensive to create, so using this function is usually a better choice 78than calling @code{gtk-recent-manager-new} and setting the screen yourself; by 79using this function a single recent manager object will be shared between users. 80 81@table @var 82@item screen 83a @code{<gdk-screen>} 84 85@item ret 86A unique @code{<gtk-recent-manager>} associated with the given screen. This 87recent manager is associated to the with the screen and can be used as long as 88the screen is open. Do not ref or unref it. 89 90@end table 91 92Since 2.10 93 94@end deffn 95 96@deffn Function gtk-recent-manager-set-screen (self@tie{}@code{<gtk-recent-manager>}) (screen@tie{}@code{<gdk-screen>}) 97@deffnx Method set-screen 98Sets the screen for a recent manager; the screen is used to track the user's 99currently configured recently used documents storage. 100 101@table @var 102@item manager 103a @code{<gtk-recent-manager>} 104 105@item screen 106a @code{<gdk-screen>} 107 108@end table 109 110Since 2.10 111 112@end deffn 113 114@deffn Function gtk-recent-manager-add-item (self@tie{}@code{<gtk-recent-manager>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool}) 115@deffnx Method add-item 116Adds a new resource, pointed by @var{uri}, into the recently used resources 117list. 118 119This function automatically retrieving some of the needed metadata and setting 120other metadata to common default values; it then feeds the data to 121@code{gtk-recent-manager-add-full}. 122 123See @code{gtk-recent-manager-add-full} if you want to explicitely define the 124metadata for the resource pointed by @var{uri}. 125 126@table @var 127@item manager 128a @code{<gtk-recent-manager>} 129 130@item uri 131a valid URI 132 133@item ret 134@samp{@code{#t}} if the new item was successfully added to the recently used 135resources list 136 137@end table 138 139Since 2.10 140 141@end deffn 142 143@deffn Function gtk-recent-manager-remove-item (self@tie{}@code{<gtk-recent-manager>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool}) 144@deffnx Method remove-item 145Removes a resource pointed by @var{uri} from the recently used resources list 146handled by a recent manager. 147 148@table @var 149@item manager 150a @code{<gtk-recent-manager>} 151 152@item uri 153the URI of the item you wish to remove 154 155@item error 156return location for a @code{<g-error>}, or @samp{@code{#f}} 157 158@item ret 159@samp{@code{#t}} if the item pointed by @var{uri} has been successfully removed 160by the recently used resources list, and @samp{@code{#f}} otherwise. 161 162@end table 163 164Since 2.10 165 166@end deffn 167 168@deffn Function gtk-recent-manager-lookup-item (self@tie{}@code{<gtk-recent-manager>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{<gtk-recent-info>}) 169@deffnx Method lookup-item 170Searches for a URI inside the recently used resources list, and returns a 171structure containing informations about the resource like its MIME type, or its 172display name. 173 174@table @var 175@item manager 176a @code{<gtk-recent-manager>} 177 178@item uri 179a URI 180 181@item error 182a return location for a @code{<g-error>}, or @samp{@code{#f}} 183 184@item ret 185a @code{<gtk-recent-info>} structure containing information about the resource 186pointed by @var{uri}, or @samp{@code{#f}} if the URI was not registered in the 187recently used resources list. Free with @code{gtk-recent-info-unref}. 188 189@end table 190 191Since 2.10 192 193@end deffn 194 195@deffn Function gtk-recent-manager-has-item (self@tie{}@code{<gtk-recent-manager>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool}) 196@deffnx Method has-item 197Checks whether there is a recently used resource registered with @var{uri} 198inside the recent manager. 199 200@table @var 201@item manager 202a @code{<gtk-recent-manager>} 203 204@item uri 205a URI 206 207@item ret 208@samp{@code{#t}} if the resource was found, @samp{@code{#f}} otherwise. 209 210@end table 211 212Since 2.10 213 214@end deffn 215 216@deffn Function gtk-recent-manager-move-item (self@tie{}@code{<gtk-recent-manager>}) (uri@tie{}@code{mchars}) (new_uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool}) 217@deffnx Method move-item 218Changes the location of a recently used resource from @var{uri} to 219@var{new-uri}. 220 221Please note that this function will not affect the resource pointed by the URIs, 222but only the URI used in the recently used resources list. 223 224@table @var 225@item manager 226a @code{<gtk-recent-manager>} 227 228@item uri 229the URI of a recently used resource 230 231@item new-uri 232the new URI of the recently used resource, or @samp{@code{#f}} to remove the 233item pointed by @var{uri} in the list 234 235@item error 236a return location for a @code{<g-error>}, or @samp{@code{#f}} 237 238@item ret 239@samp{@code{#t}} on success. 240 241@end table 242 243Since 2.10 244 245@end deffn 246 247@deffn Function gtk-recent-manager-get-limit (self@tie{}@code{<gtk-recent-manager>}) @result{}@tie{} (ret@tie{}@code{int}) 248@deffnx Method get-limit 249Gets the maximum number of items that the @code{gtk-recent-manager-get-items} 250function should return. 251 252@table @var 253@item manager 254a @code{<gtk-recent-manager>} 255 256@item ret 257the number of items to return, or -1 for every item. 258 259@end table 260 261Since 2.10 262 263@end deffn 264 265@deffn Function gtk-recent-manager-set-limit (self@tie{}@code{<gtk-recent-manager>}) (limit@tie{}@code{int}) 266@deffnx Method set-limit 267Sets the maximum number of item that the @code{gtk-recent-manager-get-items} 268function should return. If @var{limit} is set to -1, then return all the items. 269 270@table @var 271@item manager 272a @code{<gtk-recent-manager>} 273 274@item limit 275the maximum number of items to return, or -1. 276 277@end table 278 279Since 2.10 280 281@end deffn 282 283@deffn Function gtk-recent-manager-get-items (self@tie{}@code{<gtk-recent-manager>}) @result{}@tie{} (ret@tie{}@code{glist-of}) 284@deffnx Method get-items 285Gets the list of recently used resources. 286 287@table @var 288@item manager 289a @code{<gtk-recent-manager>} 290 291@item ret 292a list of newly allocated @code{<gtk-recent-info>} objects. Use 293@code{gtk-recent-info-unref} on each item inside the list, and then free the 294list itself using @code{g-list-free}. 295 296@end table 297 298Since 2.10 299 300@end deffn 301 302@deffn Function gtk-recent-manager-purge-items (self@tie{}@code{<gtk-recent-manager>}) @result{}@tie{} (ret@tie{}@code{int}) 303@deffnx Method purge-items 304Purges every item from the recently used resources list. 305 306@table @var 307@item manager 308a @code{<gtk-recent-manager>} 309 310@item error 311a return location for a @code{<g-error>}, or @samp{@code{#f}} 312 313@item ret 314the number of items that have been removed from the recently used resources 315list. 316 317@end table 318 319Since 2.10 320 321@end deffn 322 323@deffn Function gtk-recent-info-get-uri (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{mchars}) 324Gets the URI of the resource. 325 326@table @var 327@item info 328a @code{<gtk-recent-info>} 329 330@item ret 331the URI of the resource. The returned string is owned by the recent manager, and 332should not be freed. 333 334@end table 335 336Since 2.10 337 338@end deffn 339 340@deffn Function gtk-recent-info-get-display-name (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{mchars}) 341Gets the name of the resource. If none has been defined, the basename of the 342resource is obtained. 343 344@table @var 345@item info 346a @code{<gtk-recent-info>} 347 348@item ret 349the display name of the resource. The returned string is owned by the recent 350manager, and should not be freed. 351 352@end table 353 354Since 2.10 355 356@end deffn 357 358@deffn Function gtk-recent-info-get-description (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{mchars}) 359Gets the (short) description of the resource. 360 361@table @var 362@item info 363a @code{<gtk-recent-info>} 364 365@item ret 366the description of the resource. The returned string is owned by the recent 367manager, and should not be freed. 368 369@end table 370 371Since 2.10 372 373@end deffn 374 375@deffn Function gtk-recent-info-get-mime-type (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{mchars}) 376Gets the MIME type of the resource. 377 378@table @var 379@item info 380a @code{<gtk-recent-info>} 381 382@item ret 383the MIME type of the resource. The returned string is owned by the recent 384manager, and should not be freed. 385 386@end table 387 388Since 2.10 389 390@end deffn 391 392@deffn Function gtk-recent-info-get-added (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{long}) 393Gets the timestamp (seconds from system's Epoch) when the resource was added to 394the recently used resources list. 395 396@table @var 397@item info 398a @code{<gtk-recent-info>} 399 400@item ret 401the number of seconds elapsed from system's Epoch when the resource was added to 402the list, or -1 on failure. 403 404@end table 405 406Since 2.10 407 408@end deffn 409 410@deffn Function gtk-recent-info-get-modified (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{long}) 411Gets the timestamp (seconds from system's Epoch) when the resource was last 412modified. 413 414@table @var 415@item info 416a @code{<gtk-recent-info>} 417 418@item ret 419the number of seconds elapsed from system's Epoch when the resource was last 420modified, or -1 on failure. 421 422@end table 423 424Since 2.10 425 426@end deffn 427 428@deffn Function gtk-recent-info-get-visited (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{long}) 429Gets the timestamp (seconds from system's Epoch) when the resource was last 430visited. 431 432@table @var 433@item info 434a @code{<gtk-recent-info>} 435 436@item ret 437the number of seconds elapsed from system's Epoch when the resource was last 438visited, or -1 on failure. 439 440@end table 441 442Since 2.10 443 444@end deffn 445 446@deffn Function gtk-recent-info-get-private-hint (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{bool}) 447Gets the value of the "private" flag. Resources in the recently used list that 448have this flag set to @samp{@code{#t}} should only be displayed by the 449applications that have registered them. 450 451@table @var 452@item info 453a @code{<gtk-recent-info>} 454 455@item ret 456@samp{@code{#t}} if the private flag was found, @samp{@code{#f}} otherwise. 457 458@end table 459 460Since 2.10 461 462@end deffn 463 464@deffn Function gtk-recent-info-last-application (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{mchars}) 465Gets the name of the last application that have registered the recently used 466resource represented by @var{info}. 467 468@table @var 469@item info 470a @code{<gtk-recent-info>} 471 472@item ret 473an application name. Use @code{g-free} to free it. 474 475@end table 476 477Since 2.10 478 479@end deffn 480 481@deffn Function gtk-recent-info-has-group (self@tie{}@code{<gtk-recent-info>}) (group_name@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool}) 482Checks whether @var{group-name} appears inside the groups registered for the 483recently used item @var{info}. 484 485@table @var 486@item info 487a @code{<gtk-recent-info>} 488 489@item group-name 490name of a group 491 492@item ret 493@samp{@code{#t}} if the group was found. 494 495@end table 496 497Since 2.10 498 499@end deffn 500 501@deffn Function gtk-recent-info-has-application (self@tie{}@code{<gtk-recent-info>}) (app_name@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool}) 502Checks whether an application registered this resource using @var{app-name}. 503 504@table @var 505@item info 506a @code{<gtk-recent-info>} 507 508@item app-name 509a string containing an application name 510 511@item ret 512@samp{@code{#t}} if an application with name @var{app-name} was found, 513@samp{@code{#f}} otherwise. 514 515@end table 516 517Since 2.10 518 519@end deffn 520 521@deffn Function gtk-recent-info-get-icon (self@tie{}@code{<gtk-recent-info>}) (size@tie{}@code{int}) @result{}@tie{} (ret@tie{}@code{<gdk-pixbuf>}) 522Retrieves the icon of size @var{size} associated to the resource MIME type. 523 524@table @var 525@item info 526a @code{<gtk-recent-info>} 527 528@item size 529the size of the icon in pixels 530 531@item ret 532a @code{<gdk-pixbuf>} containing the icon, or @samp{@code{#f}}. 533 534@end table 535 536Since 2.10 537 538@end deffn 539 540@deffn Function gtk-recent-info-get-short-name (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{mchars}) 541Computes a valid UTF-8 string that can be used as the name of the item in a menu 542or list. For example, calling this function on an item that refers to 543"file:///foo/bar.txt" will yield "bar.txt". 544 545@table @var 546@item info 547an @code{<gtk-recent-info>} 548 549@item ret 550A newly-allocated string in UTF-8 encoding; free it with @code{g-free}. 551 552@end table 553 554Since 2.10 555 556@end deffn 557 558@deffn Function gtk-recent-info-get-uri-display (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{mchars}) 559Gets a displayable version of the resource's URI. 560 561@table @var 562@item info 563a @code{<gtk-recent-info>} 564 565@item ret 566a UTF-8 string containing the resource's URI or @samp{@code{#f}} 567 568@end table 569 570Since 2.10 571 572@end deffn 573 574@deffn Function gtk-recent-info-get-age (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{int}) 575Gets the number of days elapsed since the last update of the resource pointed by 576@var{info}. 577 578@table @var 579@item info 580a @code{<gtk-recent-info>} 581 582@item ret 583a positive integer containing the number of days elapsed since the time this 584resource was last modified. 585 586@end table 587 588Since 2.10 589 590@end deffn 591 592@deffn Function gtk-recent-info-is-local (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{bool}) 593Checks whether the resource is local or not by looking at the scheme of its URI. 594 595@table @var 596@item info 597a @code{<gtk-recent-info>} 598 599@item ret 600@samp{@code{#t}} if the resource is local. 601 602@end table 603 604Since 2.10 605 606@end deffn 607 608@deffn Function gtk-recent-info-exists (self@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{bool}) 609Checks whether the resource pointed by @var{info} still exists. At the moment 610this check is done only on resources pointing to local files. 611 612@table @var 613@item info 614a @code{<gtk-recent-info>} 615 616@item ret 617@samp{@code{#t}} if the resource exists 618 619@end table 620 621Since 2.10 622 623@end deffn 624 625@deffn Function gtk-recent-info-match (self@tie{}@code{<gtk-recent-info>}) (info_b@tie{}@code{<gtk-recent-info>}) @result{}@tie{} (ret@tie{}@code{bool}) 626Checks whether two @code{<gtk-recent-info>} structures point to the same 627resource. 628 629@table @var 630@item info-a 631a @code{<gtk-recent-info>} 632 633@item info-b 634a @code{<gtk-recent-info>} 635 636@item ret 637@samp{@code{#t}} if both @code{<gtk-recent-info>} structures point to se same 638resource, @samp{@code{#f}} otherwise. 639 640@end table 641 642Since 2.10 643 644@end deffn 645 646 647@c %end of fragment 648