<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:xi="http://www.w3.org/2001/XInclude" type="guide" style="task" id="togglebutton.js" xml:lang="de">

  <info>

  <title type="text">ToggleButton (JavaScript)</title>

    <link type="guide" xref="beginner.js#buttons"/>

    <revision version="0.1" date="2012-06-16" status="draft"/>

    <credit type="author copyright">

      <name>Taryn Fox</name>

      <email its:translate="no">jewelfox@fursona.net</email>

      <years>2012</years>

    </credit>

    <desc>Stays pressed until you click it again</desc>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Mario Blättermann</mal:name>

      <mal:email>mario.blaettermann@gmail.com</mal:email>

      <mal:years>2011, 2013</mal:years>

    </mal:credit>

  </info>

  <title>ToggleButton</title>

  <media type="image" mime="image/png" src="media/togglebutton.png"/>

  
A ToggleButton is like a normal <link xref="button.js">Button</link>, except that it stays pressed in when you click it. You can use it like an on/off switch, to control things like the <link xref="spinner.js">Spinner</link> in this example.

  
A ToggleButton's get_active method returns true if it's pressed in, and false if it's not. Its set_active method is used if you want to change its state without needing to click on it. When it changes state from pressed in to popped out and vice-versa, it sends out the "toggled" signal, which you can connect to a function to do something.

    <links type="section"/>

  <section id="imports">

    <title>Zu importierende Bibliotheken</title>

#!/usr/bin/gjs

const Gio = imports.gi.Gio;

const Gtk = imports.gi.Gtk;

const Lang = imports.lang;

    
These are the libraries we need to import for this application to run. Remember that the line which tells GNOME that we're using Gjs always needs to go at the start.

    </section>

  <section id="applicationwindow">

    <title>Entwurf des Anwendungsfensters</title>

const ToggleButtonExample = new Lang.Class({

    Name: 'ToggleButton Example',

    // Create the application itself

    _init: function() {

        this.application = new Gtk.Application({

            application_id: 'org.example.jstogglebutton',

            flags: Gio.ApplicationFlags.FLAGS_NONE

        });

    // Connect 'activate' and 'startup' signals to the callback functions

    this.application.connect('activate', Lang.bind(this, this._onActivate));

    this.application.connect('startup', Lang.bind(this, this._onStartup));

    },

    // Callback function for 'activate' signal presents window when active

    _onActivate: function() {

        this._window.present();

    },

    // Callback function for 'startup' signal builds the UI

    _onStartup: function() {

        this._buildUI ();

    },

    
All the code for this sample goes in the RadioButtonExample class. The above code creates a <link href="http://www.roojs.com/seed/gir-1.2-gtk-3.0/gjs/Gtk.Application.html">Gtk.Application</link> for our widgets and window to go in.

    // Build the application's UI

    _buildUI: function() {

        // Create the application window

        this._window = new Gtk.ApplicationWindow({

            application: this.application,

            window_position: Gtk.WindowPosition.CENTER,

            default_height: 300,

            default_width: 300,

            border_width: 30,

            title: "ToggleButton Example"});

    
The _buildUI function is where we put all the code to create the application's user interface. The first step is creating a new <link xref="GtkApplicationWindow.js">Gtk.ApplicationWindow</link> to put all our widgets into.

  </section>

  <section id="togglebutton">

    <title>Creating the ToggleButton and other widgets</title>

        // Create the spinner that the button stops and starts

        this._spinner = new Gtk.Spinner ({hexpand: true, vexpand: true});

    
We want this <link xref="spinner.js">Spinner</link> to expand vertically and horizontally, to take up as much space as possible inside the window.

        // Create the togglebutton that starts and stops the spinner

        this._toggleButton = new Gtk.ToggleButton ({label: "Start/Stop"});

        this._toggleButton.connect ('toggled', Lang.bind (this, this._onToggle));

    
Creating a ToggleButton is a lot like creating a normal <link xref="button.js">Button</link>. The biggest difference is that you're handling a "toggled" signal instead of a "clicked" signal. This code binds the _onToggle function to that signal, so that it's called whenever our ToggleButton is toggled.

        // Create a grid and put everything in it

        this._grid = new Gtk.Grid ({

            row_homogeneous: false,

            row_spacing: 15});

        this._grid.attach (this._spinner, 0, 0, 1, 1);

        this._grid.attach (this._toggleButton, 0, 1, 1, 1);

    
Here we create a simple <link xref="grid.js">Grid</link> to organize everything in, then attach the Spinner and ToggleButton to it.

        // Add the grid to the window

        this._window.add (this._grid);

        // Show the window and all child widgets

        this._window.show_all();

    },

    
Now we add the Grid to the Window, and tell the Window to show itself and its child widgets when the application is started.

    </section>

    <section id="toggled">

    <title>Making something happen when the ToggleButton is toggled</title>

    _onToggle: function() {

        // Start or stop the spinner

        if (this._toggleButton.get_active ())

            this._spinner.start ();

        else this._spinner.stop ();

    }

});

    
Whenever someone toggles the button, this function checks what its state is afterwards using get_active and starts or stops the spinner accordingly. We want it to spin only while the button is pressed in, so if get_active returns true we start the spinner. Otherwise, we tell it to stop.

// Run the application

let app = new ToggleButtonExample ();

app.application.run (ARGV);

    
Finally, we create a new instance of the finished RadioButtonExample class, and set the application running.

  </section>

  <section id="complete">

    <title>Complete code sample</title>

#!/usr/bin/gjs

imports.gi.versions.Gtk = '3.0';

const Gio = imports.gi.Gio;

const Gtk = imports.gi.Gtk;

class ToggleButtonExample {

    // Create the application itself

    constructor() {

        this.application = new Gtk.Application({

            application_id: 'org.example.jstogglebutton',

            flags: Gio.ApplicationFlags.FLAGS_NONE

        });

        // Connect 'activate' and 'startup' signals to the callback functions

        this.application.connect('activate', this._onActivate.bind(this));

        this.application.connect('startup', this._onStartup.bind(this));

    }

    // Callback function for 'activate' signal presents window when active

    _onActivate() {

        this._window.present();

    }

    // Callback function for 'startup' signal builds the UI

    _onStartup() {

        this._buildUI();

    }

    // Build the application's UI

    _buildUI() {

        // Create the application window

        this._window = new Gtk.ApplicationWindow({

            application: this.application,

            window_position: Gtk.WindowPosition.CENTER,

            default_height: 300,

            default_width: 300,

            border_width: 30,

            title: "ToggleButton Example"});

        // Create the spinner that the button stops and starts

        this._spinner = new Gtk.Spinner ({hexpand: true, vexpand: true});

        // Create the togglebutton that starts and stops the spinner

        this._toggleButton = new Gtk.ToggleButton ({label: "Start/Stop"});

        this._toggleButton.connect ('toggled', this._onToggle.bind(this));

        // Create a grid and put everything in it

        this._grid = new Gtk.Grid ({

            row_homogeneous: false,

            row_spacing: 15});

        this._grid.attach (this._spinner, 0, 0, 1, 1);

        this._grid.attach (this._toggleButton, 0, 1, 1, 1);

        // Add the grid to the window

        this._window.add (this._grid);

        // Show the window and all child widgets

        this._window.show_all();

    }

    _onToggle() {

        // Start or stop the spinner

        if (this._toggleButton.get_active ())

            this._spinner.start ();

        else this._spinner.stop ();

    }

};

// Run the application

let app = new ToggleButtonExample ();

app.application.run (ARGV);

  </section>

  <section id="in-depth">

    <title>Weiterführende Dokumentation</title>

<list>

  <item>
<link href="http://www.roojs.com/seed/gir-1.2-gtk-3.0/gjs/Gtk.Application.html">Gtk.Application</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html">Gtk.ApplicationWindow</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Grid.html">Gtk.Grid</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Spinner.html">Gtk.Spinner</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.ToggleButton.html">Gtk.ToggleButton</link>
</item>

</list>

  </section>

</page>