1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gtk.Label; 26 27 private import glib.ConstructionException; 28 private import glib.Str; 29 private import gobject.ObjectG; 30 private import gobject.Signals; 31 private import gtk.Menu; 32 private import gtk.Misc; 33 private import gtk.Widget; 34 private import gtkc.gtk; 35 public import gtkc.gtktypes; 36 private import pango.PgAttributeList; 37 private import pango.PgLayout; 38 private import std.algorithm; 39 40 41 /** 42 * The #GtkLabel widget displays a small amount of text. As the name 43 * implies, most labels are used to label another widget such as a 44 * #GtkButton, a #GtkMenuItem, or a #GtkComboBox. 45 * 46 * # CSS nodes 47 * 48 * |[<!-- language="plain" --> 49 * label 50 * ├── [selection] 51 * ├── [link] 52 * ┊ 53 * ╰── [link] 54 * ]| 55 * 56 * GtkLabel has a single CSS node with the name label. A wide variety 57 * of style classes may be applied to labels, such as .title, .subtitle, 58 * .dim-label, etc. In the #GtkShortcutsWindow, labels are used wth the 59 * .keycap style class. 60 * 61 * If the label has a selection, it gets a subnode with name selection. 62 * 63 * If the label has links, there is one subnode per link. These subnodes 64 * carry the link or visited state depending on whether they have been 65 * visited. 66 * 67 * # GtkLabel as GtkBuildable 68 * 69 * The GtkLabel implementation of the GtkBuildable interface supports a 70 * custom <attributes> element, which supports any number of <attribute> 71 * elements. The <attribute> element has attributes named “name“, “value“, 72 * “start“ and “end“ and allows you to specify #PangoAttribute values for 73 * this label. 74 * 75 * An example of a UI definition fragment specifying Pango attributes: 76 * |[ 77 * <object class="GtkLabel"> 78 * <attributes> 79 * <attribute name="weight" value="PANGO_WEIGHT_BOLD"/> 80 * <attribute name="background" value="red" start="5" end="10"/>" 81 * </attributes> 82 * </object> 83 * ]| 84 * 85 * The start and end attributes specify the range of characters to which the 86 * Pango attribute applies. If start and end are not specified, the attribute is 87 * applied to the whole text. Note that specifying ranges does not make much 88 * sense with translatable attributes. Use markup embedded in the translatable 89 * content instead. 90 * 91 * # Mnemonics 92 * 93 * Labels may contain “mnemonics”. Mnemonics are 94 * underlined characters in the label, used for keyboard navigation. 95 * Mnemonics are created by providing a string with an underscore before 96 * the mnemonic character, such as `"_File"`, to the 97 * functions gtk_label_new_with_mnemonic() or 98 * gtk_label_set_text_with_mnemonic(). 99 * 100 * Mnemonics automatically activate any activatable widget the label is 101 * inside, such as a #GtkButton; if the label is not inside the 102 * mnemonic’s target widget, you have to tell the label about the target 103 * using gtk_label_set_mnemonic_widget(). Here’s a simple example where 104 * the label is inside a button: 105 * 106 * |[<!-- language="C" --> 107 * // Pressing Alt+H will activate this button 108 * button = gtk_button_new (); 109 * label = gtk_label_new_with_mnemonic ("_Hello"); 110 * gtk_container_add (GTK_CONTAINER (button), label); 111 * ]| 112 * 113 * There’s a convenience function to create buttons with a mnemonic label 114 * already inside: 115 * 116 * |[<!-- language="C" --> 117 * // Pressing Alt+H will activate this button 118 * button = gtk_button_new_with_mnemonic ("_Hello"); 119 * ]| 120 * 121 * To create a mnemonic for a widget alongside the label, such as a 122 * #GtkEntry, you have to point the label at the entry with 123 * gtk_label_set_mnemonic_widget(): 124 * 125 * |[<!-- language="C" --> 126 * // Pressing Alt+H will focus the entry 127 * entry = gtk_entry_new (); 128 * label = gtk_label_new_with_mnemonic ("_Hello"); 129 * gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry); 130 * ]| 131 * 132 * # Markup (styled text) 133 * 134 * To make it easy to format text in a label (changing colors, 135 * fonts, etc.), label text can be provided in a simple 136 * [markup format][PangoMarkupFormat]. 137 * 138 * Here’s how to create a label with a small font: 139 * |[<!-- language="C" --> 140 * label = gtk_label_new (NULL); 141 * gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>"); 142 * ]| 143 * 144 * (See [complete documentation][PangoMarkupFormat] of available 145 * tags in the Pango manual.) 146 * 147 * The markup passed to gtk_label_set_markup() must be valid; for example, 148 * literal <, > and & characters must be escaped as <, >, and &. 149 * If you pass text obtained from the user, file, or a network to 150 * gtk_label_set_markup(), you’ll want to escape it with 151 * g_markup_escape_text() or g_markup_printf_escaped(). 152 * 153 * Markup strings are just a convenient way to set the #PangoAttrList on 154 * a label; gtk_label_set_attributes() may be a simpler way to set 155 * attributes in some cases. Be careful though; #PangoAttrList tends to 156 * cause internationalization problems, unless you’re applying attributes 157 * to the entire string (i.e. unless you set the range of each attribute 158 * to [0, %G_MAXINT)). The reason is that specifying the start_index and 159 * end_index for a #PangoAttribute requires knowledge of the exact string 160 * being displayed, so translations will cause problems. 161 * 162 * # Selectable labels 163 * 164 * Labels can be made selectable with gtk_label_set_selectable(). 165 * Selectable labels allow the user to copy the label contents to 166 * the clipboard. Only labels that contain useful-to-copy information 167 * — such as error messages — should be made selectable. 168 * 169 * # Text layout # {#label-text-layout} 170 * 171 * A label can contain any number of paragraphs, but will have 172 * performance problems if it contains more than a small number. 173 * Paragraphs are separated by newlines or other paragraph separators 174 * understood by Pango. 175 * 176 * Labels can automatically wrap text if you call 177 * gtk_label_set_line_wrap(). 178 * 179 * gtk_label_set_justify() sets how the lines in a label align 180 * with one another. If you want to set how the label as a whole 181 * aligns in its available space, see the #GtkWidget:halign and 182 * #GtkWidget:valign properties. 183 * 184 * The #GtkLabel:width-chars and #GtkLabel:max-width-chars properties 185 * can be used to control the size allocation of ellipsized or wrapped 186 * labels. For ellipsizing labels, if either is specified (and less 187 * than the actual text size), it is used as the minimum width, and the actual 188 * text size is used as the natural width of the label. For wrapping labels, 189 * width-chars is used as the minimum width, if specified, and max-width-chars 190 * is used as the natural width. Even if max-width-chars specified, wrapping 191 * labels will be rewrapped to use all of the available width. 192 * 193 * Note that the interpretation of #GtkLabel:width-chars and 194 * #GtkLabel:max-width-chars has changed a bit with the introduction of 195 * [width-for-height geometry management.][geometry-management] 196 * 197 * # Links 198 * 199 * Since 2.18, GTK+ supports markup for clickable hyperlinks in addition 200 * to regular Pango markup. The markup for links is borrowed from HTML, 201 * using the `<a>` with “href“ and “title“ attributes. GTK+ renders links 202 * similar to the way they appear in web browsers, with colored, underlined 203 * text. The “title“ attribute is displayed as a tooltip on the link. 204 * 205 * An example looks like this: 206 * 207 * |[<!-- language="C" --> 208 * const gchar *text = 209 * "Go to the" 210 * "<a href=\"http://www.gtk.org title="<i>Our</i> website\">" 211 * "GTK+ website</a> for more..."; 212 * gtk_label_set_markup (label, text); 213 * ]| 214 * 215 * It is possible to implement custom handling for links and their tooltips with 216 * the #GtkLabel::activate-link signal and the gtk_label_get_current_uri() function. 217 */ 218 public class Label : Misc 219 { 220 /** the main Gtk struct */ 221 protected GtkLabel* gtkLabel; 222 223 /** Get the main Gtk struct */ 224 public GtkLabel* getLabelStruct(bool transferOwnership = false) 225 { 226 if (transferOwnership) 227 ownedRef = false; 228 return gtkLabel; 229 } 230 231 /** the main Gtk struct as a void* */ 232 protected override void* getStruct() 233 { 234 return cast(void*)gtkLabel; 235 } 236 237 protected override void setStruct(GObject* obj) 238 { 239 gtkLabel = cast(GtkLabel*)obj; 240 super.setStruct(obj); 241 } 242 243 /** 244 * Sets our main struct and passes it to the parent class. 245 */ 246 public this (GtkLabel* gtkLabel, bool ownedRef = false) 247 { 248 this.gtkLabel = gtkLabel; 249 super(cast(GtkMisc*)gtkLabel, ownedRef); 250 } 251 252 /** 253 * Creates a new GtkLabel, containing the text in str. 254 * If characters in str are preceded by an underscore, they are 255 * underlined. If you need a literal underscore character in a label, use 256 * '__' (two underscores). The first underlined character represents a 257 * keyboard accelerator called a mnemonic. The mnemonic key can be used 258 * to activate another widget, chosen automatically, or explicitly using 259 * setMnemonicWidget(). 260 * 261 * If setMnemonicWidget() is not called, then the first activatable ancestor of the Label 262 * will be chosen as the mnemonic widget. For instance, if the 263 * label is inside a button or menu item, the button or menu item will 264 * automatically become the mnemonic widget and be activated by 265 * the mnemonic. 266 * Params: 267 * str = The text of the label, with an underscore in front of the 268 * mnemonic character 269 * mnemonic = when false uses the literal text passed in without mnemonic 270 * Throws: ConstructionException GTK+ fails to create the object. 271 */ 272 public this (string str, bool mnemonic=true) 273 { 274 GtkLabel* p; 275 276 if ( mnemonic ) 277 { 278 // GtkWidget* gtk_label_new_with_mnemonic (const gchar *str); 279 p = cast(GtkLabel*)gtk_label_new_with_mnemonic(Str.toStringz(str)); 280 } 281 else 282 { 283 // GtkWidget* gtk_label_new (const gchar *str); 284 p = cast(GtkLabel*)gtk_label_new(Str.toStringz(str)); 285 } 286 287 if(p is null) 288 { 289 throw new ConstructionException("null returned by gtk_label_new"); 290 } 291 292 this(p); 293 } 294 295 /** 296 */ 297 298 /** */ 299 public static GType getType() 300 { 301 return gtk_label_get_type(); 302 } 303 304 /** 305 * Gets the angle of rotation for the label. See 306 * gtk_label_set_angle(). 307 * 308 * Returns: the angle of rotation for the label 309 * 310 * Since: 2.6 311 */ 312 public double getAngle() 313 { 314 return gtk_label_get_angle(gtkLabel); 315 } 316 317 /** 318 * Gets the attribute list that was set on the label using 319 * gtk_label_set_attributes(), if any. This function does 320 * not reflect attributes that come from the labels markup 321 * (see gtk_label_set_markup()). If you want to get the 322 * effective attributes for the label, use 323 * pango_layout_get_attribute (gtk_label_get_layout (label)). 324 * 325 * Returns: the attribute list, or %NULL 326 * if none was set. 327 */ 328 public PgAttributeList getAttributes() 329 { 330 auto p = gtk_label_get_attributes(gtkLabel); 331 332 if(p is null) 333 { 334 return null; 335 } 336 337 return ObjectG.getDObject!(PgAttributeList)(cast(PangoAttrList*) p); 338 } 339 340 /** 341 * Returns the URI for the currently active link in the label. 342 * The active link is the one under the mouse pointer or, in a 343 * selectable label, the link in which the text cursor is currently 344 * positioned. 345 * 346 * This function is intended for use in a #GtkLabel::activate-link handler 347 * or for use in a #GtkWidget::query-tooltip handler. 348 * 349 * Returns: the currently active URI. The string is owned by GTK+ and must 350 * not be freed or modified. 351 * 352 * Since: 2.18 353 */ 354 public string getCurrentUri() 355 { 356 return Str.toString(gtk_label_get_current_uri(gtkLabel)); 357 } 358 359 /** 360 * Returns the ellipsizing position of the label. See gtk_label_set_ellipsize(). 361 * 362 * Returns: #PangoEllipsizeMode 363 * 364 * Since: 2.6 365 */ 366 public PangoEllipsizeMode getEllipsize() 367 { 368 return gtk_label_get_ellipsize(gtkLabel); 369 } 370 371 /** 372 * Returns the justification of the label. See gtk_label_set_justify(). 373 * 374 * Returns: #GtkJustification 375 */ 376 public GtkJustification getJustify() 377 { 378 return gtk_label_get_justify(gtkLabel); 379 } 380 381 /** 382 * Fetches the text from a label widget including any embedded 383 * underlines indicating mnemonics and Pango markup. (See 384 * gtk_label_get_text()). 385 * 386 * Returns: the text of the label widget. This string is 387 * owned by the widget and must not be modified or freed. 388 */ 389 public string getLabel() 390 { 391 return Str.toString(gtk_label_get_label(gtkLabel)); 392 } 393 394 /** 395 * Gets the #PangoLayout used to display the label. 396 * The layout is useful to e.g. convert text positions to 397 * pixel positions, in combination with gtk_label_get_layout_offsets(). 398 * The returned layout is owned by the @label so need not be 399 * freed by the caller. The @label is free to recreate its layout at 400 * any time, so it should be considered read-only. 401 * 402 * Returns: the #PangoLayout for this label 403 */ 404 public PgLayout getLayout() 405 { 406 auto p = gtk_label_get_layout(gtkLabel); 407 408 if(p is null) 409 { 410 return null; 411 } 412 413 return ObjectG.getDObject!(PgLayout)(cast(PangoLayout*) p); 414 } 415 416 /** 417 * Obtains the coordinates where the label will draw the #PangoLayout 418 * representing the text in the label; useful to convert mouse events 419 * into coordinates inside the #PangoLayout, e.g. to take some action 420 * if some part of the label is clicked. Of course you will need to 421 * create a #GtkEventBox to receive the events, and pack the label 422 * inside it, since labels are windowless (they return %FALSE from 423 * gtk_widget_get_has_window()). Remember 424 * when using the #PangoLayout functions you need to convert to 425 * and from pixels using PANGO_PIXELS() or #PANGO_SCALE. 426 * 427 * Params: 428 * x = location to store X offset of layout, or %NULL 429 * y = location to store Y offset of layout, or %NULL 430 */ 431 public void getLayoutOffsets(out int x, out int y) 432 { 433 gtk_label_get_layout_offsets(gtkLabel, &x, &y); 434 } 435 436 /** 437 * Returns whether lines in the label are automatically wrapped. 438 * See gtk_label_set_line_wrap(). 439 * 440 * Returns: %TRUE if the lines of the label are automatically wrapped. 441 */ 442 public bool getLineWrap() 443 { 444 return gtk_label_get_line_wrap(gtkLabel) != 0; 445 } 446 447 /** 448 * Returns line wrap mode used by the label. See gtk_label_set_line_wrap_mode(). 449 * 450 * Returns: %TRUE if the lines of the label are automatically wrapped. 451 * 452 * Since: 2.10 453 */ 454 public PangoWrapMode getLineWrapMode() 455 { 456 return gtk_label_get_line_wrap_mode(gtkLabel); 457 } 458 459 /** 460 * Gets the number of lines to which an ellipsized, wrapping 461 * label should be limited. See gtk_label_set_lines(). 462 * 463 * Returns: The number of lines 464 * 465 * Since: 3.10 466 */ 467 public int getLines() 468 { 469 return gtk_label_get_lines(gtkLabel); 470 } 471 472 /** 473 * Retrieves the desired maximum width of @label, in characters. See 474 * gtk_label_set_width_chars(). 475 * 476 * Returns: the maximum width of the label in characters. 477 * 478 * Since: 2.6 479 */ 480 public int getMaxWidthChars() 481 { 482 return gtk_label_get_max_width_chars(gtkLabel); 483 } 484 485 /** 486 * If the label has been set so that it has an mnemonic key this function 487 * returns the keyval used for the mnemonic accelerator. If there is no 488 * mnemonic set up it returns #GDK_KEY_VoidSymbol. 489 * 490 * Returns: GDK keyval usable for accelerators, or #GDK_KEY_VoidSymbol 491 */ 492 public uint getMnemonicKeyval() 493 { 494 return gtk_label_get_mnemonic_keyval(gtkLabel); 495 } 496 497 /** 498 * Retrieves the target of the mnemonic (keyboard shortcut) of this 499 * label. See gtk_label_set_mnemonic_widget(). 500 * 501 * Returns: the target of the label’s mnemonic, 502 * or %NULL if none has been set and the default algorithm will be used. 503 */ 504 public Widget getMnemonicWidget() 505 { 506 auto p = gtk_label_get_mnemonic_widget(gtkLabel); 507 508 if(p is null) 509 { 510 return null; 511 } 512 513 return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p); 514 } 515 516 /** 517 * Gets the value set by gtk_label_set_selectable(). 518 * 519 * Returns: %TRUE if the user can copy text from the label 520 */ 521 public bool getSelectable() 522 { 523 return gtk_label_get_selectable(gtkLabel) != 0; 524 } 525 526 /** 527 * Gets the selected range of characters in the label, returning %TRUE 528 * if there’s a selection. 529 * 530 * Params: 531 * start = return location for start of selection, as a character offset 532 * end = return location for end of selection, as a character offset 533 * 534 * Returns: %TRUE if selection is non-empty 535 */ 536 public bool getSelectionBounds(out int start, out int end) 537 { 538 return gtk_label_get_selection_bounds(gtkLabel, &start, &end) != 0; 539 } 540 541 /** 542 * Returns whether the label is in single line mode. 543 * 544 * Returns: %TRUE when the label is in single line mode. 545 * 546 * Since: 2.6 547 */ 548 public bool getSingleLineMode() 549 { 550 return gtk_label_get_single_line_mode(gtkLabel) != 0; 551 } 552 553 /** 554 * Fetches the text from a label widget, as displayed on the 555 * screen. This does not include any embedded underlines 556 * indicating mnemonics or Pango markup. (See gtk_label_get_label()) 557 * 558 * Returns: the text in the label widget. This is the internal 559 * string used by the label, and must not be modified. 560 */ 561 public string getText() 562 { 563 return Str.toString(gtk_label_get_text(gtkLabel)); 564 } 565 566 /** 567 * Returns whether the label is currently keeping track 568 * of clicked links. 569 * 570 * Returns: %TRUE if clicked links are remembered 571 * 572 * Since: 2.18 573 */ 574 public bool getTrackVisitedLinks() 575 { 576 return gtk_label_get_track_visited_links(gtkLabel) != 0; 577 } 578 579 /** 580 * Returns whether the label’s text is interpreted as marked up with 581 * the [Pango text markup language][PangoMarkupFormat]. 582 * See gtk_label_set_use_markup (). 583 * 584 * Returns: %TRUE if the label’s text will be parsed for markup. 585 */ 586 public bool getUseMarkup() 587 { 588 return gtk_label_get_use_markup(gtkLabel) != 0; 589 } 590 591 /** 592 * Returns whether an embedded underline in the label indicates a 593 * mnemonic. See gtk_label_set_use_underline(). 594 * 595 * Returns: %TRUE whether an embedded underline in the label indicates 596 * the mnemonic accelerator keys. 597 */ 598 public bool getUseUnderline() 599 { 600 return gtk_label_get_use_underline(gtkLabel) != 0; 601 } 602 603 /** 604 * Retrieves the desired width of @label, in characters. See 605 * gtk_label_set_width_chars(). 606 * 607 * Returns: the width of the label in characters. 608 * 609 * Since: 2.6 610 */ 611 public int getWidthChars() 612 { 613 return gtk_label_get_width_chars(gtkLabel); 614 } 615 616 /** 617 * Gets the #GtkLabel:xalign property for @label. 618 * 619 * Returns: the xalign property 620 * 621 * Since: 3.16 622 */ 623 public float getXalign() 624 { 625 return gtk_label_get_xalign(gtkLabel); 626 } 627 628 /** 629 * Gets the #GtkLabel:yalign property for @label. 630 * 631 * Returns: the yalign property 632 * 633 * Since: 3.16 634 */ 635 public float getYalign() 636 { 637 return gtk_label_get_yalign(gtkLabel); 638 } 639 640 /** 641 * Selects a range of characters in the label, if the label is selectable. 642 * See gtk_label_set_selectable(). If the label is not selectable, 643 * this function has no effect. If @start_offset or 644 * @end_offset are -1, then the end of the label will be substituted. 645 * 646 * Params: 647 * startOffset = start offset (in characters not bytes) 648 * endOffset = end offset (in characters not bytes) 649 */ 650 public void selectRegion(int startOffset, int endOffset) 651 { 652 gtk_label_select_region(gtkLabel, startOffset, endOffset); 653 } 654 655 /** 656 * Sets the angle of rotation for the label. An angle of 90 reads from 657 * from bottom to top, an angle of 270, from top to bottom. The angle 658 * setting for the label is ignored if the label is selectable, 659 * wrapped, or ellipsized. 660 * 661 * Params: 662 * angle = the angle that the baseline of the label makes with 663 * the horizontal, in degrees, measured counterclockwise 664 * 665 * Since: 2.6 666 */ 667 public void setAngle(double angle) 668 { 669 gtk_label_set_angle(gtkLabel, angle); 670 } 671 672 /** 673 * Sets a #PangoAttrList; the attributes in the list are applied to the 674 * label text. 675 * 676 * The attributes set with this function will be applied 677 * and merged with any other attributes previously effected by way 678 * of the #GtkLabel:use-underline or #GtkLabel:use-markup properties. 679 * While it is not recommended to mix markup strings with manually set 680 * attributes, if you must; know that the attributes will be applied 681 * to the label after the markup string is parsed. 682 * 683 * Params: 684 * attrs = a #PangoAttrList, or %NULL 685 */ 686 public void setAttributes(PgAttributeList attrs) 687 { 688 gtk_label_set_attributes(gtkLabel, (attrs is null) ? null : attrs.getPgAttributeListStruct()); 689 } 690 691 /** 692 * Sets the mode used to ellipsize (add an ellipsis: "...") to the text 693 * if there is not enough space to render the entire string. 694 * 695 * Params: 696 * mode = a #PangoEllipsizeMode 697 * 698 * Since: 2.6 699 */ 700 public void setEllipsize(PangoEllipsizeMode mode) 701 { 702 gtk_label_set_ellipsize(gtkLabel, mode); 703 } 704 705 /** 706 * Sets the alignment of the lines in the text of the label relative to 707 * each other. %GTK_JUSTIFY_LEFT is the default value when the widget is 708 * first created with gtk_label_new(). If you instead want to set the 709 * alignment of the label as a whole, use gtk_widget_set_halign() instead. 710 * gtk_label_set_justify() has no effect on labels containing only a 711 * single line. 712 * 713 * Params: 714 * jtype = a #GtkJustification 715 */ 716 public void setJustify(GtkJustification jtype) 717 { 718 gtk_label_set_justify(gtkLabel, jtype); 719 } 720 721 /** 722 * Sets the text of the label. The label is interpreted as 723 * including embedded underlines and/or Pango markup depending 724 * on the values of the #GtkLabel:use-underline and 725 * #GtkLabel:use-markup properties. 726 * 727 * Params: 728 * str = the new text to set for the label 729 */ 730 public void setLabel(string str) 731 { 732 gtk_label_set_label(gtkLabel, Str.toStringz(str)); 733 } 734 735 /** 736 * Toggles line wrapping within the #GtkLabel widget. %TRUE makes it break 737 * lines if text exceeds the widget’s size. %FALSE lets the text get cut off 738 * by the edge of the widget if it exceeds the widget size. 739 * 740 * Note that setting line wrapping to %TRUE does not make the label 741 * wrap at its parent container’s width, because GTK+ widgets 742 * conceptually can’t make their requisition depend on the parent 743 * container’s size. For a label that wraps at a specific position, 744 * set the label’s width using gtk_widget_set_size_request(). 745 * 746 * Params: 747 * wrap = the setting 748 */ 749 public void setLineWrap(bool wrap) 750 { 751 gtk_label_set_line_wrap(gtkLabel, wrap); 752 } 753 754 /** 755 * If line wrapping is on (see gtk_label_set_line_wrap()) this controls how 756 * the line wrapping is done. The default is %PANGO_WRAP_WORD which means 757 * wrap on word boundaries. 758 * 759 * Params: 760 * wrapMode = the line wrapping mode 761 * 762 * Since: 2.10 763 */ 764 public void setLineWrapMode(PangoWrapMode wrapMode) 765 { 766 gtk_label_set_line_wrap_mode(gtkLabel, wrapMode); 767 } 768 769 /** 770 * Sets the number of lines to which an ellipsized, wrapping label 771 * should be limited. This has no effect if the label is not wrapping 772 * or ellipsized. Set this to -1 if you don’t want to limit the 773 * number of lines. 774 * 775 * Params: 776 * lines = the desired number of lines, or -1 777 * 778 * Since: 3.10 779 */ 780 public void setLines(int lines) 781 { 782 gtk_label_set_lines(gtkLabel, lines); 783 } 784 785 /** 786 * Parses @str which is marked up with the 787 * [Pango text markup language][PangoMarkupFormat], setting the 788 * label’s text and attribute list based on the parse results. 789 * 790 * If the @str is external data, you may need to escape it with 791 * g_markup_escape_text() or g_markup_printf_escaped(): 792 * 793 * |[<!-- language="C" --> 794 * const char *format = "<span style=\"italic\">\%s</span>"; 795 * char *markup; 796 * 797 * markup = g_markup_printf_escaped (format, str); 798 * gtk_label_set_markup (GTK_LABEL (label), markup); 799 * g_free (markup); 800 * ]| 801 * 802 * This function will set the #GtkLabel:use-markup property to %TRUE as 803 * a side effect. 804 * 805 * If you set the label contents using the #GtkLabel:label property you 806 * should also ensure that you set the #GtkLabel:use-markup property 807 * accordingly. 808 * 809 * See also: gtk_label_set_text() 810 * 811 * Params: 812 * str = a markup string (see [Pango markup format][PangoMarkupFormat]) 813 */ 814 public void setMarkup(string str) 815 { 816 gtk_label_set_markup(gtkLabel, Str.toStringz(str)); 817 } 818 819 /** 820 * Parses @str which is marked up with the 821 * [Pango text markup language][PangoMarkupFormat], 822 * setting the label’s text and attribute list based on the parse results. 823 * If characters in @str are preceded by an underscore, they are underlined 824 * indicating that they represent a keyboard accelerator called a mnemonic. 825 * 826 * The mnemonic key can be used to activate another widget, chosen 827 * automatically, or explicitly using gtk_label_set_mnemonic_widget(). 828 * 829 * Params: 830 * str = a markup string (see 831 * [Pango markup format][PangoMarkupFormat]) 832 */ 833 public void setMarkupWithMnemonic(string str) 834 { 835 gtk_label_set_markup_with_mnemonic(gtkLabel, Str.toStringz(str)); 836 } 837 838 /** 839 * Sets the desired maximum width in characters of @label to @n_chars. 840 * 841 * Params: 842 * nChars = the new desired maximum width, in characters. 843 * 844 * Since: 2.6 845 */ 846 public void setMaxWidthChars(int nChars) 847 { 848 gtk_label_set_max_width_chars(gtkLabel, nChars); 849 } 850 851 /** 852 * If the label has been set so that it has an mnemonic key (using 853 * i.e. gtk_label_set_markup_with_mnemonic(), 854 * gtk_label_set_text_with_mnemonic(), gtk_label_new_with_mnemonic() 855 * or the “use_underline” property) the label can be associated with a 856 * widget that is the target of the mnemonic. When the label is inside 857 * a widget (like a #GtkButton or a #GtkNotebook tab) it is 858 * automatically associated with the correct widget, but sometimes 859 * (i.e. when the target is a #GtkEntry next to the label) you need to 860 * set it explicitly using this function. 861 * 862 * The target widget will be accelerated by emitting the 863 * GtkWidget::mnemonic-activate signal on it. The default handler for 864 * this signal will activate the widget if there are no mnemonic collisions 865 * and toggle focus between the colliding widgets otherwise. 866 * 867 * Params: 868 * widget = the target #GtkWidget 869 */ 870 public void setMnemonicWidget(Widget widget) 871 { 872 gtk_label_set_mnemonic_widget(gtkLabel, (widget is null) ? null : widget.getWidgetStruct()); 873 } 874 875 /** 876 * The pattern of underlines you want under the existing text within the 877 * #GtkLabel widget. For example if the current text of the label says 878 * “FooBarBaz” passing a pattern of “___ ___” will underline 879 * “Foo” and “Baz” but not “Bar”. 880 * 881 * Params: 882 * pattern = The pattern as described above. 883 */ 884 public void setPattern(string pattern) 885 { 886 gtk_label_set_pattern(gtkLabel, Str.toStringz(pattern)); 887 } 888 889 /** 890 * Selectable labels allow the user to select text from the label, for 891 * copy-and-paste. 892 * 893 * Params: 894 * setting = %TRUE to allow selecting text in the label 895 */ 896 public void setSelectable(bool setting) 897 { 898 gtk_label_set_selectable(gtkLabel, setting); 899 } 900 901 /** 902 * Sets whether the label is in single line mode. 903 * 904 * Params: 905 * singleLineMode = %TRUE if the label should be in single line mode 906 * 907 * Since: 2.6 908 */ 909 public void setSingleLineMode(bool singleLineMode) 910 { 911 gtk_label_set_single_line_mode(gtkLabel, singleLineMode); 912 } 913 914 /** 915 * Sets the text within the #GtkLabel widget. It overwrites any text that 916 * was there before. 917 * 918 * This function will clear any previously set mnemonic accelerators, and 919 * set the #GtkLabel:use-underline property to %FALSE as a side effect. 920 * 921 * This function will set the #GtkLabel:use-markup property to %FALSE 922 * as a side effect. 923 * 924 * See also: gtk_label_set_markup() 925 * 926 * Params: 927 * str = The text you want to set 928 */ 929 public void setText(string str) 930 { 931 gtk_label_set_text(gtkLabel, Str.toStringz(str)); 932 } 933 934 /** 935 * Sets the label’s text from the string @str. 936 * If characters in @str are preceded by an underscore, they are underlined 937 * indicating that they represent a keyboard accelerator called a mnemonic. 938 * The mnemonic key can be used to activate another widget, chosen 939 * automatically, or explicitly using gtk_label_set_mnemonic_widget(). 940 * 941 * Params: 942 * str = a string 943 */ 944 public void setTextWithMnemonic(string str) 945 { 946 gtk_label_set_text_with_mnemonic(gtkLabel, Str.toStringz(str)); 947 } 948 949 /** 950 * Sets whether the label should keep track of clicked 951 * links (and use a different color for them). 952 * 953 * Params: 954 * trackLinks = %TRUE to track visited links 955 * 956 * Since: 2.18 957 */ 958 public void setTrackVisitedLinks(bool trackLinks) 959 { 960 gtk_label_set_track_visited_links(gtkLabel, trackLinks); 961 } 962 963 /** 964 * Sets whether the text of the label contains markup in 965 * [Pango’s text markup language][PangoMarkupFormat]. 966 * See gtk_label_set_markup(). 967 * 968 * Params: 969 * setting = %TRUE if the label’s text should be parsed for markup. 970 */ 971 public void setUseMarkup(bool setting) 972 { 973 gtk_label_set_use_markup(gtkLabel, setting); 974 } 975 976 /** 977 * If true, an underline in the text indicates the next character should be 978 * used for the mnemonic accelerator key. 979 * 980 * Params: 981 * setting = %TRUE if underlines in the text indicate mnemonics 982 */ 983 public void setUseUnderline(bool setting) 984 { 985 gtk_label_set_use_underline(gtkLabel, setting); 986 } 987 988 /** 989 * Sets the desired width in characters of @label to @n_chars. 990 * 991 * Params: 992 * nChars = the new desired width, in characters. 993 * 994 * Since: 2.6 995 */ 996 public void setWidthChars(int nChars) 997 { 998 gtk_label_set_width_chars(gtkLabel, nChars); 999 } 1000 1001 /** 1002 * Sets the #GtkLabel:xalign property for @label. 1003 * 1004 * Params: 1005 * xalign = the new xalign value, between 0 and 1 1006 * 1007 * Since: 3.16 1008 */ 1009 public void setXalign(float xalign) 1010 { 1011 gtk_label_set_xalign(gtkLabel, xalign); 1012 } 1013 1014 /** 1015 * Sets the #GtkLabel:yalign property for @label. 1016 * 1017 * Params: 1018 * yalign = the new yalign value, between 0 and 1 1019 * 1020 * Since: 3.16 1021 */ 1022 public void setYalign(float yalign) 1023 { 1024 gtk_label_set_yalign(gtkLabel, yalign); 1025 } 1026 1027 protected class OnActivateCurrentLinkDelegateWrapper 1028 { 1029 static OnActivateCurrentLinkDelegateWrapper[] listeners; 1030 void delegate(Label) dlg; 1031 gulong handlerId; 1032 1033 this(void delegate(Label) dlg) 1034 { 1035 this.dlg = dlg; 1036 this.listeners ~= this; 1037 } 1038 1039 void remove(OnActivateCurrentLinkDelegateWrapper source) 1040 { 1041 foreach(index, wrapper; listeners) 1042 { 1043 if (wrapper.handlerId == source.handlerId) 1044 { 1045 listeners[index] = null; 1046 listeners = std.algorithm.remove(listeners, index); 1047 break; 1048 } 1049 } 1050 } 1051 } 1052 1053 /** 1054 * A [keybinding signal][GtkBindingSignal] 1055 * which gets emitted when the user activates a link in the label. 1056 * 1057 * Applications may also emit the signal with g_signal_emit_by_name() 1058 * if they need to control activation of URIs programmatically. 1059 * 1060 * The default bindings for this signal are all forms of the Enter key. 1061 * 1062 * Since: 2.18 1063 */ 1064 gulong addOnActivateCurrentLink(void delegate(Label) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1065 { 1066 auto wrapper = new OnActivateCurrentLinkDelegateWrapper(dlg); 1067 wrapper.handlerId = Signals.connectData( 1068 this, 1069 "activate-current-link", 1070 cast(GCallback)&callBackActivateCurrentLink, 1071 cast(void*)wrapper, 1072 cast(GClosureNotify)&callBackActivateCurrentLinkDestroy, 1073 connectFlags); 1074 return wrapper.handlerId; 1075 } 1076 1077 extern(C) static void callBackActivateCurrentLink(GtkLabel* labelStruct, OnActivateCurrentLinkDelegateWrapper wrapper) 1078 { 1079 wrapper.dlg(wrapper.outer); 1080 } 1081 1082 extern(C) static void callBackActivateCurrentLinkDestroy(OnActivateCurrentLinkDelegateWrapper wrapper, GClosure* closure) 1083 { 1084 wrapper.remove(wrapper); 1085 } 1086 1087 protected class OnActivateLinkDelegateWrapper 1088 { 1089 static OnActivateLinkDelegateWrapper[] listeners; 1090 bool delegate(string, Label) dlg; 1091 gulong handlerId; 1092 1093 this(bool delegate(string, Label) dlg) 1094 { 1095 this.dlg = dlg; 1096 this.listeners ~= this; 1097 } 1098 1099 void remove(OnActivateLinkDelegateWrapper source) 1100 { 1101 foreach(index, wrapper; listeners) 1102 { 1103 if (wrapper.handlerId == source.handlerId) 1104 { 1105 listeners[index] = null; 1106 listeners = std.algorithm.remove(listeners, index); 1107 break; 1108 } 1109 } 1110 } 1111 } 1112 1113 /** 1114 * The signal which gets emitted to activate a URI. 1115 * Applications may connect to it to override the default behaviour, 1116 * which is to call gtk_show_uri_on_window(). 1117 * 1118 * Params: 1119 * uri = the URI that is activated 1120 * 1121 * Returns: %TRUE if the link has been activated 1122 * 1123 * Since: 2.18 1124 */ 1125 gulong addOnActivateLink(bool delegate(string, Label) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1126 { 1127 auto wrapper = new OnActivateLinkDelegateWrapper(dlg); 1128 wrapper.handlerId = Signals.connectData( 1129 this, 1130 "activate-link", 1131 cast(GCallback)&callBackActivateLink, 1132 cast(void*)wrapper, 1133 cast(GClosureNotify)&callBackActivateLinkDestroy, 1134 connectFlags); 1135 return wrapper.handlerId; 1136 } 1137 1138 extern(C) static int callBackActivateLink(GtkLabel* labelStruct, char* uri, OnActivateLinkDelegateWrapper wrapper) 1139 { 1140 return wrapper.dlg(Str.toString(uri), wrapper.outer); 1141 } 1142 1143 extern(C) static void callBackActivateLinkDestroy(OnActivateLinkDelegateWrapper wrapper, GClosure* closure) 1144 { 1145 wrapper.remove(wrapper); 1146 } 1147 1148 protected class OnCopyClipboardDelegateWrapper 1149 { 1150 static OnCopyClipboardDelegateWrapper[] listeners; 1151 void delegate(Label) dlg; 1152 gulong handlerId; 1153 1154 this(void delegate(Label) dlg) 1155 { 1156 this.dlg = dlg; 1157 this.listeners ~= this; 1158 } 1159 1160 void remove(OnCopyClipboardDelegateWrapper source) 1161 { 1162 foreach(index, wrapper; listeners) 1163 { 1164 if (wrapper.handlerId == source.handlerId) 1165 { 1166 listeners[index] = null; 1167 listeners = std.algorithm.remove(listeners, index); 1168 break; 1169 } 1170 } 1171 } 1172 } 1173 1174 /** 1175 * The ::copy-clipboard signal is a 1176 * [keybinding signal][GtkBindingSignal] 1177 * which gets emitted to copy the selection to the clipboard. 1178 * 1179 * The default binding for this signal is Ctrl-c. 1180 */ 1181 gulong addOnCopyClipboard(void delegate(Label) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1182 { 1183 auto wrapper = new OnCopyClipboardDelegateWrapper(dlg); 1184 wrapper.handlerId = Signals.connectData( 1185 this, 1186 "copy-clipboard", 1187 cast(GCallback)&callBackCopyClipboard, 1188 cast(void*)wrapper, 1189 cast(GClosureNotify)&callBackCopyClipboardDestroy, 1190 connectFlags); 1191 return wrapper.handlerId; 1192 } 1193 1194 extern(C) static void callBackCopyClipboard(GtkLabel* labelStruct, OnCopyClipboardDelegateWrapper wrapper) 1195 { 1196 wrapper.dlg(wrapper.outer); 1197 } 1198 1199 extern(C) static void callBackCopyClipboardDestroy(OnCopyClipboardDelegateWrapper wrapper, GClosure* closure) 1200 { 1201 wrapper.remove(wrapper); 1202 } 1203 1204 protected class OnMoveCursorDelegateWrapper 1205 { 1206 static OnMoveCursorDelegateWrapper[] listeners; 1207 void delegate(GtkMovementStep, int, bool, Label) dlg; 1208 gulong handlerId; 1209 1210 this(void delegate(GtkMovementStep, int, bool, Label) dlg) 1211 { 1212 this.dlg = dlg; 1213 this.listeners ~= this; 1214 } 1215 1216 void remove(OnMoveCursorDelegateWrapper source) 1217 { 1218 foreach(index, wrapper; listeners) 1219 { 1220 if (wrapper.handlerId == source.handlerId) 1221 { 1222 listeners[index] = null; 1223 listeners = std.algorithm.remove(listeners, index); 1224 break; 1225 } 1226 } 1227 } 1228 } 1229 1230 /** 1231 * The ::move-cursor signal is a 1232 * [keybinding signal][GtkBindingSignal] 1233 * which gets emitted when the user initiates a cursor movement. 1234 * If the cursor is not visible in @entry, this signal causes 1235 * the viewport to be moved instead. 1236 * 1237 * Applications should not connect to it, but may emit it with 1238 * g_signal_emit_by_name() if they need to control the cursor 1239 * programmatically. 1240 * 1241 * The default bindings for this signal come in two variants, 1242 * the variant with the Shift modifier extends the selection, 1243 * the variant without the Shift modifer does not. 1244 * There are too many key combinations to list them all here. 1245 * - Arrow keys move by individual characters/lines 1246 * - Ctrl-arrow key combinations move by words/paragraphs 1247 * - Home/End keys move to the ends of the buffer 1248 * 1249 * Params: 1250 * step = the granularity of the move, as a #GtkMovementStep 1251 * count = the number of @step units to move 1252 * extendSelection = %TRUE if the move should extend the selection 1253 */ 1254 gulong addOnMoveCursor(void delegate(GtkMovementStep, int, bool, Label) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1255 { 1256 auto wrapper = new OnMoveCursorDelegateWrapper(dlg); 1257 wrapper.handlerId = Signals.connectData( 1258 this, 1259 "move-cursor", 1260 cast(GCallback)&callBackMoveCursor, 1261 cast(void*)wrapper, 1262 cast(GClosureNotify)&callBackMoveCursorDestroy, 1263 connectFlags); 1264 return wrapper.handlerId; 1265 } 1266 1267 extern(C) static void callBackMoveCursor(GtkLabel* labelStruct, GtkMovementStep step, int count, bool extendSelection, OnMoveCursorDelegateWrapper wrapper) 1268 { 1269 wrapper.dlg(step, count, extendSelection, wrapper.outer); 1270 } 1271 1272 extern(C) static void callBackMoveCursorDestroy(OnMoveCursorDelegateWrapper wrapper, GClosure* closure) 1273 { 1274 wrapper.remove(wrapper); 1275 } 1276 1277 protected class OnPopulatePopupDelegateWrapper 1278 { 1279 static OnPopulatePopupDelegateWrapper[] listeners; 1280 void delegate(Menu, Label) dlg; 1281 gulong handlerId; 1282 1283 this(void delegate(Menu, Label) dlg) 1284 { 1285 this.dlg = dlg; 1286 this.listeners ~= this; 1287 } 1288 1289 void remove(OnPopulatePopupDelegateWrapper source) 1290 { 1291 foreach(index, wrapper; listeners) 1292 { 1293 if (wrapper.handlerId == source.handlerId) 1294 { 1295 listeners[index] = null; 1296 listeners = std.algorithm.remove(listeners, index); 1297 break; 1298 } 1299 } 1300 } 1301 } 1302 1303 /** 1304 * The ::populate-popup signal gets emitted before showing the 1305 * context menu of the label. Note that only selectable labels 1306 * have context menus. 1307 * 1308 * If you need to add items to the context menu, connect 1309 * to this signal and append your menuitems to the @menu. 1310 * 1311 * Params: 1312 * menu = the menu that is being populated 1313 */ 1314 gulong addOnPopulatePopup(void delegate(Menu, Label) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1315 { 1316 auto wrapper = new OnPopulatePopupDelegateWrapper(dlg); 1317 wrapper.handlerId = Signals.connectData( 1318 this, 1319 "populate-popup", 1320 cast(GCallback)&callBackPopulatePopup, 1321 cast(void*)wrapper, 1322 cast(GClosureNotify)&callBackPopulatePopupDestroy, 1323 connectFlags); 1324 return wrapper.handlerId; 1325 } 1326 1327 extern(C) static void callBackPopulatePopup(GtkLabel* labelStruct, GtkMenu* menu, OnPopulatePopupDelegateWrapper wrapper) 1328 { 1329 wrapper.dlg(ObjectG.getDObject!(Menu)(menu), wrapper.outer); 1330 } 1331 1332 extern(C) static void callBackPopulatePopupDestroy(OnPopulatePopupDelegateWrapper wrapper, GClosure* closure) 1333 { 1334 wrapper.remove(wrapper); 1335 } 1336 }