APPENDIX A GTK+ Properties Python provides the property system used by GTK+, which allows you to customize how widgets interact with the user and how they are drawn on the screen. In the following sections, you are provided with a complete reference to the widget and child properties available in GTK+ 3. GTK+ Properties Every class derived from GObject can create any number of properties. In GTK+, these properties store information about the current state of the widget. For example, Gtk.Button has a property called relief that defines the type of relief border used by the button in its normal state. In the following code, object.relief was used to retrieve the current value stored by the button’s relief property. This method accepts a single property name and returns the value of the property. You can also use object.relief(value) to set each object property. relief = button.props.relief There are a great number of properties available to widgets; Tables A-1 through A-­132 provide a full properties list for each widget and object in GTK+ 3. Remember that object properties are inherited from parent widgets, so you should investigate a widget’s hierarchy for a full list of properties. For more information on each object, you should reference the API documentation. 413 © W. David Ashley and Andrew Krause 2019 W. D. Ashley and A. Krause, Foundations of PyGTK Development, https://doi.org/10.1007/978-1-4842-4179-0 AppENDiX A GTK+ PrOpErtiEs Caution In the GTK+ C API, property names may contain one or more dashes. Since these dashes are interpreted by Python as the subtraction operator, all Python property names substitute underscores for dashes in all property names. For instance, the property name logo-icon-name becomes logo_icon_name in a Python program. Table A-1. Gtk.AboutDialog Properties Property Type Description artists string A list of individuals who helped create the artwork used by the application. This often includes information such as an e-mail address or URL for each artist, which is displayed as a link. authors string A list of individuals who helped program the application. This often includes information such as an e-mail address or URL for each programmer, which is displayed as a link. comments string A short string that describes the general functionality of the program. This is displayed in the main dialog window, so it should not be too long. copyright string Copyright information about the application. This is displayed in the main dialog window, so it should not be too long. An example copyright string would be “(C) Copyright 2018 Author”. documenters string A list of individuals who helped write documentation for the application. This often includes information such as an e-mail address or URL for each documenter, which is displayed as a link. license string The content of the license for the application. This is displayed with a Gtk.TextView widget in a secondary dialog, so the length of the string does not matter. license-type Gtk.License The license type of the program. (continued) 414 AppENDiX A GTK+ PrOpErtiEs Table A-1. (continued) Property Type Description logo GdkPixbuf An image that is displayed as the application’s logo in the main window. If this is not set, window.get_default_icon_ list() is used. logo-icon-­name string An icon name from the icon theme to use as the logo in the main About dialog. If this is set, it takes precedence over the logo property. program-­name string The name of the application to display in the main About dialog. If you do not set this property, GLib.get_ application_name() is used. translator-­credits string A string that holds information about the translator(s) for the current language. It should be set as translatable, so each translator can provide a custom string. This often includes information such as an e-mail address or URL for each translator, which is displayed as a link. version string The version of the application that the user is running. website string A URL to the homepage for the application. This string must be prefixed withhttp:// . website-label string A label to display in place of the web site URL. If this is not set, website is set as the URL label. wrap-license boolean If set to True, the license content is wrapped. Table A-2. GtkAccelGroup Properties Property Type Description is-locked boolean Is the accel group locked. modifier-mask Gdk.ModifierType Modifier Mask. 415 AppENDiX A GTK+ PrOpErtiEs Table A-3. Gtk.AccelLabel Properties Property Type Description accel-closure GObject.Closure The closure that should be watched for changes to the keyboard accelerator. accel-widget Gtk.Widget The widget that should be watched for changes to the keyboard accelerator. Table A-4. Gtk.Accessible Properties Property Type Description widget Gtk.Widget The widget referenced by this accessible. Table A-5. Gtk.Adjustment Properties Property Type Description lower double The minimum double value that the adjustment can reach. page-increment double The increment that is shifted when moving one page forward or backward. page-size double The size of a page of the adjustment. You should set this to zero when you use Gtk.Adjustment for Gtk.SpinButton. step-increment double The increment that is moved in an individual step. For example, with Gtk.SpinButton, a single step is taken when an arrow button is pressed. upper double The maximum double value that the adjustment can reach. value double The current value of the adjustment, which is always between lower and upper. 416 AppENDiX A GTK+ PrOpErtiEs Table A-6. Gtk.AppChooserButton Properties Property Type Description heading string The text to show at the top of the dialog. show-default-item boolean Whether the combobox should show the default application on top. show-dialog-item boolean Whether the combobox should include an item that triggers a Gtk.AppChooserDialog. Table A-7. Gtk.AppChooserDialog Properties Property Type Description gfile Gio.File The Gio.File used by the app chooser dialog. heading string The text to show at the top of the dialog. Table A-8. Gtk.AppChooserWidget Properties Property Type Description default-text string The default text appearing when there are no applications. show-all boolean Whether the widget should show all applications. show-default boolean Whether the widget should show the default application. show-fallback boolean Whether the widget should show fallback applications. show-other boolean Whether the widget should show other applications. show-recommended boolean Whether the widget should show recommended applications. Table A-9. Gtk.Application Properties Property Type Description active-window Gtk.Window The window that most recently had focus. app-menu Gio.MenuModel The Gio.MenuModel for the application menu. menubar Gio.MenuModel The Gio.MenuModel for the menubar. register-session boolean Register with the session manager. 417 AppENDiX A GTK+ PrOpErtiEs Table A-10. Gtk.ApplicationWindow Properties Property Type Description active-window Gtk.Window The window that most recently had focus. show-menubar boolean True if the window should show a menubar at the top of the window. Table A-11. Gtk.Arrow Properties Property Type Description active-window Gtk.Window The window that most recently had focus. arrow-type Gtk.ArrowType The direction the arrow should point. shadow-type Gtk.ShadowType Appearance of the shadow surrounding the arrow. Table A-12. Gtk.AspectFrame Properties Property Type Description obey-child boolean Force aspect ratio to match that of the frame’s child. ratio float Aspect ratio if obey_child is False. shadow-type float Appearance of the shadow surrounding the arrow. xalign float X alignment of the child. yalign float Y alignment of the child. Table A-13. Gtk.Assistant Properties Property Type Description use-header-bar integer Use Header Bar for actions. 418 AppENDiX A GTK+ PrOpErtiEs Table A-14. Gtk.Box Properties Property Type Description baseline-position Gtk.BaselinePosition The position of the baseline aligned widgets if extra space is available. homogeneous boolean Whether the children should all be the same size. spacing integer The amount of space between children. Table A-15. Gtk.Builder Properties Property Type Description translation-domain string The translation domain used by gettext(). Table A-16. Gtk.Button Properties Property Type Description always-show-image boolean Whether the image is always shown. image Gtk.Widget Child widget to appear next to the button text. image-position Gtk.PositionType The position of the image relative to the text. label string Text of the label widget inside the button, if the button contains a label widget. relief Gtk.ReliefStyle The border relief style. use-underline boolean If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key. Table A-17. Gtk.ButtonBox Properties Property Type Description layout-style Gtk.ButtonBoxStyle How to lay out the buttons in the box. Possible values are spread, edge, start and end. 419 AppENDiX A GTK+ PrOpErtiEs Table A-18. Gtk.Calendar Properties Property Type Description day integer The selected day (as a number between 1 and 31, or 0 to unselect the current day. detail-height-rows integer Details height in rows. detail-width-chars integer Details width in characters. month integer The selected month (as a number between 0 and 11). no-month-change boolean If True, the selected month cannot be changed. show-day-names boolean If True, day names are displayed. show-details boolean If True, details are shown. show-heading boolean If True, a heading is displayed. show-week-numbers boolean If True, week numbers are displayed. year integer The selected year. Table A-19. Gtk.CellArea Properties Property Type Description edit-widget Gtk.CellEditable The widget currently editing the edited cell.