QtGradientDialog Class

Detailed Description

The QtGradientDialog class provides a dialog for specifying gradients.

The gradient dialog's function is to allow users to edit gradients. For example, you might use this in a drawing program to allow the user to set the brush gradient.

Starting from the top of the dialog there are several buttons:

[Missing image qtgradientdialogtopbuttons.png]

The first three buttons allow for changing a type of the gradient (QGradient::Type), while the second three allow for changing spread of the gradient (QGradient::Spread). The last button shows or hides the details extension of the dialog. Conceptually the default view with hidden details provides the full functional control over gradient editing. The additional extension with details allows to set gradient's parameters more precisely. The visibility of extension can be controlled by detailsVisible property. Moreover, if you don't want the user to switch on or off the visibility of extension you can set the detailsButtonVisible property to false.

Below top buttons there is an area where edited gradient is interactively previewed. In addition the user can edit gradient type's specific parameters directly in this area by dragging appropriate handles.

In the middle of the dialog there is an area where the user can edit gradient stops.

The top part of this area contains stop handles, and bottom part shows the preview of gradient stops path. In order to create a new gradient stop double click inside the view over the desired position. If you double click on existing stop handle in the top part of the view, clicked handle will be duplicated (duplicate will contain the same color). The stop can be activated by clicking on its handle. You can activate previous or next stop by pressing left or right key respectively. To jump to the first or last stop press home or end key respectively. The gradient stops editor supports multiselection. Clicking a handle holding the shift modifier key down will select a range of stops between the active stop and clicked one. Clicking a handle holding control modifier key down will remove from or add to selection the clicked stop depending if it was or wasn't already selected respectively. Multiselection can also be created using rubberband (by pressing the left mouse button outside of any handle and dragging). Sometimes it's hard to select a stop because its handle can be partially covered by other handle. In that case the user can zoom in the view by spinning mouse wheel. The selected stop handles can be moved by drag & drop. In order to remove selected stops press delete key. For convenience context menu is provided with the following actions:

• New Stop - creates a new gradient stop
• Delete - removes the active and all selected stops
• Flip All - mirrors all stops
• Select All - selects all stops
• Zoom In - zooms in
• Zoom Out - zooms out
• Zoom All - goes back to original 100% zoom

The bottom part of the QtGradientDialog contains a set of widgets allowing to control the color of the active and selected stops.

The color button shows the color of the active gradient stop. It also allows for choosing a color from standard color dialog and applying it to the active stop and all selected stops. It's also possible to drag a color directly from the color button and to drop it in gradient stops editor at desired position (it will create new stop with dragged color) or at desired stop handle (it will change the color of that handle).

To the right of color button there is a set of 2 radio buttons which allows to switch between HVS and RGB color spec.

Finally there are 4 color sliders working either in HSVA (hue saturation value alpha) or RGBA (red green blue alpha) mode, depending on which radio button is chosen. The radio buttons can be controlled programatically by spec() and setSpec() methods. The sliders show the color of the active stop. By double clicking inside color slider you can set directly the desired color. Changes of slider's are applied to stop selection in the way that the color component being changed is applied to stops in selection only, while other components remain unchanged in selected stops (e.g. when the user is changing the saturation, new saturation is applied to selected stops preventing original hue, value and alpha in multiselection).

The convenient static functions getGradient() provide modal gradient dialogs, e.g.:

     bool ok;
     QGradient gradient = QtGradientDialog::getGradient(&ok, QRadialGradient(), this);
     if (ok) {
         // the user clicked OK and gradient is set to the gradient the user selected
     } else {
         // the user canceled the dialog; gradient is set to the initial
         // value, in this case radial gradient
     }

In order to have more control over the properties of QtGradientDialog use standard QDialog::exec() method:

     bool detailsVisible;
     QColor::Spec spec;
     QGradient gradient;

     QtGradientDialog dlg(this);
     dlg.setDetailsVisible(detailsVisible);
     dlg.setSpec(spec);
     dlg.setGradient(gradient);
     if (dlg.exec() != QDialog::Accepted)
         return;

     gradient = dlg.gradient();
     // detailsVisible and spec properties can be changed interactively by the user too,
     // we store the values of these properties for the next time QtGradientDialog is executed.
     detailsVisible = dlg.detailsVisible();
     spec = dlg.spec();